---
title: "Execute a command asynchronously"
method: POST
path: "/process/spawn"
---

# Execute a command asynchronously

`POST /process/spawn`

## Request body

- ProcessSpawnRequest — Request to execute a command synchronously.
  - `command` string, required — Executable or shell command to run.
  - `args` string[] — Command arguments.
  - `cwd` string, nullable — Working directory (absolute path) to run the command in.
  - `env` object — Environment variables to set for the process.
  - `as_user` string, nullable — Run the process as this user.
  - `as_root` boolean — Run the process with root privileges.
  - `timeout_sec` integer, nullable — Maximum execution time in seconds.
  - `allocate_tty` boolean — Allocate a pseudo-terminal (PTY) for the process to enable interactive shells.
  - `rows` integer — Initial terminal rows when allocate_tty is true.
  - `cols` integer — Initial terminal columns when allocate_tty is true.

## Response `200`

Spawned

- ProcessSpawnResult — Information about a spawned process.
  - `process_id` string, uuid — Server-assigned identifier for the process.
  - `pid` integer — OS process ID.
  - `started_at` string, date-time — Timestamp when the process started.

## Other responses

- `400` — Bad Request
- `500` — Internal Server Error

## Changes

> 52 revisions in range; 4 could not be searched.

- **2025-12-31** `fdab5b26abe6` — 1 breaking
  - added `subschema #2` to the request body `allOf` list
- **2025-10-10** `3cb3697795bf` — 3 breaking
  - the request property `allOf[#/components/schemas/ProcessExecRequest]/as_user` became not nullable
  - the request property `allOf[#/components/schemas/ProcessExecRequest]/cwd` became not nullable
  - the request property `allOf[#/components/schemas/ProcessExecRequest]/timeout_sec` became not nullable
- **2025-08-28** `a491bfd480cd` — 2 warning
  - removed `subschema #2` from the request body `allOf` list
  - removed the request property `allOf[#/components/schemas/ProcessExecRequest]/stream`
- **2025-08-20** `e1658c618fd2` — 1 info
  - endpoint added
- **2025-06-27** `f980a92ab23f` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/kernel/apis/kernel-images-api/changes/process/spawn/post.md)

---

[API](https://skmtc.dev/kernel/apis/kernel-images-api.md) · [All operations](https://skmtc.dev/kernel/apis/kernel-images-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kernel/kernel-images-api/revisions/7a641fa15a85/schema)