---
title: "Start a command"
method: POST
path: "/v1/sessions/{id}/executions"
---

# Start a command

`POST /v1/sessions/{id}/executions`

## Request

- Base URL: `https://assemble-vms-api.fly.dev`
- URL: `https://assemble-vms-api.fly.dev/v1/sessions/{id}/executions`
- Auth: HTTP bearer

Start an asynchronous managed command. The session must be running and may have only one running managed execution. An active provided-agent request reserves the session and blocks external commands. Preserve the returned ID for reconnect or cancellation. Commands mutate the shared session directly. Failed or cancelled commands may leave partial file changes; successful process exit does not establish that every write was flushed durably.

## Request body

- Execute
  - `command` string, required
  - `cwd` string: Working directory within /workspace; defaults to /workspace.
  - `timeoutSeconds` integer
  - `env` object: Per-command guest environment overrides; names must match ^[A-Za-z_][A-Za-z0-9_]*$.

## Response `202`

Execution accepted.

- Execution
  - `id` string, uuid, required
  - `sessionId` string, uuid, required
  - `state` 'running' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'interrupted', required
  - `exitCode` integer, nullable, required
  - `createdAt` string, date-time, required
  - `finishedAt` string, date-time, nullable, required

## Other responses

- `default`: Structured API error. HTTP 400 invalid request, 401 authentication, 404 missing resource, 409 conflict, 413 size limit, 429 quota, or 503 unavailable.

---

[API](https://skmtc.dev/assemble/apis/assemble-vms-api.md) - [All operations](https://skmtc.dev/assemble/apis/assemble-vms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/assemble/apis/assemble-vms-api/revisions/93f55a2e3de3?raw)