Set up the sandbox

The sandbox lets the Sazabi agent run command-line tools against your systems during an investigation — your cloud CLI, a database client, or your own tooling. By the end of this guide you will have a CLI connected and confirmed working. Connecting one CLI takes a few minutes.

What the sandbox is

The sandbox is an isolated, ephemeral environment the agent gets for a thread. It starts fresh, runs the commands the agent needs, and does not persist between threads. Common languages and CLIs are available, and you add more by connecting sandbox CLIs or a custom CLI. Nothing you connect leaks between threads, and each thread's sandbox is its own.

CLIs

The sandbox comes with common languages and CLIs preinstalled, and you set up more for the agent in two ways: connect a sandbox CLI, or add a custom CLI.

Sandbox CLIs

A sandbox CLI is a more convenient way to set up a common CLI: Sazabi already knows how to install and authenticate the tool, so you supply credentials once and it is ready at the start of every thread in the project. Connecting a sandbox CLI creates a CLI connection.

Browse the catalog under Settings > Sandbox CLIs. It covers cloud CLIs, database clients, and platform tools, and each entry knows its own executable, the environment variables it needs, and how to test that a credential works. See Sandbox CLIs for the full list.

Connecting sandbox CLIs

You connect a sandbox CLI from the dashboard, or with the Sazabi CLI (see CLI reference) — the agent uses whichever you connect. (Custom CLIs are covered separately below.)

In the dashboard

1. Go to Settings > Sandbox CLIs and choose a sandbox CLI under Browse sandbox CLIs.
2. Enter the credentials it asks for. Prefer least-privilege or read-only credentials wherever possible.
3. Click Connect. Sazabi runs the CLI's test command against your credentials and reports whether the connection works.

With the CLI

List the available CLI types, test credentials without saving, then save the connection:

sazabi sandbox-clis types                                 # List available CLIs and the env vars each needs
sazabi sandbox-clis test --type aws --env-file creds.json # Run the sandbox CLI's test command against your credentials
sazabi sandbox-clis set --type aws --env-file creds.json  # Save the connection for every thread in the project

Pass credentials as repeated --env KEY=VALUE flags (use KEY=@file to read a value from a file, or --env-file for a JSON object of names and values). sazabi sandbox-clis set runs the same connection test the dashboard does before saving. Some sandbox CLIs have an agent-ready setup skill — sazabi sandbox-clis skill --type <type> prints it.

Custom CLIs

When a tool you need is not in the catalog — an internal tool, a niche vendor CLI, or something you install from your own package source — add it as a custom CLI under Settings > Sandbox CLIs. Adding a custom CLI requires member access or higher. Prefer a sandbox CLI when one exists: sandbox CLIs are baked into the sandbox image and validate credentials for you. Custom CLIs — a setup script plus environment variables for a tool Sazabi does not already know — are configured in the dashboard only; the CLI's sazabi sandbox-clis commands manage catalog sandbox CLIs. If the tool you need later joins the catalog, connect it with sazabi sandbox-clis set --type <type> instead.

Setup script

The setup script runs when a sandbox starts, as the sazabi user with passwordless sudo for commands that need root. Enter the shell commands that install the tool and prepare the environment, so the executable is available to the agent during the thread. For example:

# Install a CLI from your package registry
npm install -g @example/mycli
mycli --version

Environment variables

Add the credentials and configuration the CLI reads as environment variables — key/value pairs (for example MYCLI_TOKEN), one row per variable the tool expects. Values are stored encrypted and injected into the sandbox for the agent's commands.

Security model

• The sandbox has outbound internet access. That is how connected CLIs reach your vendors' APIs, databases, and clouds during an investigation. Egress comes from shared infrastructure with no static IP addresses, so control what the agent can reach with credentials and scopes rather than network rules — a CLI with no credentials cannot act on your systems.
• Ephemeral and isolated. Each thread gets a fresh sandbox that does not persist afterward, so nothing carries over between investigations, and one thread's sandbox can never see another's.
• Bounded runtime. A sandbox runs for a bounded period (up to about 45 minutes) before it is torn down.
• Least privilege. Because the agent can run whatever the connected CLI allows, connect read-only or narrowly scoped credentials so the blast radius of any command is small.

The controls you configure:

• What is available. The agent can only use the sandbox CLIs and custom CLIs you connect; pause or remove a connection under Settings > Sandbox CLIs and it is gone from the next sandbox.
• What each tool can do. The credential you supply is the tool's authority — scope it tightly, and every sandbox CLI validates its credential with a connection test before saving.
• How credentials are handled. Values are stored encrypted and injected only into the sandbox at run time; rotate them by re-entering under Settings > Sandbox CLIs or with sazabi sandbox-clis set.

Verify

Confirm a connected CLI actually works from inside an investigation.

1. Connect a sandbox CLI (for example your cloud CLI) and click Connect — the test should report success.
2. Open a thread and ask the agent to run a harmless read-only command with that CLI, such as: Use the AWS CLI to list my S3 buckets.
3. The agent runs the command in the sandbox and returns the real output from your account (your actual bucket names), shown in a tool call you can expand.

If the command fails with an authentication error, re-open the CLI connection in Settings > Sandbox CLIs, re-enter the credentials, and click Connect to re-test.

For a custom CLI, ask the agent to run the tool the same way (for example "run mycli whoami"). If the command is not found, check that the setup script installs the binary onto the PATH; if it runs but is unauthenticated, confirm the required environment variables are set.

Further reading