Commands

A command is a top-level process invocation record. You run commands inside a sandbox either synchronously (run, which waits for exit) or asynchronously (start, which returns immediately), then inspect the result, cancel it, or follow its logs.

Run vs start

CrowNest offers two ways to execute a command, and the right one depends on how long the process runs.

• POST /v1/sandboxes/{id}/commands/run waits for the process to exit and returns the completed command, including exitCode, stdout, and stderr. It also accepts collect and collectOn to export artifacts when the command finishes.
• POST /v1/sandboxes/{id}/commands/start returns 202 immediately with the command in status queued or starting. Poll GET /v1/commands/{commandId} or follow the log stream to track it. start doesn't accept collect or collectOn.

Both endpoints take command (required, non-empty), plus optional cwd, env, and timeoutMs. Both are idempotent with an Idempotency-Key header. We recommend run for short tasks and start for servers and long-running work.

Statuses

The status field tracks the command through its lifecycle.

Exit codes vs API errors

A non-zero exit code is not an API error. If your process runs and exits with status 3, the API call still succeeds: the command has status exited and exitCode: 3. Check status and exitCode on the command object to decide whether the work succeeded.

API errors (the { "error": { "code", ... } } envelope) mean the request itself failed — for example invalid_request, forbidden, not_found, sandbox_destroyed, quota_exceeded, or command_timed_out.

Timeouts

Every command has a timeout. timeoutMs defaults to 60000 ms (1 minute) and accepts up to 600000 ms (10 minutes). A command that exceeds its timeout ends with status timed_out. Plan-level command duration limits also apply; they're configurable beta defaults, so check your plan.

Environment variables

Pass env as a string map to set environment variables for the process. Two rules apply:

• You can't set keys with the reserved CROWNEST prefix; doing so returns reserved_env_key. See injected environment context.
• Values are ephemeral and never persisted. Pass them on each command.

Cancellation

Cancel a running command with POST /v1/commands/{commandId}/cancel. The body takes an optional mode:

• graceful (default) — asks the process to terminate (SIGTERM).
• force — kills the process immediately (SIGKILL).

The canceled command records cancelMode, canceledAt, and terminationSignal. Cancellation is idempotent by state: canceling an already-finished command doesn't error.

Logs

Command output is captured as ordered chunks, each with a sequence number (seq) and a stream (stdout or stderr). There are three ways to get logs.

Paginated chunks

GET /v1/commands/{commandId}/logs returns { data, hasMore, nextSeq? }. Query parameters: stream (stdout, stderr, or combined, default combined), afterSeq, and limit (default 50, max 100). Page with afterSeq=nextSeq until hasMore is false.

Live SSE stream

GET /v1/commands/{commandId}/stream is a server-sent events stream. Event types are log, heartbeat, terminal, and error, with fields seq, type, timestamp, data, and stream. Resume after a disconnect with the afterSeq query parameter or the Last-Event-ID header. If you resume from a sequence outside the retention window, the stream returns a stream_gap error.

Full download

POST /v1/commands/{commandId}/logs/download-url with body { stream } returns { url, method: "GET", expiresAt } — a short-lived URL for the complete log of that stream.

Output truncation

The stdout and stderr fields inlined on the command object can be truncated for large outputs; stdoutTruncated and stderrTruncated tell you when that happened. To get the full output, page through the logs endpoint or request a log download URL.

Next steps

• Sandboxes — lifecycle and TTL behavior that affects running commands.
• Artifacts — export files with collect and collectOn.
• SDK quickstart — run your first command.
• Commands API reference