> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreload.com/llms.txt > Use this file to discover all available pages before exploring further. # Run a command > Starts a command in a ready sandbox and answers with its run record. A command that exits nonzero, times out or cannot start is a result, not an error. Needs the `use` scope. ## OpenAPI ````yaml /openapi.json post /v1/sandboxes/{id}/runs openapi: 3.1.0 info: title: Coreload sandbox API version: '1' description: >- Create short-lived sandboxes, run commands in them and move files in and out. The API is in beta and not offered to outside callers yet: there are no API keys for outside callers. A call gets a ticket for a box from the edge with an API key, then calls the box at the ticket's URL with the ticket's `authorization` header. Answers are JSON, except a file download (its bytes) and a tunnel (a 101 upgrade); a JSON error is `{ok: false, error: {code, message}}`. servers: - url: '{box}' description: The box URL from your ticket (`url`). variables: box: default: https://box.coreload.example description: The ticket's url. security: - ticket: [] - apiKey: [] tags: - name: Access description: 'Tickets: how a key reaches a box.' - name: Sandboxes description: Create, list, get and destroy sandboxes. - name: Runs description: Run commands in a sandbox and read their results and output. - name: Files description: Move files in and out of a sandbox. - name: Tunnels description: >- Byte tunnels over an HTTP upgrade: to a sandbox's SSH server or desktop, and the relay that answers a sandbox's outbound connections from your side. paths: /v1/sandboxes/{id}/runs: post: tags: - Runs summary: Run a command description: >- Starts a command in a ready sandbox and answers with its run record. A command that exits nonzero, times out or cannot start is a result, not an error. Needs the `use` scope. operationId: runCommand parameters: - name: id in: path required: true description: The sandbox id (`sbx_` and 12 hex). schema: type: string pattern: ^sbx_[0-9a-f]{12}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunRequest' responses: '200': description: The run. content: application/json: schema: $ref: '#/components/schemas/Run' '400': description: Notably `invalid_value`. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Notably `unauthorized`. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Notably `scope_missing`, `ip_not_allowed`. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Notably `not_found`. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Notably `sandbox_not_ready`, `idempotency_conflict`. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: Notably `too_large`. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: Notably `backend_error`. content: application/json: schema: $ref: '#/components/schemas/Error' default: description: >- An error: `{ok: false, error: {code, message}}`. This route may answer any code in this table (code, then status): `invalid_value` 400, `unauthorized` 401, `scope_missing` 403, `ip_not_allowed` 403, `not_found` 404, `idempotency_conflict` 409, `sandbox_not_ready` 409, `too_large` 413, `quota_exceeded` 429, `busy` 429, `wait_timeout` 504, `backend_error` 502. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RunRequest: type: object required: - command properties: command: type: array minItems: 1 prefixItems: - type: string minLength: 1 pattern: ^[^\u0000]*$ items: type: string pattern: ^[^\u0000]*$ description: The program, then its arguments (no NUL characters). timeoutMs: type: integer description: The run's time limit in ms (at most 24 h). minimum: 1 maximum: 86400000 idempotencyKey: type: string description: >- Makes a retried run return the first one's answer; the same key with a different request is `idempotency_conflict`. 1 to 255 printable ASCII characters without spaces (a UUID is fine). pattern: ^[\x21-\x7e]{1,255}$ Run: type: object required: - sandbox - run - state properties: sandbox: type: string description: The sandbox id. run: type: string description: The run id. pattern: ^run_[0-9a-f]{12}$ state: type: string description: '`running` or `done`.' enum: - running - done command: type: array items: type: string description: The command. exitCode: type: - integer - 'null' description: The exit code; null while running or when a signal ended it. signal: type: - string - 'null' description: The signal that ended it, if one did. timedOut: type: - boolean - 'null' description: True when it hit its time limit. error: type: - string - 'null' description: Why it could not start, if it could not. stdout: type: string description: Standard output (what is kept of it). stderr: type: string description: Standard error (what is kept of it). stdoutTruncated: type: boolean description: True once standard output passed the stored cap. stderrTruncated: type: boolean description: True once standard error passed the stored cap. outputHeld: type: - boolean - 'null' description: True when output is held back. startedAt: type: string description: When it started. format: date-time finishedAt: type: - string - 'null' description: When it finished. format: date-time durationMs: type: - integer - 'null' description: How long it ran, in ms. Error: type: object required: - ok - error properties: ok: const: false error: type: object required: - code - message properties: code: type: string description: The error code. enum: - invalid_value - unauthorized - scope_missing - ip_not_allowed - not_found - backend_error - idempotency_conflict - sandbox_not_ready - too_large - quota_exceeded - busy - wait_timeout message: type: string description: What went wrong, and what to do. securitySchemes: ticket: type: apiKey in: header name: Authorization description: >- The ticket's `authorization` value, sent as it is (its own scheme, not Bearer), until the ticket's `expiresAt`. apiKey: type: http scheme: bearer description: >- An API key: `Authorization: Bearer `. The edge takes it for a ticket; a box takes a key issued for that box. Keys are not issued to outside callers yet. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.