v1

latestOpenAPI 3.1.02026-07-2675394318.9 KB

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

Request body

commandstring 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.

disposableboolean

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

hostnamestring

Hostname to set when execution.

argsstring[]

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

shellboolean

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.

envobject 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_envboolean

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.

cwdstring

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.

uidinteger

User ID to run the process as.

gidinteger

Group ID to run the process as.

timeoutinteger

Maximum execution time in seconds

truncate_output_atinteger

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

filesobject

Map of absolute file paths to file metadata

Example request

{
  "command": "/bin/app",
  "hostname": "container-name",
  "image": "12345678-9abc-baba-deda-0123456789ab",
  "args": [
    "arg1",
    "arg2"
  ],
  "env": {
    "KEY1": "value1",
    "KEY2": "value2"
  },
  "cwd": "/app",
  "resources_limits": {
    "max_layer_bytes": 1073741824
  },
  "stdin": {
    "value": "aGVsbG8K"
  },
  "timeout": 60,
  "truncate_output_at": 65535,
  "files": {
    "/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.

uuidstring uuid

A UUID string

commandstring

imagestring uuid