Skip to content
Docs

Execute a command

POSThttps://api.vercel.com/v2/sandboxes/sessions/{sessionId}/cmd
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.
https://api.vercel.com/v2/sandboxes/sessions/{sessionId}/cmd
const response = await fetch('https://api.vercel.com/v2/sandboxes/sessions/sessionId/cmd?cmdId=string&teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "command": "npm",
    "args": [],
    "cwd": "/home/vercel-sandbox",
    "env": "[object Object]",
    "sudo": "true",
    "wait": "true",
    "logs": "true",
    "timeout": "30000",
    "attachStdin": "true"
  }),
});


const data = await response.json();
console.log(data);
Response
{
  "command": {
    "args": [],
    "cwd": "/vercel/sandbox",
    "durationMs": "1234",
    "exitCode": "0",
    "id": "cmd_123a6c5209bc3778245d011443644c8d27dc2c50",
    "name": "npm",
    "sessionId": "sbx_123a6c5209bc3778245d011443644c8d27dc2c50",
    "startedAt": "1673123456789"
  }
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

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

Query parameters

cmdIdstringRequired
The unique identifier of the command to stream logs for.
teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Body

application/json
commandstringRequired
The executable or shell command to run. This is the program name without arguments.
argsarrayOptional
Arguments to pass to the command. Each argument should be a separate array element.
cwdstringOptional
The working directory in which to execute the command. Defaults to the sandbox home directory if not specified.
envobjectOptional
Additional environment variables to set for this command. These are merged with the sandbox environment.
sudobooleanOptional
Execute the command with root (superuser) privileges.
waitbooleanOptional
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.
logsbooleanOptional
If true, stream the logs of the command execution in real-time via ND-JSON. This is only applicable if wait is also true.
timeoutintegerOptional
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.
attachStdinbooleanOptional
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

200Success
commandobjectRequired
This object represents a command run in a Vercel Sandbox session (v2 API).

Errors

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