---
title: "Exec Command"
method: POST
path: "/sandboxes/{sandbox_id}/exec"
---

# Exec Command

`POST /sandboxes/{sandbox_id}/exec`

Run a command inside a sandbox and return its result.

Resolves the sandbox (reconnecting on a registry miss), then runs
the command over the facade's cached SSH channel.

## Path parameters

- `sandbox_id` string, required

## Request body

- ExecRequest — Request body for running a command inside a sandbox. Mirrors the arguments of :meth:`smolvm.SmolVM.run`.
  - `command` string, required — Shell command to execute in the sandbox.
  - `timeout` integer — Maximum seconds to wait for the command to finish.
  - `shell` 'login' | 'raw' — 'login' runs via the guest login shell; 'raw' executes the command directly with no shell wrapping.

## Response `200`

Successful Response

- ExecResponse — The result of a command run inside a sandbox. Reuses the engine's :class:`~smolvm.types.CommandResult` (exit code, stdout, stderr) under an API-owned name so the generated SDKs expose a stable ``ExecResponse`` type rather than an engine-internal one.
  - `exit_code` integer, required
  - `stdout` string, required
  - `stderr` string, required

## Other responses

- `404` — No sandbox with that id exists on the host.
- `409` — The sandbox could not be reconnected, or the command could not run.
- `422` — Validation Error

## Changes

- **2026-06-16** `7d061924484c` — 1 info
  - endpoint added
- **2026-06-16** `5006f0bc478e` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/celestoai/apis/smolvm/changes/sandboxes/:sandbox_id/exec/post.md)

---

[API](https://skmtc.dev/celestoai/apis/smolvm.md) · [All operations](https://skmtc.dev/celestoai/apis/smolvm/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/celestoai/smolvm/revisions/ad347836d68f/schema)