---
title: "Spawn an additional subprocess inside a running instance"
method: POST
path: "/operations/{operationId}/subprocesses"
tags: ["operation"]
---

# Spawn an additional subprocess inside a running instance

`POST /operations/{operationId}/subprocesses`

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.

## Path parameters

- `operationId` string, uuid, required — A UUID string

## Request body

- ExecSpec — Process-execution surface shared between `InstanceSpawnRequest` (the main process) and `POST /operations/{operationId}/subprocesses` (additional subprocesses). VM-level concerns (image, hostname, resources_limits, files, timeout, disposable, preserve_env) live on `InstanceSpawnRequest` only.
  - `command` string, 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.
  - `args` string[] — Arguments to pass to the command if shell is set to false.
  - `shell` boolean — Run command through a shell expression (args must be empty).
  - `env` object, nullable — Environment variables to set in the child process.
  - `cwd` string — Working directory; empty string means image / server default.
  - `uid` integer — User ID to run the process as.
  - `gid` integer — Group ID to run the process as.
  - `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`.
  - `truncate_output_at` integer — Maximum number of bytes of stdout / stderr to keep. Defaults to 1 MiB; capped at 10 MiB.

## Response `201`

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

- object
  - `spid` integer, required — Spawn id assigned by the worker.

## 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
- `404` — Not Found - The requested resource does not exist
- `409` — Conflict — the operation exists but is not an instance, or is not currently EXECUTING / ASSIGNED.
- `425` — Too Early (RFC 8470) — the VM is not ready to accept the exec yet: no worker holds the operation, or the guest control channel is still coming up. Retry after `Retry-After`.
- `504` — Gateway Timeout — the guest accepted the connection but the spawn call didn't return in time. The subprocess MAY have started anyway; do not blind-retry — inspect `GET /events` for a `spawn` event first.

---

[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)