> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt > Use this file to discover all available pages before exploring further. # Spawn a new container instance > 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. ## OpenAPI ````yaml https://eu-north.nebius.computer/static/api.yaml post /instances openapi: 3.0.0 info: title: Contree API description: > Contree is a container management system combining virtual machine isolation with container operational efficiency. Designed for security-sensitive workloads requiring hardware-enforced boundaries while maintaining container workflow compatibility. version: 1.0.0 servers: - url: '{baseUrl}/v1' description: | Nebius IAM-fronted endpoint (use `IAMBearerAuth` + `IAMProjectHeader`). Override `baseUrl` to point at a different deployment. variables: baseUrl: default: https://api.tokenfactory.nebius.com/sandboxes description: | Base URL of the contree service. Defaults to the public Nebius IAM-fronted endpoint; set to your self-hosted contree origin (e.g. `https://contree.example.com`) when running elsewhere. security: - IAMBearerAuth: [] IAMProjectHeader: [] tags: - name: images description: Operations related to container images - name: files description: Operations related to file uploads - name: instances description: Operations related to container instances - name: inspect description: Operations related to inspecting container images - name: operations description: Operations related to long-running operations - name: auth description: Authentication and token introspection paths: /instances: post: tags: - instances summary: Spawn a new container instance description: > 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. operationId: spawnInstance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceSpawnRequest' responses: '201': description: > 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. headers: Location: schema: type: string description: URL to check the operation status example: /v1/operations/12345678-9abc-baba-deda-0123456789ab content: application/json: schema: $ref: '#/components/schemas/InstanceSpawnResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: InstanceSpawnRequest: type: object required: - command - image properties: command: type: string description: > 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`. example: /bin/app disposable: type: boolean description: >- Creates a disposable execution environment no any state will be saved. default: false hostname: type: string description: Hostname to set when execution. example: container-name default: linuxkit image: $ref: '#/components/schemas/ImageSource' args: type: array items: type: string description: | Arguments to pass to the command if shell is set to false. example: - arg1 - arg2 default: [] shell: type: boolean description: > 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. default: false env: nullable: true type: object additionalProperties: type: string description: > 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. example: KEY1: value1 KEY2: value2 preserve_env: type: boolean description: > 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. default: false cwd: type: string pattern: ^((/[^/]*)+/?)?$ description: > 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. example: /app default: '' uid: type: integer minimum: 0 description: User ID to run the process as. example: 0 default: 0 gid: type: integer minimum: 0 description: Group ID to run the process as. example: 0 default: 0 resources_limits: $ref: '#/components/schemas/InstanceResourcesLimits' stdin: $ref: '#/components/schemas/StreamRepr' timeout: type: integer description: Maximum execution time in seconds example: 60 truncate_output_at: type: integer description: > Maximum number of bytes to keep from stdout/stderr. Default is `1048576` (1 MiB). The maximum value is `10485760` (10 MiB). example: 65535 default: 1048576 files: type: object description: Map of absolute file paths to file metadata additionalProperties: type: object properties: uuid: $ref: '#/components/schemas/UUIDSchema' uid: type: integer description: User ID example: 0 gid: type: integer description: Group ID example: 0 mode: type: string description: File mode in octal format (e.g., "0644") example: '0644' example: /root/hello.txt: uuid: a9165a5d-5c86-4bd8-8ee4-ae46c19cf45d uid: 0 gid: 0 mode: '0644' /tmp/log.txt: uuid: 065def2a-e977-4852-8b26-a0ec05e85a90 uid: 1000 gid: 1000 mode: '0600' InstanceSpawnResponse: type: object properties: uuid: $ref: '#/components/schemas/UUIDSchema' command: type: string image: $ref: '#/components/schemas/UUIDSchema' hostname: type: string args: type: array items: type: string shell: type: boolean env: nullable: true type: object additionalProperties: type: string preserve_env: type: boolean cwd: type: string uid: type: integer gid: type: integer resources_limits: $ref: '#/components/schemas/InstanceResourcesLimits' stdin: $ref: '#/components/schemas/StreamRepr' timeout: type: integer truncate_output_at: type: integer disposable: type: boolean files: type: object additionalProperties: type: object properties: uuid: $ref: '#/components/schemas/UUIDSchema' uid: type: integer gid: type: integer mode: type: string result: nullable: true allOf: - $ref: '#/components/schemas/InstanceResult' ImageSource: oneOf: - $ref: '#/components/schemas/UUIDSchema' - $ref: '#/components/schemas/ImageSourceTag' description: > 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. example: tag:busybox:latest InstanceResourcesLimits: type: object properties: max_layer_bytes: type: integer minimum: 1 description: Maximum writable layer size in bytes. example: 1073741824 default: 12884901888 StreamRepr: type: object required: - value - encoding properties: value: type: string description: Content of the stream example: Y29tbWFuZCBvdXRwdXQK encoding: type: string enum: - ascii - base64 description: Encoding of the content example: base64 truncated: type: boolean description: Whether the output was truncated example: false UUIDSchema: type: string format: uuid description: A UUID string example: 12345678-9abc-baba-deda-0123456789ab InstanceResult: type: object description: Result of an instance execution properties: resources: type: object properties: block_input: type: integer description: Block input operations block_output: type: integer description: Block output operations cost: type: number format: float description: Operation cost elapsed_time: type: number description: Elapsed wall time involuntary_switches: type: integer description: Number of involuntary context switches max_rss: type: integer description: Maximum resident set size in KB monotonic_time: type: number format: float description: Monotonic time measurement page_faults: type: integer description: Number of page faults page_faults_io: type: integer description: Number of page faults requiring I/O shared_memory: type: integer description: Shared memory size signals: type: integer description: Number of signals received swaps: type: integer description: Number of swaps system_cpu_time: type: number format: float description: System CPU time used unshared_memory: type: integer description: Unshared memory size user_cpu_time: type: number format: float description: User CPU time used voluntary_switches: type: integer description: Number of voluntary context switches state: type: object properties: continued: type: boolean description: Whether the process was continued from a stop core_dump: type: boolean description: Whether a core dump was generated exit_code: type: integer description: Process exit code pid: type: integer description: Process ID signal: type: integer description: Signal that caused termination, if any stopped: type: boolean description: Whether the process was stopped timed_out: type: boolean description: >- Whether process had been killed because operation timeout was reached stdout: $ref: '#/components/schemas/StreamRepr' stderr: $ref: '#/components/schemas/StreamRepr' Error: type: object required: - error properties: error: oneOf: - type: string - type: object - type: array items: type: object description: Error message or structured validation errors example: Some error occurred, this is an example of error message status: type: integer description: HTTP status code example: 500 traceback: type: array items: type: string ImageSourceTag: type: string description: > A container image tag. String must be started with a prefix "tag:" followed by the actual tag. pattern: ^tag:[A-Za-z0-9][A-Za-z0-9_-]*(?:[:/.][A-Za-z0-9_-]+)*$ example: tag:busybox:latest responses: BadRequest: description: Bad Request - Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: | Unauthorized - Invalid or missing authentication credentials. Either the `Authorization` bearer token is missing or invalid, or the `Project` header is missing. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden - Token does not have sufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: IAMBearerAuth: type: http scheme: bearer bearerFormat: IAM description: | IAM bearer token issued by the Nebius IAM service. Sent as `Authorization: Bearer `. Must be combined with the `Project` header (see `IAMProjectHeader`). This is the recommended authentication scheme for new clients. IAMProjectHeader: type: apiKey in: header name: Project description: | Nebius project ID associated with the IAM token. Required together with `IAMBearerAuth`. Identifies the project context the request is scoped to. ````