Borealis Docs

Create your first sandbox

Start with a small Linux environment and confirm that it is running before you send it work.

Before you begin

Sign in to Borealis, select the organisation you want to work in, and check that you have sandbox creation permission and available capacity. New accounts can register here.

Create in the app

  1. Open the sandboxes view and choose Create.
  2. Enter a name, such as my-first-sandbox.
  3. Choose ubuntu:24.04 as the container image.
  4. Set Command to sleep and Args (JSON Array) to ["infinity"]. This keeps the example container running after startup.
  5. Review CPU Cores, Memory (GB), Idle Timeout (minutes), and Placement. Use a pool available to your account.
  6. Create the sandbox and wait until its status is running.

Image downloads and placement can take time. An accepted creation request is not a signal that commands can run yet.

Create with the CLI

With Node.js 22 or newer installed:

npm install --global @amaretto-software-labs/borealis-cli
borealis auth login
borealis context show --json
borealis sandbox create --body '{"name":"my-first-sandbox","image":"ubuntu:24.04","command":"sleep","args":["infinity"]}'

Keep the returned sandbox ID. Replace SANDBOX_ID in subsequent examples with that ID.

borealis sandbox get SANDBOX_ID --json

When it is running, execute a small command:

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

The execution has its own ID and status. Use borealis sandbox exec get SANDBOX_ID EXEC_ID --json to inspect the result.

Finish safely

Stop the sandbox when you no longer need its running compute:

borealis sandbox stop SANDBOX_ID

Stop ends running processes; it is not a memory snapshot. Before deleting an environment, preserve anything you need using snapshots and workspace exports. See the lifecycle guide for how these operations differ.