> ## Documentation Index > Fetch the complete documentation index at: https://docs.archil.com/llms.txt > Use this file to discover all available pages before exploring further. # Run Command in Sandbox > Submits a shell command to a running sandbox. By default the response reports `running` after the runtime accepts it. Set `wait=true` to hold for a terminal result; if the wait budget expires, the response remains `running` and the result is available from getSandboxExec. Only `running` sandboxes accept execs (409 otherwise). ## OpenAPI ````yaml POST /api/sandboxes/{sid}/execs openapi: 3.1.0 info: title: Archil Control Plane API description: > The Archil Control Plane API provides programmatic access to manage disks, persistent sandboxes, mounts, and API keys in the Archil distributed filesystem platform. API keys authenticate requests to this control plane and are scoped to your account. They are distinct from *disk tokens*, which are per-disk credentials used by clients when mounting a disk. ## Authentication All endpoints require an API key: ``` Authorization: {API_KEY} ``` Create API keys in the [Archil Console](https://console.archil.com) or via the API. ## Response Format All responses use a consistent envelope: ```json { "success": true, "data": { ... } } ``` Or on error: ```json { "success": false, "error": "Error message" } ``` version: 1.0.0 contact: email: support@archil.com url: https://archil.com servers: - url: https://control.green.us-east-1.aws.prod.archil.com description: AWS US East (N. Virginia) — aws-us-east-1 - url: https://control.green.eu-west-1.aws.prod.archil.com description: AWS EU West (Ireland) — aws-eu-west-1 - url: https://control.green.us-west-2.aws.prod.archil.com description: AWS US West (Oregon) — aws-us-west-2 - url: https://control.blue.us-central1.gcp.prod.archil.com description: GCP US Central (Iowa) — gcp-us-central1 security: - ApiKeyAuth: [] tags: - name: Disks description: Create, read, update, and delete disks - name: Serverless Execution description: Run commands on a disk without provisioning compute - name: Sandboxes description: Manage persistent sandbox virtual machines - name: Disk Users description: Manage authorized users on disks - name: API Tokens description: >- Manage API keys (also called API tokens) used to authenticate Control Plane API requests. Distinct from disk tokens. paths: /api/sandboxes/{sid}/execs: post: tags: - Sandboxes summary: Run a command in a sandbox description: | Submits a shell command to a running sandbox. By default the response reports `running` after the runtime accepts it. Set `wait=true` to hold for a terminal result; if the wait budget expires, the response remains `running` and the result is available from getSandboxExec. Only `running` sandboxes accept execs (409 otherwise). operationId: execInSandbox parameters: - $ref: '#/components/parameters/SandboxId' - $ref: '#/components/parameters/Wait' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SandboxExecRequest' responses: '202': description: The exec, terminal (result fields set) or still running content: application/json: schema: $ref: '#/components/schemas/ApiResponse_SandboxExec' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: The sandbox is not running content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: The sandbox's max_concurrent_execs cap is reached content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalError' components: parameters: SandboxId: name: sid in: path required: true description: Sandbox UUID schema: type: string format: uuid Wait: name: wait in: query required: false description: Hold the request for a completed start or exec result schema: type: boolean default: false schemas: SandboxExecRequest: type: object required: - command properties: command: type: string description: Shell command, run via `/bin/sh -c` command_tty: type: boolean description: Allocate a TTY for the command env: type: object additionalProperties: type: string description: Extra environment variables for this command timeout_seconds: type: integer format: int64 description: Server-side execution deadline; the exec reports timed_out past it ApiResponse_SandboxExec: type: object required: - success - data properties: success: type: boolean example: true data: $ref: '#/components/schemas/SandboxExec' ErrorResponse: type: object required: - success - error properties: success: type: boolean example: false error: type: string example: Invalid request parameters SandboxExec: type: object required: - sandbox_id - exec_id - command - status - started_at properties: sandbox_id: type: string format: uuid exec_id: type: string format: uuid command: type: string status: $ref: '#/components/schemas/SandboxExecState' exit_code: type: integer stdout: type: string stderr: type: string exit_reason: type: string execute_time_ms: type: integer format: int64 started_at: type: string format: date-time finished_at: type: string format: date-time SandboxExecState: type: string enum: - running - completed - failed - cancelled - timed_out responses: ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Invalid or missing authentication credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key ````