v1

latestOpenAPI 3.1.02026-07-2675394318.9 KB

operation

Spawn an additional subprocess inside a running instance

Starts a new process inside the VM that already hosts the named operation. Distinct from POST /instances, which spins up a VM: this endpoint requires a running operation (EXECUTING or ASSIGNED) and reuses the existing VM.

The body is an ExecSpec — process-execution fields only. VM-level concerns (image, hostname, resources_limits, files, timeout, disposable, preserve_env) are not accepted here; they were set when the parent operation was created.

The required permission follows the parent instance: SPAWN_DISPOSABLE when it was spawned with disposable=true, SPAWN otherwise.

On success the worker assigns a fresh spid (≥2; spid=1 is the main process spawned from metadata) and the response carries it in the body plus a Location header pointing at GET /operations/{operationId}/subprocesses/{spid} — the subprocess result reconstructed from its events.

post/operations/{operationId}/subprocesses

Path parameters

operationIdstring uuid required

A UUID string

Example:12345678-9abc-baba-deda-0123456789ab

The ID of the operation

Request body

commandstring required

The command to execute. Same semantics as in InstanceSpawnRequest.command — when shell=true it is a shell expression, otherwise a path to an executable.

argsstring[]

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

shellboolean

Run command through a shell expression (args must be empty).

envobject nullable

Environment variables to set in the child process.

cwdstring

Working directory; empty string means image / server default.

uidinteger

User ID to run the process as.

gidinteger

Group ID to run the process as.

truncate_output_atinteger

Maximum number of bytes of stdout / stderr to keep. Defaults to 1 MiB; capped at 10 MiB.

Example request

{
  "command": "/bin/app",
  "args": [
    "arg1",
    "arg2"
  ],
  "stdin": {
    "value": "aGVsbG8K"
  },
  "truncate_output_at": 65535
}

Response

Created — subprocess started. Location references the new subprocess result.

spidinteger required

Spawn id assigned by the worker.