Exec service
POSThttps://api.instacloud.com/projects/{projectId}/services/{serviceId}/exec
Token scope: account · org · project — read-only tokens refused (not a GET).
Run a one-shot command inside a compute service's machine (wakes it first if scaled to zero). command is argv — no shell is invoked; use ["sh", "-c", "..."] for shell features. Gated under both deploy and secrets.read.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
projectId | path | string | yes | |
serviceId | path | string | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
command | string[] | yes | |
timeoutSec | integer | no | default 30s |
Responses
200
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
exitCode | integer | yes | |
stdout | string | yes | |
stderr | string | yes | |
truncated | boolean | no | true when stdout or stderr was cut at the 1 MiB cap |
202
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
status | "approval_required" | no | |
approvalId | string | no | |
action | string | no | the gated action, or a comma-joined compound set — prefer `actions` |
actions | string[] | no | every capability this approval covers |
message | string | no | |
url | string | no | the console page where a project admin reviews this request |
nextActions | object[] | no | |
nextActions.op | string | yes | Neutral logical action id, e.g. "service.add" — NOT an operationId or a CLI/MCP tool name; each client maps it to its own surface. |
nextActions.reason | string | yes | Natural-language, human/LLM-facing "why do this now". |
nextActions.args | object | no | Suggested, flat named arguments; "<placeholder>"s where a value is unknown. |
nextActions.gated | boolean | no | True if the action passes a governance gate. |
400
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
403
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
404
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
502
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |
504
the command ran past timeoutSec; not retryable as-is — detach long work or raise timeoutSec
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | |
code | "exec_timeout" | yes | |
stdout | string | no | what the command printed before the deadline; absent when the provider did not return it |
stderr | string | no | what the command printed to stderr before the deadline; absent when the provider did not return it |