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.
Error
A valid request URL is required to generate request examples
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).
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Coreload","colors":{"primary":"#ff5b1f","light":"#ff7a45","dark":"#ff5b1f"},"logo":{"light":"https://mintcdn.com/coreload/F-WROzTpZWtGz7OO/logo-light.svg?fit=max\u0026auto=format\u0026n=F-WROzTpZWtGz7OO\u0026q=85\u0026s=50bd4c9eea257ef9d634dbf3599789e1","dark":"https://mintcdn.com/coreload/F-WROzTpZWtGz7OO/logo-dark.svg?fit=max\u0026auto=format\u0026n=F-WROzTpZWtGz7OO\u0026q=85\u0026s=b0cde3ceb7455ce8c50c921e01e982ed","href":"https://coreload.com"},"favicon":"https://mintcdn.com/coreload/F-WROzTpZWtGz7OO/favicon.svg?fit=max\u0026auto=format\u0026n=F-WROzTpZWtGz7OO\u0026q=85\u0026s=0de709dda535cec859042e54ba72581d","api":{"playground":{"display":"none"}},"navbar":{"links":[{"href":"https://coreload.com","label":"coreload.com"}],"primary":{"type":"button","label":"Install the GitHub App","href":"https://github.com/apps/coreload-ci/installations/new"}},"footer":{"links":[{"header":"Coreload","items":[{"label":"Home","href":"https://coreload.com"},{"label":"Quickstart","href":"/quickstart"},{"label":"Pricing","href":"/pricing"}]}]},"fonts":{"family":"Geist"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"coreload","hasAudioNarration":false,"actualSubdomain":"coreload","customDomains":["docs.coreload.com"],"gitSource":{"type":"github","owner":"coreloadhq","repo":"coreload","deployBranch":"main","contentDirectory":"docs/mintlify","isPrivate":true,"mountPath":"","label":"","_id":"6aecc328eead22005dedb25c"},"chroma":{"latestBuiltDeploymentHistoryId":"6aecc81a90fdd8a86a9d0ebe","collectionId":"8a2b0604-dc83-40ac-8ca7-f91a6cc3f6a5","liveDeploymentHistoryId":"6aecc81a90fdd8a86a9d0ebe","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6aed029d5c9b7df9b8240291","clientVersion":"0.0.4071","searchFilterCounts":[{"language":"default","tag":"API reference (beta)","count":15},{"language":"default","tag":"Endpoints","count":14},{"language":"default","tag":"Account","count":5},{"language":"default","tag":"Runners","count":5},{"language":"default","tag":"Sandboxes","count":5},{"language":"default","tag":"Get started","count":3},{"language":"default","tag":"Runs","count":3},{"language":"default","tag":"Tunnels","count":3},{"language":"default","tag":"Files","count":2},{"language":"default","tag":"Access","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[],"page":{"pagePath":"api-reference/runs/run-a-command","slug":"/api-reference/runs/run-a-command","pageMetadata":{"title":"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.\n\nNeeds the `use` scope.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/runs","href":"/api-reference/runs/run-a-command","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"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.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Needs the \", _jsx(_components.code, {\n children: \"use\"\n }), \" scope.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"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.\n\nNeeds the `use` scope.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/runs","href":"/api-reference/runs/run-a-command","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"runCommand","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.\n\nNeeds the `use` scope.","parameters":["4fbe8241-3b4f-4763-b7a8-88897632a7b2"],"requestBody":"ef030832-ff06-43e2-9dfa-baeda3832628","responses":{"200":"18d527df-b16e-4d7a-b502-75162d1ec86a","400":"a0e96d25-277d-452e-a902-63e504f295ce","401":"de4971b5-d153-4a73-bac2-5842da1d2588","403":"1bd02473-f42d-4559-86c8-b9763dbcd22d","404":"4bb49b2a-5128-40c4-a956-b1ee38029a17","409":"5e073a9e-51d6-4205-b206-09268e5c2639","413":"044255cc-2ee2-4c52-94cf-0ffff83c4349","502":"56e730c3-7f58-4801-b2b1-d2e483d53586","default":"d0c6c9d2-d69f-4f95-93cf-4ae7039c39ee"},"method":"post","type":"path","servers":["8257b7e2-aa01-4b68-a67c-a64772faebb2"],"security":["b4413efe-1b14-4a69-913e-967ba6b63849","d53f00f2-66f6-47d0-8484-d4cbaa0e7ccc"],"path":"/v1/sandboxes/{id}/runs","baseUrlOptions":["{box}"],"title":"Run a command","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"4fbe8241-3b4f-4763-b7a8-88897632a7b2":{"name":"id","in":"path","required":true,"description":"The sandbox id (`sbx_` and 12 hex).","schema":{"type":"string","pattern":"^sbx_[0-9a-f]{12}$","isRequired":true,"description":"The sandbox id (`sbx_` and 12 hex).","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["command"],"properties":{"command":{"type":"object","_tupleOriginal":true,"properties":{"[0]":{"type":"string","minLength":1,"pattern":"^[^\\u0000]*$","uniqueKey":"command.[0]","typeLabel":"string"}},"description":"The program, then its arguments (no NUL characters).","isRequired":true,"uniqueKey":"command","typeLabel":"tuple"},"timeoutMs":{"type":"integer","description":"The run's time limit in ms (at most 24 h).","minimum":1,"maximum":86400000,"uniqueKey":"timeoutMs","typeLabel":"integer"},"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}$","uniqueKey":"idempotencyKey","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"command":["\u003cstring>"],"timeoutMs":43200000,"idempotencyKey":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"18d527df-b16e-4d7a-b502-75162d1ec86a":{"description":"The run.","content":{"application/json":{"schema":{"type":"object","required":["sandbox","run","state"],"properties":{"sandbox":{"type":"string","description":"The sandbox id.","isRequired":true,"uniqueKey":"sandbox","typeLabel":"string"},"run":{"type":"string","description":"The run id.","pattern":"^run_[0-9a-f]{12}$","isRequired":true,"uniqueKey":"run","typeLabel":"string"},"state":{"type":"string","description":"`running` or `done`.","enum":["running","done"],"isRequired":true,"uniqueKey":"state","typeLabel":"enum\u003cstring>"},"command":{"type":"array","items":{"type":"string","uniqueKey":"command.items.[INDEX]","typeLabel":"string"},"description":"The command.","uniqueKey":"command","typeLabel":"string[]"},"exitCode":{"oneOf":[{"type":"integer","description":"The exit code; null while running or when a signal ended it.","uniqueKey":"exitCode.oneOf.0","typeLabel":"integer"},{"type":"null","description":"The exit code; null while running or when a signal ended it.","uniqueKey":"exitCode.oneOf.1","typeLabel":"null"}],"uniqueKey":"exitCode","typeLabel":"integer | null"},"signal":{"oneOf":[{"type":"string","description":"The signal that ended it, if one did.","uniqueKey":"signal.oneOf.0","typeLabel":"string"},{"type":"null","description":"The signal that ended it, if one did.","uniqueKey":"signal.oneOf.1","typeLabel":"null"}],"uniqueKey":"signal","typeLabel":"string | null"},"timedOut":{"oneOf":[{"type":"boolean","description":"True when it hit its time limit.","uniqueKey":"timedOut.oneOf.0","typeLabel":"boolean"},{"type":"null","description":"True when it hit its time limit.","uniqueKey":"timedOut.oneOf.1","typeLabel":"null"}],"uniqueKey":"timedOut","typeLabel":"boolean | null"},"error":{"oneOf":[{"type":"string","description":"Why it could not start, if it could not.","uniqueKey":"error.oneOf.0","typeLabel":"string"},{"type":"null","description":"Why it could not start, if it could not.","uniqueKey":"error.oneOf.1","typeLabel":"null"}],"uniqueKey":"error","typeLabel":"string | null"},"stdout":{"type":"string","description":"Standard output (what is kept of it).","uniqueKey":"stdout","typeLabel":"string"},"stderr":{"type":"string","description":"Standard error (what is kept of it).","uniqueKey":"stderr","typeLabel":"string"},"stdoutTruncated":{"type":"boolean","description":"True once standard output passed the stored cap.","uniqueKey":"stdoutTruncated","typeLabel":"boolean"},"stderrTruncated":{"type":"boolean","description":"True once standard error passed the stored cap.","uniqueKey":"stderrTruncated","typeLabel":"boolean"},"outputHeld":{"oneOf":[{"type":"boolean","description":"True when output is held back.","uniqueKey":"outputHeld.oneOf.0","typeLabel":"boolean"},{"type":"null","description":"True when output is held back.","uniqueKey":"outputHeld.oneOf.1","typeLabel":"null"}],"uniqueKey":"outputHeld","typeLabel":"boolean | null"},"startedAt":{"type":"string","description":"When it started.","format":"date-time","uniqueKey":"startedAt","typeLabel":"string\u003cdate-time>"},"finishedAt":{"oneOf":[{"type":"string","description":"When it finished.","format":"date-time","uniqueKey":"finishedAt.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","description":"When it finished.","format":"date-time","uniqueKey":"finishedAt.oneOf.1","typeLabel":"null"}],"uniqueKey":"finishedAt","typeLabel":"string\u003cdate-time> | null"},"durationMs":{"oneOf":[{"type":"integer","description":"How long it ran, in ms.","uniqueKey":"durationMs.oneOf.0","typeLabel":"integer"},{"type":"null","description":"How long it ran, in ms.","uniqueKey":"durationMs.oneOf.1","typeLabel":"null"}],"uniqueKey":"durationMs","typeLabel":"integer | null"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"sandbox":"\u003cstring>","run":"\u003cstring>","state":"running","command":["\u003cstring>"],"exitCode":123,"signal":"\u003cstring>","timedOut":true,"error":"\u003cstring>","stdout":"\u003cstring>","stderr":"\u003cstring>","stdoutTruncated":true,"stderrTruncated":true,"outputHeld":true,"startedAt":"2023-11-07T05:31:56Z","finishedAt":"2023-11-07T05:31:56Z","durationMs":123}}},"exampleType":"generated"}},"exampleType":"generated"},"a0e96d25-277d-452e-a902-63e504f295ce":{"description":"Notably `invalid_value`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"de4971b5-d153-4a73-bac2-5842da1d2588":{"description":"Notably `unauthorized`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"1bd02473-f42d-4559-86c8-b9763dbcd22d":{"description":"Notably `scope_missing`, `ip_not_allowed`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"4bb49b2a-5128-40c4-a956-b1ee38029a17":{"description":"Notably `not_found`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"5e073a9e-51d6-4205-b206-09268e5c2639":{"description":"Notably `sandbox_not_ready`, `idempotency_conflict`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"044255cc-2ee2-4c52-94cf-0ffff83c4349":{"description":"Notably `too_large`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"56e730c3-7f58-4801-b2b1-d2e483d53586":{"description":"Notably `backend_error`.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"d0c6c9d2-d69f-4f95-93cf-4ae7039c39ee":{"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":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false,"isRequired":true,"uniqueKey":"ok","typeLabel":"any"},"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"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"What went wrong, and what to do.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"ok":false,"error":{"code":"invalid_value","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"b4413efe-1b14-4a69-913e-967ba6b63849":{"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`.","scopes":[],"schemeName":"ticket"}},"d53f00f2-66f6-47d0-8484-d4cbaa0e7ccc":{"apiKey":{"type":"http","scheme":"bearer","description":"Your API key: `Authorization: Bearer \u003ckey>`. The edge takes it for a ticket; a box takes a key issued for that box.","scopes":[],"schemeName":"apiKey"}}},"servers":{"8257b7e2-aa01-4b68-a67c-a64772faebb2":{"url":"{box}","description":"The box URL from your ticket (`url`).","variables":{"box":{"default":"https://box.coreload.example","description":"The ticket's url."}}}},"processedSecurityOptions":[{"schemes":[{"scheme":{"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`.","scopes":[],"schemeName":"ticket"},"schema":{"title":"Authorization","type":"string","description":"The ticket's `authorization` value, sent as it is (its own scheme, not Bearer), until the ticket's `expiresAt`.","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ticket","name":"Authorization"}],"title":"ticket"},{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"Your API key: `Authorization: Bearer \u003ckey>`. The edge takes it for a ticket; a box takes a key issued for that box.","scopes":[],"schemeName":"apiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Your API key: `Authorization: Bearer \u003ckey>`. The edge takes it for a ticket; a box takes a key issued for that box.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"apiKey","name":"Authorization"}],"title":"apiKey"}]},"originalFileLocation":"openapi.json"},"subdomain":"coreload","siteName":"Coreload","title":"Run a command - Coreload","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-05T20:18:22.686Z","originalFileLocation":"api-reference/runs/run-a-command.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Coreload\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Run a command - Coreload\">\u003cmeta data-mint-head property=\"og:description\" content=\"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.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Coreload\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.coreload.com/api-reference/runs/run-a-command\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://coreload.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Run+a+command\u0026amp;description=Starts+a+command+in+a+ready+sandbox+and+answers+with+its+run+record.+A+command+that+exits+nonzero%2C+times+out+or+cannot+start+is+a+result%2C+not+an+error.%0A%0ANeeds+t\u0026amp;theme=db2a9d753a96e7371f6d74f9\u0026amp;signature=6b9765e55dba07c537246152f7704552e96333c41a37c2ae83b6cead570e5fd5\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Run a command - Coreload\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://coreload.mintlify.app/_mintlify/api/og/v2?division=Runs\u0026amp;title=Run+a+command\u0026amp;description=Starts+a+command+in+a+ready+sandbox+and+answers+with+its+run+record.+A+command+that+exits+nonzero%2C+times+out+or+cannot+start+is+a+result%2C+not+an+error.%0A%0ANeeds+t\u0026amp;theme=db2a9d753a96e7371f6d74f9\u0026amp;signature=6b9765e55dba07c537246152f7704552e96333c41a37c2ae83b6cead570e5fd5\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/coreload/kDocl_xUe8SpC1qe/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Coreload\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#ff5b1f\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.coreload.com/api-reference/runs/run-a-command\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/runs/run-a-command.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.coreload.com/#organization\",\"name\":\"Coreload\",\"url\":\"https://docs.coreload.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/coreload/F-WROzTpZWtGz7OO/logo-light.svg?fit=max\u0026auto=format\u0026n=F-WROzTpZWtGz7OO\u0026q=85\u0026s=50bd4c9eea257ef9d634dbf3599789e1\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.coreload.com#website\",\"name\":\"Coreload\",\"url\":\"https://docs.coreload.com\",\"publisher\":{\"@id\":\"https://docs.coreload.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.coreload.com/api-reference/runs/run-a-command#webpage\",\"url\":\"https://docs.coreload.com/api-reference/runs/run-a-command\",\"name\":\"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.\",\"dateModified\":\"2026-11-05T20:18:22.686Z\",\"isPartOf\":{\"@id\":\"https://docs.coreload.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.coreload.com/api-reference/runs/run-a-command#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.coreload.com/api-reference/runs/run-a-command#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"API reference (beta)\",\"item\":\"https://docs.coreload.com/api\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Endpoints\",\"item\":\"https://docs.coreload.com/api-reference/access/get-a-ticket-for-a-box\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Run a command\",\"item\":\"https://docs.coreload.com/api-reference/runs/run-a-command\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.coreload.com/api-reference/runs/run-a-command#apireference\",\"headline\":\"Run a command\",\"name\":\"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.\",\"url\":\"https://docs.coreload.com/api-reference/runs/run-a-command\",\"mainEntityOfPage\":{\"@id\":\"https://docs.coreload.com/api-reference/runs/run-a-command#webpage\"},\"dateModified\":\"2026-11-05T20:18:22.686Z\",\"publisher\":{\"@id\":\"https://docs.coreload.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.coreload.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Coreload\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Coreload","nav":{"global":null,"groups":[{"group":"Get started","pages":[{"title":"Docs","href":"/index"},{"title":"Quickstart: your first job on Coreload","href":"/quickstart"},{"title":"Migrate from Blacksmith","href":"/migrate-from-blacksmith"}]},{"group":"Runners","pages":[{"title":"Runner sizes","href":"/sizes"},{"title":"Runners and labels","href":"/runners"},{"title":"Languages and tools","href":"/languages"},{"title":"Caching","href":"/caching"},{"title":"Limits","href":"/limits"}]},{"group":"Account","pages":[{"title":"Pricing","href":"/pricing"},{"title":"Billing","href":"/billing"},{"title":"Security model","href":"/security"},{"title":"Troubleshooting","href":"/troubleshooting"},{"title":"Questions","href":"/faq"}]},{"group":"API reference (beta)","pages":[{"title":"API reference (beta)","href":"/api"},{"group":"Endpoints","pages":[{"group":"Access","pages":[{"title":"Get a ticket for a box","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/tickets","href":"/api-reference/access/get-a-ticket-for-a-box"}]},{"group":"Sandboxes","pages":[{"title":"List your sandboxes","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sandboxes","href":"/api-reference/sandboxes/list-your-sandboxes"},{"title":"Create a sandbox","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes","href":"/api-reference/sandboxes/create-a-sandbox"},{"title":"Get a sandbox","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sandboxes/{id}","href":"/api-reference/sandboxes/get-a-sandbox"},{"title":"Destroy a sandbox","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/sandboxes/{id}","href":"/api-reference/sandboxes/destroy-a-sandbox"},{"title":"Lock a sandbox's egress","description":"Limits the sandbox's outbound network to the agent relay. One-way and idempotent: it is never unlocked.\n\nNeeds the `use` scope.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/egress","href":"/api-reference/sandboxes/lock-a-sandboxs-egress"}]},{"group":"Runs","pages":[{"title":"Run a command","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/runs","href":"/api-reference/runs/run-a-command"},{"title":"Get a run's result","description":"The run's state and, once it is done, its outcome. While it runs, the outcome fields are null and the output so far is what the logs route returns.\n\nNeeds the `view` scope.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sandboxes/{id}/runs/{run}","href":"/api-reference/runs/get-a-runs-result"},{"title":"Get a run's output so far","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sandboxes/{id}/runs/{run}/logs","href":"/api-reference/runs/get-a-runs-output-so-far"}]},{"group":"Files","pages":[{"title":"Download a file","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sandboxes/{id}/files","href":"/api-reference/files/download-a-file"},{"title":"Upload a file","deprecated":null,"version":null,"openapi":"/openapi.json put /v1/sandboxes/{id}/files","href":"/api-reference/files/upload-a-file"}]},{"group":"Tunnels","pages":[{"title":"Open an SSH tunnel","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/ssh","href":"/api-reference/tunnels/open-an-ssh-tunnel"},{"title":"Open a desktop tunnel","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/desktop","href":"/api-reference/tunnels/open-a-desktop-tunnel"},{"title":"Open a credential relay tunnel","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sandboxes/{id}/relay","href":"/api-reference/tunnels/open-a-credential-relay-tunnel"}]}]}]}]},"basePath":"","title":"Run a command - Coreload","buildId":"dpl_GZsjphRpnhWkstV12jxWNcMHFyox","deploymentId":"dpl_GZsjphRpnhWkstV12jxWNcMHFyox","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-B5zPa4Vr.js","utils-CVjrr8Yd.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DTgURWzl.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DxTHtkdZ.js","snippetPresets-Cx47o5Vx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-4Fr6y9N_.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-Dq2ElbEk.js","shallow-BfYl9r69.js","getApiPlaygroundDisplay-Ch3xc7i1.js","CodeSnippet-BsBxuJ1v.js","CodeSnippets-CetzeDL8.js","Page-CYZot51e.js","getPastedJson-BxPKFSJx.js","icon-o0J1Ochb.js","MethodPill-Du3usO5m.js","DuplicateIcon-DJypyMzl.js","createIcon-YMA6N8KJ.js","DynamicMarkdown-CWvhfcZc.js","SectionHeading-BdLVaXCd.js","axios-vUo_bRtp.js","Markdown-C4Ez6OeV.js","clsx-DptzKFCt.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-Dt1IougW.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-CZ6Wt2Vb.js"]}