---
title: "Execute a command inside a VM"
method: POST
path: "/v1/vms/{id}/exec"
tags: ["exec"]
---

# Execute a command inside a VM

`POST /v1/vms/{id}/exec`

Runs a command via the VM's guest agent and returns stdout, stderr,
exit code, and timing. `timeoutSec` bounds server-side execution;
clients should set their own HTTP timeout in addition.

502 responses are transient (worker unreachable, worker-side timeout,
or worker 5xx — all collapsed into 502 at the scheduler). The SDK's
`run()` helper does NOT auto-retry these by default: exec is
**not idempotent** — if a 502 hides a successful exec, a retry may
run the command twice. Callers opt in with `max_retries=N` per call.

## Request body

- ExecVMRequest
  - `command` string[], required — Argv-style command. First element must be non-empty. For shell strings, wrap as `["sh", "-c", "<string>"]`.
  - `timeoutSec` integer — Server-side execution timeout in seconds. Must be positive when provided; omit to use the server default.

## Response `200`

Command result

- ExecVMResponse
  - `exitCode` integer, required
  - `stdout` string, required
  - `stderr` string, required
  - `timedOut` boolean, required
  - `stdoutTruncated` boolean, required
  - `stderrTruncated` boolean, required
  - `durationMs` integer, required

## Other responses

- `400` — Invalid request
- `401` — Missing or invalid credentials
- `404` — Resource not found
- `409` — VM is not running
- `500` — Internal server error
- `502` — Worker unreachable, worker HTTP 5xx, or worker-side timeout. Not retried by default (non-idempotent).

## Changes

- **2026-04-22** `fdb53b5a79b3` — 1 warning, 4 info
  - deleted the `path` request parameter `id`
  - api operation id `execVM` removed and replaced with `execVm`
  - api tag `exec` added
  - api tag `VMs` removed
  - …1 more

[Change history](https://skmtc.dev/fastvm-org/apis/fastvm-api/changes/v1/vms/:id/exec/post.md)

---

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