Back to blog
A fan of translucent teal glass chambers with a larger mint chamber in front.
Update

Automate Borealis with the CLI, API, and MCP

Create sandboxes, run commands, and follow their progress from your terminal, your application, or an MCP client.

Borealis Team

A sandbox often starts as an interactive session: choose an image, run a command, and inspect the result. Once the workflow is useful, you may want to repeat it from a script, connect it to an application, or let an agent operate it on your behalf.

Borealis supports those workflows through its command-line interface, public API, and hosted MCP service. They work with the same sandbox resources, so you can choose the interface that fits the task and still open the environment in the Borealis app when you need to inspect it.

Start in the terminal

The CLI is a straightforward way to explore your account and turn familiar actions into repeatable commands. Install it with Node.js 22 or newer, then sign in:

npm install --global @amaretto-software-labs/borealis-cli
borealis auth login
borealis context show --json

Check the organisation context before creating anything. Then request a small environment:

borealis sandbox create --body '{"name":"automation-demo","image":"ubuntu:24.04","command":"sleep","args":["infinity"]}' --json

The startup command keeps this example container alive. Save the returned sandbox ID and replace SANDBOX_ID below with it. Creation can take time, so inspect the sandbox until it is running:

borealis sandbox get SANDBOX_ID --json

Now run a command and inspect the execution using its returned ID:

borealis sandbox exec SANDBOX_ID --body '{"command":"sh","args":["-lc","printf hello"],"timeoutSeconds":60}' --json
borealis sandbox exec get SANDBOX_ID EXEC_ID --json

Replace EXEC_ID with the execution ID from the previous response. Check its status and exit code before reporting success. When you have finished with the example, stop the sandbox:

borealis sandbox stop SANDBOX_ID

For scripts, use --json to read structured responses instead of parsing terminal formatting. Supply automation credentials through BOREALIS_ACCESS_TOKEN or a protected --token-file, rather than placing a token directly in command arguments.

The CLI guide covers profiles, organisation selection, and command discovery. The official CLI repository contains its source and usage reference.

Call the API from your application

Use the public HTTP API when sandbox operations need to fit into your own application or service. The production base URL is https://api.borealishq.io/api/v1.

For example, a tool with an appropriately scoped API access token can list sandboxes:

curl --fail-with-body \
  --header "Authorization: Bearer $BOREALIS_ACCESS_TOKEN" \
  'https://api.borealishq.io/api/v1/sandboxes?page=1&pageSize=50'

The token must already be supplied securely in the environment. An integration can select an authorised organisation with the X-Organization-Id header, choosing among the organisations its token already reaches.

An application might create an environment for a job, wait for it to become ready, execute work, collect the result, and stop the sandbox. The API also provides operations for templates, registries, snapshots, workspace transfers, and eligible host pools. Each operation remains subject to its permissions and account limits.

Start with the public API guide for request examples, authentication, and operation handling. You can call the API from the language and HTTP tooling your application already uses.

Give an MCP client access to sandbox tools

The hosted Model Context Protocol service makes Borealis operations available as tools to compatible clients. Add this remote server URL in a client that supports Streamable HTTP and OAuth discovery:

https://mcp.borealishq.io/mcp

Follow the client’s Borealis sign-in and consent flow, then start with a read operation such as context_get or sandbox_list. Once the context is right, tools such as sandbox_create and sandbox_exec_start let the client request work in an environment.

Give the agent a bounded task. For example: inspect a particular sandbox, run a named test command, report its result, and ask before deleting anything. The client should follow the returned operation state rather than treating acceptance as completion.

MCP uses its own OAuth audience, so it needs its own credential rather than an existing API token. See the MCP setup guide for connection and permission details.

Make automation reliable

Whichever interface you use, the work still needs following.

  • Keep resource and operation IDs. A sandbox, execution, snapshot request, and workspace transfer have different lifetimes. Follow the operation that answers your question.
  • Preserve idempotency keys. If a keyed mutation times out, reuse its original key and request body when retrying. The CLI generates keys and accepts an explicit --idempotency-key; raw API integrations must follow each operation’s key requirements.
  • Check before repeating work. Losing a response does not prove that a command never ran. Be especially careful with commands that change external systems.
  • Confirm destructive actions. Review targets before approving deletion or replacing workspace files. The CLI and MCP flows include confirmation handling for destructive operations.
  • Use only the access you need. Keep credentials out of repositories and prompts, choose the right organisation, and stop environments when their work is finished.

You can begin with one CLI command, move a repeatable workflow into your application, or expose a bounded task through MCP. The first sandbox guide is a good starting point for all three.