Error

A valid request URL is required to generate request examples

{
  "uuid": "12345678-9abc-baba-deda-0123456789ab",
  "command": "<string>",
  "image": "12345678-9abc-baba-deda-0123456789ab",
  "hostname": "<string>",
  "args": [
    "<string>"
  ],
  "shell": true,
  "env": {},
  "preserve_env": true,
  "cwd": "<string>",
  "uid": 123,
  "gid": 123,
  "resources_limits": {
    "max_layer_bytes": 1073741824
  },
  "stdin": {
    "value": "Y29tbWFuZCBvdXRwdXQK",
    "encoding": "base64",
    "truncated": false
  },
  "timeout": 123,
  "truncate_output_at": 123,
  "disposable": true,
  "files": {},
  "result": {
    "resources": {
      "block_input": 123,
      "block_output": 123,
      "cost": 123,
      "elapsed_time": 123,
      "involuntary_switches": 123,
      "max_rss": 123,
      "monotonic_time": 123,
      "page_faults": 123,
      "page_faults_io": 123,
      "shared_memory": 123,
      "signals": 123,
      "swaps": 123,
      "system_cpu_time": 123,
      "unshared_memory": 123,
      "user_cpu_time": 123,
      "voluntary_switches": 123
    },
    "state": {
      "continued": true,
      "core_dump": true,
      "exit_code": 123,
      "pid": 123,
      "signal": 123,
      "stopped": true,
      "timed_out": true
    },
    "stdout": {
      "value": "Y29tbWFuZCBvdXRwdXQK",
      "encoding": "base64",
      "truncated": false
    },
    "stderr": {
      "value": "Y29tbWFuZCBvdXRwdXQK",
      "encoding": "base64",
      "truncated": false
    }
  }
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

instances

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.

POST

instances

Error

A valid request URL is required to generate request examples

{
  "uuid": "12345678-9abc-baba-deda-0123456789ab",
  "command": "<string>",
  "image": "12345678-9abc-baba-deda-0123456789ab",
  "hostname": "<string>",
  "args": [
    "<string>"
  ],
  "shell": true,
  "env": {},
  "preserve_env": true,
  "cwd": "<string>",
  "uid": 123,
  "gid": 123,
  "resources_limits": {
    "max_layer_bytes": 1073741824
  },
  "stdin": {
    "value": "Y29tbWFuZCBvdXRwdXQK",
    "encoding": "base64",
    "truncated": false
  },
  "timeout": 123,
  "truncate_output_at": 123,
  "disposable": true,
  "files": {},
  "result": {
    "resources": {
      "block_input": 123,
      "block_output": 123,
      "cost": 123,
      "elapsed_time": 123,
      "involuntary_switches": 123,
      "max_rss": 123,
      "monotonic_time": 123,
      "page_faults": 123,
      "page_faults_io": 123,
      "shared_memory": 123,
      "signals": 123,
      "swaps": 123,
      "system_cpu_time": 123,
      "unshared_memory": 123,
      "user_cpu_time": 123,
      "voluntary_switches": 123
    },
    "state": {
      "continued": true,
      "core_dump": true,
      "exit_code": 123,
      "pid": 123,
      "signal": 123,
      "stopped": true,
      "timed_out": true
    },
    "stdout": {
      "value": "Y29tbWFuZCBvdXRwdXQK",
      "encoding": "base64",
      "truncated": false
    },
    "stderr": {
      "value": "Y29tbWFuZCBvdXRwdXQK",
      "encoding": "base64",
      "truncated": false
    }
  }
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

{
  "error": "Some error occurred, this is an example of error message",
  "status": 500,
  "traceback": [
    "<string>"
  ]
}

Authorizations

Authorization

string

header

required

IAM bearer token issued by the Nebius IAM service. Sent as Authorization: Bearer <iam-token>. Must be combined with the Project header (see IAMProjectHeader).

This is the recommended authentication scheme for new clients.

Project

string

header

required

Nebius project ID associated with the IAM token. Required together with IAMBearerAuth. Identifies the project context the request is scoped to.

Body

application/json

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.

Example:

"/bin/app"

image

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.

Example:

"tag:busybox:latest"

disposable

boolean

default:false

Creates a disposable execution environment no any state will be saved.

hostname

string

default:linuxkit

Hostname to set when execution.

Example:

"container-name"

args

string[]

Arguments to pass to the command if shell is set to false.

Example:

["arg1", "arg2"]

shell

boolean

default:false

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 | null

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.

Show child attributes

Example:

{ "KEY1": "value1", "KEY2": "value2" }

preserve_env

boolean

default:false

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

default:""

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.

Pattern: ^((/[^/]*)+/?)?$

Example:

"/app"

uid

integer

default:0

User ID to run the process as.

Required range: x >= 0

Example:

0

gid

integer

default:0

Group ID to run the process as.

Required range: x >= 0

Example:

0

resources_limits

object

Show child attributes

stdin

object

Show child attributes

timeout

integer

Maximum execution time in seconds

Example:

60

truncate_output_at

integer

default:1048576

Maximum number of bytes to keep from stdout/stderr. Default is 1048576 (1 MiB). The maximum value is 10485760 (10 MiB).

Example:

65535

files

object

Map of absolute file paths to file metadata

Show child attributes

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"
  }
}

Response

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.

uuid

string<uuid>

A UUID string

Example:

"12345678-9abc-baba-deda-0123456789ab"

command

string

image

string<uuid>

A UUID string

Example:

"12345678-9abc-baba-deda-0123456789ab"

hostname

string

args

string[]

shell

boolean

env

object | null

Show child attributes

preserve_env

boolean

cwd

string

uid

integer

gid

integer

resources_limits

object

Show child attributes

stdin

object

Show child attributes

timeout

integer

truncate_output_at

integer

disposable

boolean

files

object

Show child attributes

result

object | null

Result of an instance execution

Show child attributes

Check if a file exists for the current namespace List operations

⌘I

API Documentation

Inference and Training

Sandboxes

Spawn a new container instance

Authorizations

Body

Response