---
title: "Execute a command"
method: POST
path: "/v2/sandboxes/sessions/{sessionId}/cmd"
tags: ["sandboxes"]
---

# Execute a command

`POST /v2/sandboxes/sessions/{sessionId}/cmd`

## Request

- Base URL: `https://api.vercel.com`
- URL: `https://api.vercel.com/v2/sandboxes/sessions/{sessionId}/cmd`
- Auth: HTTP bearer

Executes a shell command inside a running session. The command runs asynchronously and returns immediately with a command ID that can be used to track its progress and retrieve its output. Optionally, use the `wait` parameter to stream the command status until completion.

## Path parameters

- `sessionId` string, required: The unique identifier of the session in which to execute the command.

## Query parameters

- `teamId` string
- `slug` string

## Request body

- object
  - `command` string, required: The executable or shell command to run. This is the program name without arguments.
  - `args` string[]: Arguments to pass to the command. Each argument should be a separate array element.
  - `cwd` string: The working directory in which to execute the command. Defaults to the sandbox home directory if not specified.
  - `env` object: Additional environment variables to set for this command. These are merged with the sandbox environment.
  - `sudo` boolean: Execute the command with root (superuser) privileges.
  - `wait` boolean: If true, returns an ND-JSON stream that emits the command status when started and again when finished. Useful for synchronously waiting for command completion.
  - `logs` boolean: If true, stream the logs of the command execution in real-time via ND-JSON. This is only applicable if `wait` is also true.
  - `timeout` integer: Maximum duration in milliseconds the command may run before it is killed with SIGKILL, up to 5 hours. Enforced at exec time, independently of `wait`.
  - `attachStdin` boolean: If true, keeps the command stdin open so it can be written to with the stdin endpoint while the command runs. When false, the command reads from an empty stdin.

## Response `200`

- object
  - `command` SessionCommand, required: This object represents a command run in a Vercel Sandbox session (v2 API).
    - `args` string[], required: The arguments of the command.
    - `cwd` string, required: The current working directory of the command.
    - `durationMs` number: Duration of the command execution in milliseconds.
    - `exitCode` number, nullable, required: If the command did finish, the exit code.
    - `id` string, required: The ID of the command.
    - `name` string, required: The name of the command.
    - `sessionId` string, required: The ID of the session associated with the command.
    - `startedAt` number, required: When the command was started, in milliseconds since the epoch.

## Other responses

- `400`: One of the provided values in the request body is invalid. One of the provided values in the request query is invalid.
- `401`: The request is not authorized.
- `403`: You do not have permission to access this resource.
- `404`
- `410`
- `422`
- `429`

## Changes

- **2026-10-23** `0ab54ee1bd2e`: 1 info
  - removed the non-success response with the status `500`
- **2026-10-19** `f4083d759e58`: 1 warning, 1 info
  - deleted the `query` request parameter `cmdId`
  - removed `subschema #3` from the response body `oneOf` list for the response status `200`
- **2026-10-10** `32399b3ed273`: 1 info
  - added the new optional request property `attachStdin`
- **2026-08-18** `4a14567fe836`: 1 warning
  - the `timeout` request property's max was set to `18000000.00`
- **2026-07-08** `3ff660568354`: 2 info
  - added the optional property `command/durationMs` to the response with the `200` status (media type: application/json)
  - added the optional property `oneOf[subschema #2]/command/durationMs` to the response with the `200` status (media type: application/x-ndjson)

[Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v2/sandboxes/sessions/:sessionId/cmd/post.md)

---

[API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)