---
title: "Spawn a new container instance"
method: POST
path: "/instances"
tags: ["instances"]
---

# Spawn a new container instance

`POST /instances`

Creates and runs a new execution instance with the specified configuration. 
Requires a valid `Authorization` header.

Common request body rules:

  * The request body must contain at least `command` and `image` fields all other fields can be omitted.
  * If the `command` field is a shell expression, you must set `shell` field to `true`.
  * For specifying the shell binary, you can use `env` field to set `SHELL` variable.
  * When `shell` is `true`, environment variables defined in the image (via `ENV` directives) are
    automatically inherited. When `shell` is `false`, image environment variables are not inherited
    and must be passed explicitly via the `env` field.

## Request body

- InstanceSpawnRequest
  - `command` string, required — The command to execute. In case if `shell` is set to `true`, this MUST contain shell expression. For example `echo hello world` or `ls -l /app`. If `shell` is set to `false`, this must be a relative or absolute path to the executable inside the image rootfs. For example: `/bin/app` or `/usr/bin/find`. Do not forget pass necessary `PATH` variable to env field, by default `PATH` is set to `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`.
  - `disposable` boolean — Creates a disposable execution environment no any state will be saved.
  - `hostname` string — Hostname to set when execution.
  - `image` union, required — An base image for run a new instance. May be either image UUID or image tag (prefixed with "tag:"). After creation of the instance, if tag is used, this value will be resolved to the image UUID, and the UUID will be stored in the metadata.
    - string, uuid — A UUID string
    - string — A container image tag. String must be started with a prefix "tag:" followed by the actual tag.
  - `args` string[] — Arguments to pass to the command if shell is set to false.
  - `shell` boolean — Whether to run the command through a shell. If `true`, the command must be a shell expression and all values from args will be ignored. If `false`, the command field must be a path to an executable and args will be used. When `true`, environment variables from the image are automatically inherited. When `false`, they are not - use the `env` field to pass them explicitly.
  - `env` object, nullable — Environment variables to set in the container. These are merged with image-defined variables when `shell` is `true`. When `shell` is `false`, only variables specified here are available - image-defined variables are not inherited.
  - `preserve_env` boolean — Preserve environment variables in resulting image after execution. When `true`, the image's existing environment variables from `metadata/env` are merged with user-provided `env` values (user values take priority on conflicts), and the combined result is written back to `metadata/env` after command execution. Setting a variable to an empty string or `null` removes it from the preserved environment.
  - `cwd` string — Path to the working directory, must be absolute or a special value the empty string. It means the default working directory of the image or server default will be used. If field is omitted it will be set to the empty string. The directory will be created automatically if it does not exist.
  - `uid` integer — User ID to run the process as.
  - `gid` integer — Group ID to run the process as.
  - `resources_limits` InstanceResourcesLimits
    - `max_layer_bytes` integer — Maximum writable layer size in bytes.
  - `networking` InstanceNetworking
    - `enabled` boolean — Enable network access for the instance. When `false`, the VM starts without a guest network interface.
  - `stdin` ClosableStreamRepr — Stdin payload. Unlike output streams it is never truncated; instead it carries a `close` flag controlling the pipe's EOF.
    - `value` string, required — Content to write to stdin (may be empty for a close-only request)
    - `encoding` 'ascii' | 'base64' — Encoding of the content
    - `close` boolean — `true` (default) closes stdin (EOF) after writing `value` — the pre-existing one-shot behavior. `false` keeps the pipe open so more data can be sent later via `POST /operations/{operationId}/subprocesses/{spid}/stdin`.
  - `timeout` integer — Maximum execution time in seconds
  - `truncate_output_at` integer — Maximum number of bytes to keep from stdout/stderr. Default is `1048576` (1 MiB). The maximum value is `10485760` (10 MiB).
  - `files` object — Map of absolute file paths to file metadata

## Response `201`

Created - The instance has been successfully created and its execution has been queued. When operation created successfully, the response will contain `Location` header with URL to check the operation status. and the body will contain the parsed request body with additional `uuid` field.

- InstanceSpawnResponse
  - `uuid` string, uuid — A UUID string
  - `command` string
  - `image` string, uuid — A UUID string
  - `hostname` string
  - `args` string[]
  - `shell` boolean
  - `env` object, nullable
  - `preserve_env` boolean
  - `cwd` string
  - `uid` integer
  - `gid` integer
  - `resources_limits` InstanceResourcesLimits
    - `max_layer_bytes` integer — Maximum writable layer size in bytes.
  - `networking` InstanceNetworking
    - `enabled` boolean — Enable network access for the instance. When `false`, the VM starts without a guest network interface.
  - `stdin` ClosableStreamRepr — Stdin payload. Unlike output streams it is never truncated; instead it carries a `close` flag controlling the pipe's EOF.
    - `value` string, required — Content to write to stdin (may be empty for a close-only request)
    - `encoding` 'ascii' | 'base64' — Encoding of the content
    - `close` boolean — `true` (default) closes stdin (EOF) after writing `value` — the pre-existing one-shot behavior. `false` keeps the pipe open so more data can be sent later via `POST /operations/{operationId}/subprocesses/{spid}/stdin`.
  - `timeout` integer
  - `truncate_output_at` integer
  - `disposable` boolean
  - `files` object
  - `result` InstanceResult — Result of an instance execution
    - `resources` object
      - `block_input` integer — Block input operations
      - `block_output` integer — Block output operations
      - `cost` number, float — Operation cost
      - `elapsed_time` number — Elapsed wall time
      - `involuntary_switches` integer — Number of involuntary context switches
      - `max_rss` integer — Maximum resident set size in KB
      - `monotonic_time` number, float — Monotonic time measurement
      - `page_faults` integer — Number of page faults
      - `page_faults_io` integer — Number of page faults requiring I/O
      - `shared_memory` integer — Shared memory size
      - `signals` integer — Number of signals received
      - `swaps` integer — Number of swaps
      - `system_cpu_time` number, float — System CPU time used
      - `unshared_memory` integer — Unshared memory size
      - `user_cpu_time` number, float — User CPU time used
      - `voluntary_switches` integer — Number of voluntary context switches
    - `state` object
      - `continued` boolean — Whether the process was continued from a stop
      - `core_dump` boolean — Whether a core dump was generated
      - `exit_code` integer — Process exit code
      - `pid` integer — Process ID
      - `signal` integer — Signal that caused termination, if any
      - `stopped` boolean — Whether the process was stopped
      - `timed_out` boolean — Whether process had been killed because operation timeout was reached
    - `stdout` StreamRepr
      - `value` string, required — Content of the stream
      - `encoding` 'ascii' | 'base64', required — Encoding of the content
      - `truncated` boolean — Whether the output was truncated
    - `stderr` StreamRepr
      - `value` string, required — Content of the stream
      - `encoding` 'ascii' | 'base64', required — Encoding of the content
      - `truncated` boolean — Whether the output was truncated

## Other responses

- `400` — Bad Request - Invalid request parameters
- `401` — Unauthorized - Invalid or missing authentication credentials. Either the `Authorization` bearer token is missing or invalid, or the `Project` header is missing.
- `403` — Forbidden - Token does not have sufficient permissions

---

[API](https://skmtc.net/nebius/apis/nebius-openai-compatible-inference-api.md) · [All operations](https://skmtc.net/nebius/apis/nebius-openai-compatible-inference-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nebius/nebius-openai-compatible-inference-api/revisions/0fb323abba3c/schema)