Skip to content
Fuse
Esc
↑↓navigate↵open⌘Jpreview

Act on an environment

Supported actions:

  • rotate-token — generate fresh per-VM credentials, upload them to the guest filesystem, and persist the orchestrator’s encrypted copy. Returns 204. Note: the running fused process reads its token once at startup and keeps serving the old token until it is restarted; rotation currently takes full effect only after the guest agent restarts.
  • drain — first phase of two-phase teardown. Runs the environment’s configured drain command inside the guest (default: the fused drain command) so in-guest workloads quiesce gracefully; an empty drain command only transitions the state. The VM transitions to draining but is not destroyed; a subsequent DELETE tears it down. Only running VMs can be drained — any other state returns 409. If the drain command fails the VM remains in draining so the caller can still DELETE; the failure is returned as 5xx. A VM left in draining longer than the orchestrator’s draining timeout (--draining-timeout, default 5m30s) is destroyed by the reconcile loop, unless a hitl decision is pending on it or its destroy is gated.
  • fork — create a new environment seeded from a checkpoint of this one. With reuse_snapshot_id empty the server snapshots the source first; otherwise it reuses that ready snapshot (it must belong to this VM). The fork is pinned to the source’s host, receives its own guest credentials (fused is restarted), and is returned as a new Environment with 201. GPU environments (spec.gpus > 0, including MIG) and QEMU-hosted environments cannot be forked: a vfio device cannot be checkpointed, so the request returns 409 conflict. That is a permanent property of the environment and must not be retried.
  • exec — run a single command inside the guest and return its exit code, stdout, and stderr. Takes an ExecEnvironmentRequest body and returns an ExecEnvironmentResponse. See the exit-code contract below.
  • request: the agent asks a human for something the environment’s hitl.requests declares: an ask, a secret or a takeover (RequestHumanRequest). Returns 201 with the pending Intervention.
  • takeover: a human takes control of the environment (TakeoverRequest, body optional). Claims the agent’s pending takeover request when there is one, else opens a new takeover on the caller’s behalf. Returns 200 with the intervention, still pending, with payload.takeover.holder and started_at set. While it is held the agent’s exec and computer actions get 423 locked. Taking over again as the current holder returns the same intervention. Needs hitl:takeover; the agent’s own key cannot claim the request it raised (403 self_approval). 409 when someone else already holds it, or the VM is not running. 400 when the environment does not declare hitl.requests.takeover, or not for this via.
  • release: end the held takeover (ReleaseRequest, body optional). The intervention is approved and note becomes its decision.answer, which is what the waiting agent reads; an empty note becomes released by <actor>. Any caller with hitl:takeover may release, not only the holder, so a takeover whose holder walked away does not have to wait out its deadline. Returns 200 with the intervention. 409 when nothing is held, or the takeover expired before the release arrived.

Exec: a non-zero exit code is not an HTTP error. A guest command that exits non-zero comes back as 200 with that code in exit_code. The command ran, and it failed; that is the answer the caller asked for, not a transport failure. Clients and SDKs must surface it as a value and must not raise on it.

HTTP errors are reserved for the cases where the command could not be run at all:

  • 400 invalid_argument — neither cmd nor shell was set, or both were.
  • 403 unauthorized — exec requires the master token. API keys are refused: exec is root in the guest, and keys carry no scopes today.
  • 404 not_found — unknown VM.
  • 409 conflict — the VM is not running (e.g. draining).
  • 423 locked: a human holds the environment (a takeover), or an ask stall is waiting for a human to ack it. Nothing ran. details.intervention_id names the intervention and details.kind is takeover or stall. Wait on it with GET /v1/interventions/{interventionId}?wait= until it is no longer pending, then send the exec again. The lock never outlives the intervention’s deadline. The SDKs do this by default.
  • 501 unimplemented — the provider has no guest to exec into (e.g. the in-memory stub).

Fork error mapping. Fork returns 409 conflict for three distinct preconditions:

  • the reused snapshot (reuse_snapshot_id) is not in state ready;
  • the source holds a GPU passthrough device (permanent — do not retry);
  • with reuse_snapshot_id empty, the implicit seed snapshot is refused because the snapshot quota (count or bytes) is exhausted. This 409 has nothing to do with a reused snapshot’s state, so do not infer the cause from the status code alone.

404 covers an unknown VM or snapshot, including a reused snapshot that is no longer present on the host.

Known limitation: the remaining fork and rotate-token precondition failures — source VM not running, and a provider with no fork support — still return 500 internal rather than 409/501. Treat the message, not the status code, as the contract until these move to 4xx.

Hitl gates. When the environment’s hitl.gates or hitl.exec match, exec, fork, migrate, drain and rotate-token are checked before anything runs. A gate in ask mode answers 202 with a HeldResponse and performs the action only once a human approves it; notify lets it run and records a terminal intervention; deny answers 403 forbidden with details.reason hitl_denied. A grant from an earlier approval (env or ttl:<duration>) lets a matching action through without a prompt.

POST/v1/environments/{vmId}
Authorization
AuthorizationBearer token · headerrequired
`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. An expired key is refused with 401 like an unknown one. A key minted with `scopes` reaches only the hitl routes (`/v1/interventions`, `/v1/hitl/*`, and POST /v1/api-keys to mint a narrower key). Any other route is 403 code `forbidden`, reason `env_scope`, except an `/v1/environments/{vmId}` route for an environment the key does not cover, which is 404 so the key cannot probe which environments exist. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.
or
fuse_sessionAPI key · cookierequired
HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.
Path parameters
vmIdstringrequired
VM identifier assigned by the orchestrator.
Query parameters
actionstringrequired
The action to perform.
Allowed:rotate-tokendrainforkmigrateexecrequesttakeoverrelease
Header parameters
Fuse-Actorstring
The person behind this request, as an opaque id (`user_42`, `alice@corp.com`, `slack:U0123`). Fuse records it on hitl interventions and the audit log and never checks it. Accepted on every authenticated route; it matters wherever an actor is recorded (raising, deciding, minting). At most 128 bytes, no control characters; a malformed value is 400. How the recorded actor is resolved: - key pinned to an actor: that actor (`source: pinned`). A different `Fuse-Actor` is 403 `forbidden`, reason `actor_mismatch`. - key with `hitl:act-as`: the header value (`source: asserted`, with the asserting key's id), else `key:<key_id>`. - any other key: `key:<key_id>` named after the key's label (`source: key`). Sending the header is 403 `forbidden`, reason `actor_not_allowed`, rather than silently dropped. - master token: the header value (`source: asserted`), else `master` (`source: key`). An asserted actor is only as true as the key holder's own auth.
max length 128
Fuse-Actor-Namestring
Optional display name for `Fuse-Actor`, at most 256 bytes. Sending it without `Fuse-Actor` is 400.
max length 256
Request body
application/json
Required for `exec`, which rejects an empty body with 400, and for `request` (RequestHumanRequest). Optional for `fork` (ForkEnvironmentRequest), `migrate` (MigrateEnvironmentRequest), `takeover` (TakeoverRequest) and `release` (ReleaseRequest). Ignored by `rotate-token` and `drain`.
One of:
ExecEnvironmentRequest
cmdstring[]
The argv to run in the guest, e.g. `["ls", "-l", "/var/log"]`. Preferred over `shell`: argv has no quoting rules and cannot be turned into an injection by interpolating a value.
shellstring
A command line to run under `sh -lc`. The explicit opt-in for what argv cannot express: pipelines, redirects, and globs.
timeout_msinteger
Bounds how long the command may run inside the guest. Zero (or omitted) takes the server default of 60000 ms. Values above the server ceiling of 600000 ms are clamped to it, not rejected.
ForkEnvironmentRequest
reuse_snapshot_idstring
Existing ready snapshot of this VM to seed the fork from. Empty means snapshot the source first.
commentstring
Free-form note attached to the seed snapshot.
MigrateEnvironmentRequest
target_host_idstring
Host to migrate the VM to. Empty means the orchestrator picks a host other than the source via its scheduler, preferring the environment's checkpoint standby. It never picks the source: if no other host can take the VM the request answers 503 and the source keeps running.
liveboolean
Carry the guest's memory to the target and resume it there, so processes survive the move, instead of cold-booting a disk snapshot. Requires the same cpu and firecracker build on both hosts, and the environment's network slot free on the target. It never falls back to a cold migration: a target that cannot resume the guest answers 409 and the source keeps running.
lazyboolean
Resume the guest on the target before its memory has arrived and page it in from the source afterwards, so the move does not wait on a full copy of the memory image. Requires `live` and an environment created with `huge_pages`, otherwise 409. Until the target reports every page resident (the `vm.memory_resident` event) the guest still depends on the source host; if the transfer fails, `vm.memory_transfer_failed` is emitted and the guest hangs on its next missing page.
RequestHumanRequest
kindstring
Request kind. Defaults to ask.
Allowed:asksecrettakeoverreview
questionstring
What the human is asked. Required for an ask.
choicesstring[]
When set, the answer must be one of these.
targetstring
A declared secret target, by its `env` name or `file` path. Required for a secret; anything undeclared is 400. The agent gets back `decision.answer` `"done"`, never the value.
messagestring
The agent's text, shown to the human under the target's label (secret), or with the content up for review (review).
max length 4096
pathstring
An absolute, clean guest path to review (review). Fuse reads it at request time, up to 1 MiB; a longer file is cut off and `payload.review.truncated` is set. A file fuse cannot read is 400. Exclusive with `content`.
contentstring
Inline text or a diff to review (review). Exclusive with `path`.
max length 1048576
formatstring
How to show the review (review). Empty guesses: `diff` when the content starts like a unified diff or the path ends in `.diff` or `.patch`, else `text`.
Allowed:textdiff
viastring
How the human should take over. Defaults to `terminal` (takeover).
Allowed:terminaldesktop
reasonstring
Why the agent wants a human to take over (takeover). On release the agent gets the human's note as `decision.answer`.
timeout_secondsinteger<int64>
Shortens the policy's deadline for this request. Never extends it.
TakeoverRequest
viastring
How to take over. Defaults to `terminal`. Must be declared in `hitl.requests.takeover.via`. Claiming an agent's pending request keeps the `via` the agent asked for.
Allowed:terminaldesktop
reasonstring
Recorded when no agent request is pending to claim.
ReleaseRequest
notestring
Handed back to the agent as the takeover's `decision.answer`. Empty becomes `released by <actor>`.
Responses
200Drain succeeded (body is the updated Environment with `state == "draining"`), exec completed (body is an ExecEnvironmentResponse), or a takeover was started or released (body is the Intervention). An exec whose guest command exited non-zero lands here, not in an error response.
One of:
Environment
idstringrequired
Fleet-assigned VM identifier (prefix + task_id).
statestringrequired
Allowed:provisioningrunningdrainingdestroying
task_idstringrequired
Empty when the VM is being torn down.
host_idstring
Scheduler-assigned host ID when placement uses the host registry.
urlstringrequired
host:port address where the guest agent (fused) is reachable, via per-VM DNAT. Empty before the VM is running.
specResourceSpecrequired
Hardware requirements for a VM. No lower bound is declared on cpus/ram_mb because the server does not enforce one: createEnvironment validates only task_id and the GPU fields, so a spec with `cpus: 0` / `ram_mb: 0` is accepted and scheduled. Callers should still send positive values; a strict request validator must not reject zero, or it will refuse payloads the API accepts.
Show properties
cpusinteger<int32>
min 0
ram_mbinteger<int32>
min 0
storage_gbinteger<int32>
min 0
gpusinteger<int32>
Count of GPU devices requested. Zero means no GPU. With gpu_profile unset, this is whole devices; with gpu_profile set, this is the count of MIG instances of that profile (decision D5).
min 0
gpu_kindstring
Optional GPU model to match (e.g. "a100"). Empty matches any kind on a host that has GPUs.
gpu_profilestring
Optional MIG profile in mig-parted vocabulary (e.g. "1g.10gb"). When set, gpus counts MIG instances of this profile rather than whole devices, and the qemu host agent attaches them via vfio-pci sysfsdev (decision D5).
imagestring
Optional named base rootfs for the provider to boot from (resolved by the host agent against its named-rootfs directory). Empty means the provider's default base image.
regionstring
host_idstring
Pins the environment to an exact host id (the Fusefile's placement.host). A pin is a hard gate, not an override: the host must still be active, run the right backend, and fit the request. An unknown host id is rejected with 404 before any VM is created.
labelsobject
Placement label selectors (the Fusefile's placement.labels). Every pair must match the target host's operator-declared labels. A selector that matches no host is rejected with 503, never queued.
huge_pagesboolean
Back guest memory with 2M pages. The host must have that much memory reserved as hugepages, or the create answers 409. Fixed for the life of the environment, and required for a lazy migrate.
max_runtime_secondsinteger<int64>
Leak-detection ceiling for this task. Zero means "use the fleet default". The orchestrator tears down tasks that exceed this age with no state transitions.
idle_timeout_secondsinteger<int64>
Destroys the environment once it has gone this long with no exec and no attach session. Zero means "use the fleet default", which is no idle expiry unless the operator configured one. Measured from the last exec or attach, not from create, and must be at least 60 (idle detection runs on the reconcile loop). In-guest CPU use and traffic on exposed ports are not observed.
created_atstring<date-time>required
updated_atstring<date-time>required
errorstring
Last failure message, empty on the happy path.
endpointsEndpoint[]
Published network endpoints for ports requested via the create request's `expose` list. Omitted when none.
Show properties
Array of Endpoint
asstring
Caller-chosen label from the expose request.
urlstringrequired
Reachable address, e.g. "http://203.0.113.5:41231".
protocolstring
The transport this endpoint was actually published on, which is not always what was requested: a host agent too old to know about the field publishes tcp and omits this. Read it rather than assuming the request was honoured.
Allowed:tcpudp
portintegerrequired
The guest-side port this endpoint publishes.
healthobject
Last verdict of the environment-level healthcheck. Omitted when the environment declared no healthcheck, and omitted until the first verdict has been read back from the guest. The orchestrator refreshes it on the reconcile tick (30s by default), so it lags the guest by up to one tick.
Show properties
statestringrequired
The probe's last verdict. Deliberately separate from `Environment.state`: an unhealthy environment is still a running one, and nothing tears it down for a failing probe.
Allowed:startingpassingfailing
sincestring<date-time>
When the probe entered this state.
failuresinteger
Consecutive failed attempts. Zero while passing.
messagestring
The last attempt's failure detail. Empty while passing.
egressobject
The resolved outbound policy. Always present on a server that knows about egress: an environment created without asking reports `direct`, so a caller can tell "not proxied" from "this server predates the field".
Show properties
modestringrequired
Allowed:directproxy
providerstring
The backend serving this environment. Proxy only.
protocolstring
Proxy only.
Allowed:socks5http
endpointstring
The proxy url the workload was handed, e.g. `socks5h://10.200.3.1:1080`. A host-local address useless to anyone not already inside the sandbox, and never a credential. Proxy only.
healthobject
The endpoint's last probe verdict. Proxy only, and `unknown` until the reconcile tick (30s by default) has probed it once. An unhealthy proxy reports and nothing acts on it: the environment keeps running with no egress, never with direct egress.
Show properties
statestringrequired
Allowed:unknownhealthyunhealthy
reasonstring
The backend-level failure, e.g. `dial tcp 10.200.3.1:1080: connection refused`. Empty while healthy. Never a destination hostname or anything drawn from the sandbox's traffic.
checked_atstring<date-time>
ExecEnvironmentResponse
exit_codeintegerrequired
The guest command's own exit status. Non-zero is a normal result, delivered with HTTP 200.
stdoutstringrequired
stderrstringrequired
Intervention
idstringrequired
env_idstringrequired
kindstringrequired
Allowed:asksecrettakeoverreviewexeclifecyclecomputerstallexpiry
gatestring
The gate that raised it. Empty for a request.
modestring
The gate's mode. Notify and deny records are born terminal.
Allowed:asknotifydeny
statestringrequired
Allowed:pendingapprovedrejectedexpiredcancelled
payloadobjectrequired
What was asked or attempted: `question` for an ask, `secret`, `takeover` or `review` for those requests, `exec`, `lifecycle` or `computer` for a gate, `signal` for a stall or expiry. `decider` is set when a gate's decider sent the action on to a human.
Show properties
questionstring
choicesstring[]
execExecPayload
A held exec.
Show properties
argvstring[]required
shellstring
The script when the caller sent `shell`; argv is then the sh -lc that runs it.
timeout_msinteger<int64>
lifecycleLifecyclePayload
A held environment action.
Show properties
actionstringrequired
Allowed:destroyforkmigratedrainsnapshotrotate-token
secretInterventionSecret
A secret request. It never holds the value.
Show properties
targetstringrequired
The declared target's `env` name or `file` path.
labelstringrequired
The target's label from the policy. Show it first: the agent writes `message`, so `message` alone could claim to be anything.
messagestring
The agent's own text.
takeoverInterventionTakeover
A takeover. `holder` and `started_at` are set while a human holds the environment, which is also when the agent's exec and computer calls get 423. The intervention stays `pending` until release.
Show properties
viastringrequired
Allowed:terminaldesktop
reasonstring
holderActor
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
started_atstring<date-time>
signalInterventionSignal
What fuse saw when it raised a stall or expiry. A stall carries `failures` and `last_exit_code`, or `quiet_seconds`. An expiry carries `reaper` and `reap_at`, and once approved `extended_until`.
Show properties
failuresinteger
The run of consecutive non-zero exec exits.
last_exit_codeinteger
The exit code that completed the run.
quiet_secondsinteger<int64>
How long the agent had made no exec or computer call.
reaperstring
What will tear the environment down.
Allowed:idle_timeoutmax_runtime
reap_atstring<date-time>
When. The expiry's own deadline is capped at this, with a 10s floor.
extended_untilstring<date-time>
Set on approval. The reapers leave the environment alone until then.
computerComputerPayload
A held computer action. On approval the orchestrator replays `input` to the guest, with the approver's `edited_text` in place of `text` when there is one.
Show properties
actionstringrequired
The computer action name.
textstring
The text of a `type` (or the keys of a `key`), as sent.
inputobjectrequired
The whole action body as the caller sent it (a ComputerActionRequest).
reviewInterventionReview
A review request. When `path` is set, `content` is that file as fuse read it at request time, so the human reviews what the agent submitted even if the file changed afterwards.
Show properties
pathstring
contentstringrequired
formatstringrequired
Allowed:textdiff
messagestring
The agent's note to the reviewer.
truncatedboolean
Set when the file was longer than 1 MiB and was cut off.
deciderInterventionDecider
What a gate's decider said about an action it sent on to a human: `verdict` `ask` with its `reason`, or the `error` that made fuse fall through to a human.
Show properties
verdictstringrequired
Allowed:ask
reasonstring
errorstring
Set when the decider call failed.
triggered_byActorrequired
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
deadlinestring<date-time>required
on_timeoutstringrequired
Allowed:rejectallow
decisionobject
Present once terminal. An expired intervention carries the on_timeout outcome and a cancelled one a reject, both decided by "system".
Show properties
outcomestringrequired
Allowed:approvereject
answerstring
reasonstring
decided_byActorrequired
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
decided_atstring<date-time>required
edited_argvstring[]
The argv the approver replaced a held exec's with.
edited_textstring
The text the approver replaced a held `type` action's with.
grantstring
How far an approval of a gated action reaches.
resultInterventionResult
What performing an approved gated action produced.
Show properties
execExecEnvironmentResponse
The outcome of a guest command. A non-zero `exit_code` arrives with **HTTP 200**: the command ran and failed, which is a successful answer to the question the caller asked. It is not an error and must not be raised by an SDK. HTTP errors mean the command could not be run at all. `stdout` and `stderr` are kept apart, and are plain strings rather than base64 — exec output is overwhelmingly text, and encoding it would make every caller pay a decoding tax for the rare binary case.
Show properties
exit_codeintegerrequired
The guest command's own exit status. Non-zero is a normal result, delivered with HTTP 200.
stdoutstringrequired
stderrstringrequired
computerComputerActionResponse
The guest's answer to one action.
Show properties
outputstring
Textual output, e.g. the pointer location for `cursor_position`.
screenshotstring
Base64 PNG of the display after the action settled. Present on every action that implies one; for `zoom` it is the cropped region at full resolution.
env_idstring
The environment a fork or migrate produced.
snapshot_idstring
The snapshot a snapshot action produced.
errorstring
Set when the approved action could not be performed. A non-zero exec exit code is a result in `exec`, not an error.
finished_atstring<date-time>required
created_atstring<date-time>required
updated_atstring<date-time>required
201Fork succeeded (body is the new Environment), or a `request` was raised (body is the pending Intervention; wait on it with GET /v1/interventions/{interventionId}?wait=).
One of:
Environment
idstringrequired
Fleet-assigned VM identifier (prefix + task_id).
statestringrequired
Allowed:provisioningrunningdrainingdestroying
task_idstringrequired
Empty when the VM is being torn down.
host_idstring
Scheduler-assigned host ID when placement uses the host registry.
urlstringrequired
host:port address where the guest agent (fused) is reachable, via per-VM DNAT. Empty before the VM is running.
specResourceSpecrequired
Hardware requirements for a VM. No lower bound is declared on cpus/ram_mb because the server does not enforce one: createEnvironment validates only task_id and the GPU fields, so a spec with `cpus: 0` / `ram_mb: 0` is accepted and scheduled. Callers should still send positive values; a strict request validator must not reject zero, or it will refuse payloads the API accepts.
Show properties
cpusinteger<int32>
min 0
ram_mbinteger<int32>
min 0
storage_gbinteger<int32>
min 0
gpusinteger<int32>
Count of GPU devices requested. Zero means no GPU. With gpu_profile unset, this is whole devices; with gpu_profile set, this is the count of MIG instances of that profile (decision D5).
min 0
gpu_kindstring
Optional GPU model to match (e.g. "a100"). Empty matches any kind on a host that has GPUs.
gpu_profilestring
Optional MIG profile in mig-parted vocabulary (e.g. "1g.10gb"). When set, gpus counts MIG instances of this profile rather than whole devices, and the qemu host agent attaches them via vfio-pci sysfsdev (decision D5).
imagestring
Optional named base rootfs for the provider to boot from (resolved by the host agent against its named-rootfs directory). Empty means the provider's default base image.
regionstring
host_idstring
Pins the environment to an exact host id (the Fusefile's placement.host). A pin is a hard gate, not an override: the host must still be active, run the right backend, and fit the request. An unknown host id is rejected with 404 before any VM is created.
labelsobject
Placement label selectors (the Fusefile's placement.labels). Every pair must match the target host's operator-declared labels. A selector that matches no host is rejected with 503, never queued.
huge_pagesboolean
Back guest memory with 2M pages. The host must have that much memory reserved as hugepages, or the create answers 409. Fixed for the life of the environment, and required for a lazy migrate.
max_runtime_secondsinteger<int64>
Leak-detection ceiling for this task. Zero means "use the fleet default". The orchestrator tears down tasks that exceed this age with no state transitions.
idle_timeout_secondsinteger<int64>
Destroys the environment once it has gone this long with no exec and no attach session. Zero means "use the fleet default", which is no idle expiry unless the operator configured one. Measured from the last exec or attach, not from create, and must be at least 60 (idle detection runs on the reconcile loop). In-guest CPU use and traffic on exposed ports are not observed.
created_atstring<date-time>required
updated_atstring<date-time>required
errorstring
Last failure message, empty on the happy path.
endpointsEndpoint[]
Published network endpoints for ports requested via the create request's `expose` list. Omitted when none.
Show properties
Array of Endpoint
asstring
Caller-chosen label from the expose request.
urlstringrequired
Reachable address, e.g. "http://203.0.113.5:41231".
protocolstring
The transport this endpoint was actually published on, which is not always what was requested: a host agent too old to know about the field publishes tcp and omits this. Read it rather than assuming the request was honoured.
Allowed:tcpudp
portintegerrequired
The guest-side port this endpoint publishes.
healthobject
Last verdict of the environment-level healthcheck. Omitted when the environment declared no healthcheck, and omitted until the first verdict has been read back from the guest. The orchestrator refreshes it on the reconcile tick (30s by default), so it lags the guest by up to one tick.
Show properties
statestringrequired
The probe's last verdict. Deliberately separate from `Environment.state`: an unhealthy environment is still a running one, and nothing tears it down for a failing probe.
Allowed:startingpassingfailing
sincestring<date-time>
When the probe entered this state.
failuresinteger
Consecutive failed attempts. Zero while passing.
messagestring
The last attempt's failure detail. Empty while passing.
egressobject
The resolved outbound policy. Always present on a server that knows about egress: an environment created without asking reports `direct`, so a caller can tell "not proxied" from "this server predates the field".
Show properties
modestringrequired
Allowed:directproxy
providerstring
The backend serving this environment. Proxy only.
protocolstring
Proxy only.
Allowed:socks5http
endpointstring
The proxy url the workload was handed, e.g. `socks5h://10.200.3.1:1080`. A host-local address useless to anyone not already inside the sandbox, and never a credential. Proxy only.
healthobject
The endpoint's last probe verdict. Proxy only, and `unknown` until the reconcile tick (30s by default) has probed it once. An unhealthy proxy reports and nothing acts on it: the environment keeps running with no egress, never with direct egress.
Show properties
statestringrequired
Allowed:unknownhealthyunhealthy
reasonstring
The backend-level failure, e.g. `dial tcp 10.200.3.1:1080: connection refused`. Empty while healthy. Never a destination hostname or anything drawn from the sandbox's traffic.
checked_atstring<date-time>
Intervention
idstringrequired
env_idstringrequired
kindstringrequired
Allowed:asksecrettakeoverreviewexeclifecyclecomputerstallexpiry
gatestring
The gate that raised it. Empty for a request.
modestring
The gate's mode. Notify and deny records are born terminal.
Allowed:asknotifydeny
statestringrequired
Allowed:pendingapprovedrejectedexpiredcancelled
payloadobjectrequired
What was asked or attempted: `question` for an ask, `secret`, `takeover` or `review` for those requests, `exec`, `lifecycle` or `computer` for a gate, `signal` for a stall or expiry. `decider` is set when a gate's decider sent the action on to a human.
Show properties
questionstring
choicesstring[]
execExecPayload
A held exec.
Show properties
argvstring[]required
shellstring
The script when the caller sent `shell`; argv is then the sh -lc that runs it.
timeout_msinteger<int64>
lifecycleLifecyclePayload
A held environment action.
Show properties
actionstringrequired
Allowed:destroyforkmigratedrainsnapshotrotate-token
secretInterventionSecret
A secret request. It never holds the value.
Show properties
targetstringrequired
The declared target's `env` name or `file` path.
labelstringrequired
The target's label from the policy. Show it first: the agent writes `message`, so `message` alone could claim to be anything.
messagestring
The agent's own text.
takeoverInterventionTakeover
A takeover. `holder` and `started_at` are set while a human holds the environment, which is also when the agent's exec and computer calls get 423. The intervention stays `pending` until release.
Show properties
viastringrequired
Allowed:terminaldesktop
reasonstring
holderActor
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
started_atstring<date-time>
signalInterventionSignal
What fuse saw when it raised a stall or expiry. A stall carries `failures` and `last_exit_code`, or `quiet_seconds`. An expiry carries `reaper` and `reap_at`, and once approved `extended_until`.
Show properties
failuresinteger
The run of consecutive non-zero exec exits.
last_exit_codeinteger
The exit code that completed the run.
quiet_secondsinteger<int64>
How long the agent had made no exec or computer call.
reaperstring
What will tear the environment down.
Allowed:idle_timeoutmax_runtime
reap_atstring<date-time>
When. The expiry's own deadline is capped at this, with a 10s floor.
extended_untilstring<date-time>
Set on approval. The reapers leave the environment alone until then.
computerComputerPayload
A held computer action. On approval the orchestrator replays `input` to the guest, with the approver's `edited_text` in place of `text` when there is one.
Show properties
actionstringrequired
The computer action name.
textstring
The text of a `type` (or the keys of a `key`), as sent.
inputobjectrequired
The whole action body as the caller sent it (a ComputerActionRequest).
reviewInterventionReview
A review request. When `path` is set, `content` is that file as fuse read it at request time, so the human reviews what the agent submitted even if the file changed afterwards.
Show properties
pathstring
contentstringrequired
formatstringrequired
Allowed:textdiff
messagestring
The agent's note to the reviewer.
truncatedboolean
Set when the file was longer than 1 MiB and was cut off.
deciderInterventionDecider
What a gate's decider said about an action it sent on to a human: `verdict` `ask` with its `reason`, or the `error` that made fuse fall through to a human.
Show properties
verdictstringrequired
Allowed:ask
reasonstring
errorstring
Set when the decider call failed.
triggered_byActorrequired
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
deadlinestring<date-time>required
on_timeoutstringrequired
Allowed:rejectallow
decisionobject
Present once terminal. An expired intervention carries the on_timeout outcome and a cancelled one a reject, both decided by "system".
Show properties
outcomestringrequired
Allowed:approvereject
answerstring
reasonstring
decided_byActorrequired
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
decided_atstring<date-time>required
edited_argvstring[]
The argv the approver replaced a held exec's with.
edited_textstring
The text the approver replaced a held `type` action's with.
grantstring
How far an approval of a gated action reaches.
resultInterventionResult
What performing an approved gated action produced.
Show properties
execExecEnvironmentResponse
The outcome of a guest command. A non-zero `exit_code` arrives with **HTTP 200**: the command ran and failed, which is a successful answer to the question the caller asked. It is not an error and must not be raised by an SDK. HTTP errors mean the command could not be run at all. `stdout` and `stderr` are kept apart, and are plain strings rather than base64 — exec output is overwhelmingly text, and encoding it would make every caller pay a decoding tax for the rare binary case.
Show properties
exit_codeintegerrequired
The guest command's own exit status. Non-zero is a normal result, delivered with HTTP 200.
stdoutstringrequired
stderrstringrequired
computerComputerActionResponse
The guest's answer to one action.
Show properties
outputstring
Textual output, e.g. the pointer location for `cursor_position`.
screenshotstring
Base64 PNG of the display after the action settled. Present on every action that implies one; for `zoom` it is the cropped region at full resolution.
env_idstring
The environment a fork or migrate produced.
snapshot_idstring
The snapshot a snapshot action produced.
errorstring
Set when the approved action could not be performed. A non-zero exec exit code is a result in `exec`, not an error.
finished_atstring<date-time>required
created_atstring<date-time>required
updated_atstring<date-time>required
202A hitl gate holds the action (exec, fork, migrate, drain or rotate-token). Nothing ran yet. The body is a HeldResponse naming the pending intervention, and `Location` points at it. Wait on it with GET /v1/interventions/{interventionId}?wait=; once approved the orchestrator performs the action and stores the outcome in the intervention's `result`.
intervention_idstringrequired
interventionInterventionrequired
Show properties
idstringrequired
env_idstringrequired
kindstringrequired
Allowed:asksecrettakeoverreviewexeclifecyclecomputerstallexpiry
gatestring
The gate that raised it. Empty for a request.
modestring
The gate's mode. Notify and deny records are born terminal.
Allowed:asknotifydeny
statestringrequired
Allowed:pendingapprovedrejectedexpiredcancelled
payloadobjectrequired
What was asked or attempted: `question` for an ask, `secret`, `takeover` or `review` for those requests, `exec`, `lifecycle` or `computer` for a gate, `signal` for a stall or expiry. `decider` is set when a gate's decider sent the action on to a human.
Show properties
questionstring
choicesstring[]
execExecPayload
A held exec.
Show properties
argvstring[]required
shellstring
The script when the caller sent `shell`; argv is then the sh -lc that runs it.
timeout_msinteger<int64>
lifecycleLifecyclePayload
A held environment action.
Show properties
actionstringrequired
Allowed:destroyforkmigratedrainsnapshotrotate-token
secretInterventionSecret
A secret request. It never holds the value.
Show properties
targetstringrequired
The declared target's `env` name or `file` path.
labelstringrequired
The target's label from the policy. Show it first: the agent writes `message`, so `message` alone could claim to be anything.
messagestring
The agent's own text.
takeoverInterventionTakeover
A takeover. `holder` and `started_at` are set while a human holds the environment, which is also when the agent's exec and computer calls get 423. The intervention stays `pending` until release.
Show properties
viastringrequired
Allowed:terminaldesktop
reasonstring
holderActor
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
started_atstring<date-time>
signalInterventionSignal
What fuse saw when it raised a stall or expiry. A stall carries `failures` and `last_exit_code`, or `quiet_seconds`. An expiry carries `reaper` and `reap_at`, and once approved `extended_until`.
Show properties
failuresinteger
The run of consecutive non-zero exec exits.
last_exit_codeinteger
The exit code that completed the run.
quiet_secondsinteger<int64>
How long the agent had made no exec or computer call.
reaperstring
What will tear the environment down.
Allowed:idle_timeoutmax_runtime
reap_atstring<date-time>
When. The expiry's own deadline is capped at this, with a 10s floor.
extended_untilstring<date-time>
Set on approval. The reapers leave the environment alone until then.
computerComputerPayload
A held computer action. On approval the orchestrator replays `input` to the guest, with the approver's `edited_text` in place of `text` when there is one.
Show properties
actionstringrequired
The computer action name.
textstring
The text of a `type` (or the keys of a `key`), as sent.
inputobjectrequired
The whole action body as the caller sent it (a ComputerActionRequest).
reviewInterventionReview
A review request. When `path` is set, `content` is that file as fuse read it at request time, so the human reviews what the agent submitted even if the file changed afterwards.
Show properties
pathstring
contentstringrequired
formatstringrequired
Allowed:textdiff
messagestring
The agent's note to the reviewer.
truncatedboolean
Set when the file was longer than 1 MiB and was cut off.
deciderInterventionDecider
What a gate's decider said about an action it sent on to a human: `verdict` `ask` with its `reason`, or the `error` that made fuse fall through to a human.
Show properties
verdictstringrequired
Allowed:ask
reasonstring
errorstring
Set when the decider call failed.
triggered_byActorrequired
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
deadlinestring<date-time>required
on_timeoutstringrequired
Allowed:rejectallow
decisionobject
Present once terminal. An expired intervention carries the on_timeout outcome and a cancelled one a reject, both decided by "system".
Show properties
outcomestringrequired
Allowed:approvereject
answerstring
reasonstring
decided_byActorrequired
Show properties
idstringrequired
A pinned or asserted actor id, `key:<key_id>`, `master`, `system` for fuse itself, or `decider:<gate>`.
namestring
sourcestringrequired
`pinned`: fixed on the key at mint time. `asserted`: named in `Fuse-Actor` by a `hitl:act-as` key or the master token, and only as true as that caller's own auth. `key`: derived from the credential. `system`: expiry and cancellation. `decider`: a gate's decider allowed or denied the action; the id is `decider:<gate>`.
Allowed:pinnedassertedkeysystemdecider
key_idstring
The key that authenticated the request, including the key that asserted an actor. Omitted for the master token.
decided_atstring<date-time>required
edited_argvstring[]
The argv the approver replaced a held exec's with.
edited_textstring
The text the approver replaced a held `type` action's with.
grantstring
How far an approval of a gated action reaches.
resultInterventionResult
What performing an approved gated action produced.
Show properties
execExecEnvironmentResponse
The outcome of a guest command. A non-zero `exit_code` arrives with **HTTP 200**: the command ran and failed, which is a successful answer to the question the caller asked. It is not an error and must not be raised by an SDK. HTTP errors mean the command could not be run at all. `stdout` and `stderr` are kept apart, and are plain strings rather than base64 — exec output is overwhelmingly text, and encoding it would make every caller pay a decoding tax for the rare binary case.
Show properties
exit_codeintegerrequired
The guest command's own exit status. Non-zero is a normal result, delivered with HTTP 200.
stdoutstringrequired
stderrstringrequired
computerComputerActionResponse
The guest's answer to one action.
Show properties
outputstring
Textual output, e.g. the pointer location for `cursor_position`.
screenshotstring
Base64 PNG of the display after the action settled. Present on every action that implies one; for `zoom` it is the cropped region at full resolution.
env_idstring
The environment a fork or migrate produced.
snapshot_idstring
The snapshot a snapshot action produced.
errorstring
Set when the approved action could not be performed. A non-zero exec exit code is a result in `exec`, not an error.
finished_atstring<date-time>required
created_atstring<date-time>required
updated_atstring<date-time>required
204Action succeeded with no body. Always for rotate-token; for drain and fork only in the rare race where the action succeeded but the environment record could not be re-read to build a response body.
400Malformed request.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
403A hitl gate in `deny` mode refused the action (code `forbidden`, `details.reason` `hitl_denied`, `details.gate` the gate's name, `details.intervention_id` the terminal record; the message is the gate's `reason`), or the caller may not use the route.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
404Resource does not exist. Note the distinct code `route_not_found`, returned when the URL matches no registered route at all (wrong host, port, or path prefix) rather than a known route with a missing resource.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
409Conflicts with current state (e.g. duplicate task assignment).
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
423A human holds the environment, so the agent's call was refused before it reached the guest (code `locked`). Either a takeover is held (`details.kind` `takeover`), or a stall in `ask` mode is waiting for a human to ack it (`details.kind` `stall`). `details.intervention_id` names the intervention. Long-poll it with GET /v1/interventions/{interventionId}?wait= until it is no longer `pending`, then send the call again; a new 423 means wait again. The lock never outlives the intervention's deadline, so this always ends. The SDKs wait and retry by default, and raise a `LockedError` carrying the intervention id and kind when told not to wait.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
500Unexpected server error.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
501The operation is not supported by the backing provider (e.g. an exec or attach against an environment with no real guest).
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).
Request
curl -X POST "http://localhost:8080/v1/environments/string?action=rotate-token" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "cmd": [
    "ls",
    "-l"
  ],
  "timeout_ms": 5000
}'
Response
{
  "id": "string",
  "state": "provisioning",
  "task_id": "string",
  "host_id": "string",
  "url": "string",
  "spec": {
    "cpus": 0,
    "ram_mb": 0,
    "storage_gb": 0,
    "gpus": 0,
    "gpu_kind": "string",
    "gpu_profile": "string",
    "image": "string",
    "region": "string",
    "host_id": "string",
    "labels": {},
    "huge_pages": true,
    "max_runtime_seconds": 0,
    "idle_timeout_seconds": 0
  },
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "error": "string",
  "endpoints": [
    {
      "as": "string",
      "url": "string",
      "protocol": "tcp",
      "port": 0
    }
  ],
  "health": {
    "state": "starting",
    "since": "2024-01-01T00:00:00Z",
    "failures": 0,
    "message": "string"
  },
  "egress": {
    "mode": "direct",
    "provider": "string",
    "protocol": "socks5",
    "endpoint": "string",
    "health": {
      "state": "unknown",
      "reason": "string",
      "checked_at": "2024-01-01T00:00:00Z"
    }
  }
}