Sign in

v13

latestOpenAPI 3.0.32026-07-31359869.4 MB
sandboxes

Execute a command

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.

post/v2/sandboxes/sessions/{sessionId}/cmd

Path parameters

sessionIdstring required

The unique identifier of the session in which to execute the command.

Example:sbx_abc123

The unique identifier of the session in which to execute the command.

Query parameters

cmdIdstring required

The unique identifier of the command to stream logs for.

Example:cmd_abc123

The unique identifier of the command to stream logs for.

teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Request body

commandstring required

The executable or shell command to run. This is the program name without arguments.

argsstring[]

Arguments to pass to the command. Each argument should be a separate array element.

cwdstring

The working directory in which to execute the command. Defaults to the sandbox home directory if not specified.

envobject

Additional environment variables to set for this command. These are merged with the sandbox environment.

sudoboolean

Execute the command with root (superuser) privileges.

waitboolean

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.

logsboolean

If true, stream the logs of the command execution in real-time via ND-JSON. This is only applicable if wait is also true.

timeoutinteger

Maximum duration in milliseconds the command may run before it is killed with SIGKILL. Enforced at exec time, independently of wait.

Example request

{
  "command": "npm",
  "args": [
    "install",
    "--save",
    "lodash"
  ],
  "cwd": "/home/vercel-sandbox",
  "env": {
    "NODE_ENV": "production",
    "DEBUG": "true"
  },
  "timeout": 30000
}

Response

Example response

{
  "command": {
    "id": "cmd_123a6c5209bc3778245d011443644c8d27dc2c50",
    "name": "npm",
    "args": [
      "run",
      "build"
    ],
    "cwd": "/vercel/sandbox",
    "sessionId": "sbx_123a6c5209bc3778245d011443644c8d27dc2c50",
    "startedAt": 1673123456789,
    "durationMs": 1234
  }
}