> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run commands in a sandbox

> Run a command in a sandbox, stream its output, send stdin, reattach to a detached command, and kill a command.

Run a command in a running sandbox and read its output while it runs. A command has no time limit unless you set one.

Write the code that runs a command in a sandbox.

Use POST /v1/sandboxes/{id}/commands to run a command in a running sandbox.
Read the NDJSON stream line by line and skip empty lines.
Use detached: true for a long command, and read its output again with GET /v1/sandboxes/{id}/commands/{commandId}/events?after=N, where N is the last seq that you read.
Do not ask me to share my API key.

## Before you start

* You need an API key with the `sandboxes:exec` scope. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The sandbox must be `running`. See [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md).

## Run a command

Send `POST /v1/sandboxes/{id}/commands` with a `command`:

* A string runs with `bash -lc`, for example `"npm test"`.
* A list runs the program with its arguments, for example `["ls", "-la"]`.

The answer is a stream of JSON lines (NDJSON) that ends when the command exits.

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/commands`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ command: "npm test", cwd: "/home/user/app" }),
  },
);

const decoder = new TextDecoder();
let buffered = "";

for await (const bytes of response.body!) {
  buffered += decoder.decode(bytes, { stream: true });
  const lines = buffered.split("\n");
  buffered = lines.pop() ?? "";

  for (const line of lines) {
    if (!line) continue;

    const event = JSON.parse(line);

    if (event.type === "stdout") process.stdout.write(event.data);
    if (event.type === "stderr") process.stderr.write(event.data);
    if (event.type === "exit") console.log("exit code", event.exitCode);
  }
}
```

```bash cURL theme={null}
curl -N https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/commands \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "npm test", "cwd": "/home/user/app"}'
```

### Events in the stream

Each line is one event. Each event has a `seq` that starts at 0.

| Type | Fields | Meaning |
| - | - | - |
| `started` | `commandId`, `pid`, `at` | The command started. Keep `commandId` to send stdin, read the output again, or kill the command. |
| `stdout` | `data`, `encoding` | Output on stdout. |
| `stderr` | `data`, `encoding` | Output on stderr. |
| `exit` | `exitCode`, `signal`, `oomKilled`, `timedOut`, `at` | The command exited. This is the last event. |

* `encoding` is `utf8` for text, and `base64` for bytes that are not valid UTF-8.
* When no event comes for 15 seconds, the stream sends an empty line, so that proxies keep the connection open. Skip empty lines.
* If you disconnect before the `exit` event, the command gets `SIGKILL`. To keep a command running, use a [detached command](#run-a-detached-command).

```text theme={null}
{"type":"started","seq":0,"at":"2026-11-16T02:10:00.000Z","commandId":"cmd_06d8k3m7q2v9x4b1n5c0e8f2jd","pid":412}
{"type":"stdout","seq":1,"data":"12 tests passed\n","encoding":"utf8"}
{"type":"exit","seq":2,"at":"2026-11-16T02:10:04.000Z","exitCode":0,"signal":null,"oomKilled":false,"timedOut":false}
```

### Set the folder, the environment, and a time limit

| Field | Value |
| - | - |
| `cwd` | The working folder, as an absolute path. The default is the home folder of root. |
| `env` | Environment variables for this command, such as `{"NODE_ENV": "test"}`. |
| `timeoutSeconds` | The time limit in seconds. At the limit, the command gets `SIGKILL` and `exit` has `timedOut: true`. Leave it out or send `null` for no time limit. |

## Send stdin

Start the command with `"stdin": true`. Then send `POST /v1/sandboxes/{id}/commands/{commandId}/stdin` with `data`. Send `"eof": true` to close stdin. The answer is `204`.

```typescript TypeScript theme={null}
await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/commands/${commandId}/stdin`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ data: "yes\n" }),
  },
);
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/commands/cmd_06d8k3m7q2v9x4b1n5c0e8f2jd/stdin \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": "yes\n"}'
```

Send `"encoding": "base64"` for bytes that are not text. Stdin to a command that exited answers `409`.

## Run a detached command

Send `"detached": true` for a long command, such as a dev server or a build. The API answers `201` with the command at once, and the command runs after you disconnect.

```json theme={null}
{
  "id": "cmd_06d8k3m7q2v9x4b1n5c0e8f2jd",
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "argv": ["bash", "-lc", "npm run dev"],
  "cwd": "/home/user/app",
  "status": "running",
  "pid": 412,
  "detached": true,
  "startedAt": "2026-11-16T02:10:00.000Z",
  "exitedAt": null,
  "exitCode": null,
  "signal": null,
  "oomKilled": false,
  "timedOut": false,
  "lastSeq": 0
}
```

Read the output with `GET /v1/sandboxes/{id}/commands/{commandId}/events`. Send `?after=N` to get only the events with a `seq` above N, for example after a disconnect. The stream ends at the `exit` event. You can read the events of a command again after it exits.

```typescript TypeScript theme={null}
const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/commands/${commandId}/events?after=${lastSeq}`,
  { headers: { Authorization: `Bearer ${process.env.VMS_API_KEY}` } },
);
```

```bash cURL theme={null}
curl -N "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/commands/cmd_06d8k3m7q2v9x4b1n5c0e8f2jd/events?after=12" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

The sandbox keeps the newest 4 MiB of events of each command. If you ask for older events, the stream starts at the oldest kept event.

## List, get, and kill commands

| Request | Answer |
| - | - |
| `GET /v1/sandboxes/{id}/commands` | The commands of the sandbox, the newest first. |
| `GET /v1/sandboxes/{id}/commands/{commandId}` | One command, with its `status` and its exit result. |
| `DELETE /v1/sandboxes/{id}/commands/{commandId}` | Kills the command and returns it. |

A kill sends `SIGKILL`. Send `?signal=SIGTERM` for a different signal: `SIGTERM`, `SIGINT`, `SIGHUP`, `SIGQUIT`, `SIGUSR1`, or `SIGUSR2`. The answer comes when the command exits, or after 5 seconds. After the exit, `signal` has the signal.

If a command runs out of memory, the command gets `SIGKILL` and `oomKilled` is `true`. Use a bigger [size](https://vms.dev/docs/reference/plans.md#sandbox-sizes) for this command.

The sandbox keeps each running command and its 25 newest exited commands. A restart of the sandbox removes the list.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `401` | `unauthenticated` | The API key is missing, not correct, revoked, or expired. |
| `403` | `forbidden` | The API key does not have the `sandboxes:exec` scope. |
| `404` | `not_found` | The workspace has no sandbox with this ID, or the sandbox has no command with this ID. |
| `409` | `sandbox_not_running` | The sandbox is not running. Start it, then try again. |
| `409` | `sandbox_starting` | The sandbox is starting. Try again when it is `running`. |
| `409` | `sandbox_stopping` | The sandbox is stopping. |
| `409` | `conflict` | The command exited, so it cannot get stdin. |
| `503` | `unavailable` | The sandbox did not answer. Try again. |

A revoked API key can work for 30 more seconds on these endpoints.

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.