Borealis Docs

Commands and interactive terminals

Use exec for a tracked unit of work and an interactive session when you need a terminal conversation.

Run a command

Wait for the sandbox to be running. Then pass a command and argument array:

borealis sandbox exec SANDBOX_ID --body '{"command":"sh","args":["-lc","pwd"],"timeoutSeconds":60}'

Replace SANDBOX_ID with your sandbox ID. Exec also supports a working directory and per-command environment values. Shell operators are interpreted only when you explicitly run a shell; they are not part of the argument-array protocol.

The returned execution ID identifies this run:

borealis sandbox exec get SANDBOX_ID EXEC_ID --json

Check the execution’s status and exit code. An accepted request is not a successful command, and container logs are not a substitute for execution output.

Open a terminal

Create an interactive session, then attach using its returned session ID:

borealis interactive create SANDBOX_ID
borealis interactive attach SESSION_ID

Interactive sessions support input, output, and terminal resizing. Treat the session as a resource with its own lifetime. Disconnecting a client, ending a shell, stopping a session, and stopping the sandbox are distinct actions; inspect status before assuming work has ended.

Handle interruptions

A host restart or runtime loss can make an execution unavailable. Reconnect or query its status before deciding to rerun it. A failed connection does not prove the command never ran.

Do not automatically repeat a non-idempotent command, such as a database migration or a payment request, after losing its response. Record application-level checkpoints where needed.

Supply sensitive inputs carefully

Inspect borealis sandbox capabilities SANDBOX_ID --json before relying on sensitive execution support. Ordinary environment variables may be visible in container metadata. Sensitive inputs and output redaction reduce exposure in supported paths, but the code you run can still read and disclose its inputs. See security.