Get Started
Quickstart
1. Prerequisites
Section titled “1. Prerequisites”- A Chainguard account and organization. Sign up at console.chainguard.dev/workspaces/signup. The sign-up flow asks for your new organization’s details: finish creating the organization before you go on. If you already belong to a Chainguard organization, you can use that one. Accounts and organizations are managed in the Chainguard Console at console.chainguard.dev.
- Workspaces turned on for that organization. A new organization starts with it off. Step 4 below turns it on; it needs the owner role, which you have in an organization you created.
- One language toolchain:
2. Create a Project and Install the SDK
Section titled “2. Create a Project and Install the SDK”The packages aren’t on package registries yet; they install from the
chainguard-sandbox-sdk repository. Start in
any directory you keep projects in. These commands create a new project directory, my-app, and add
the SDK to it. Run every later command on this page from my-app.
mkdir my-app && cd my-appuv inituv add "chainguard-sandbox-sdk @ git+https://github.com/sandboxing-dev/chainguard-sandbox-sdk#subdirectory=python"To add it to a project you already have, run only the uv add line in that project’s directory (the
one with its pyproject.toml).
To work from a clone of the repository instead, no project is needed: the clone’s python directory is
a project with the CLI and the example programs in it, and uv run installs what it needs on first use.
git clone https://github.com/sandboxing-dev/chainguard-sandbox-sdkcd chainguard-sandbox-sdk/pythonThe Python commands below work unchanged from chainguard-sandbox-sdk/python.
git clone https://github.com/sandboxing-dev/chainguard-sandbox-sdkmkdir my-app && cd my-appbun init -ybun add ../chainguard-sandbox-sdk/typescriptBun can’t install a package from a subdirectory of a Git repository, so the repository is cloned next
to your project and added by path. ../chainguard-sandbox-sdk/typescript is that path as seen from
my-app; if your project lives elsewhere, use the path from it to the clone’s typescript directory.
To work in the clone itself, without a project of your own, install its dependencies once:
cd chainguard-sandbox-sdk/typescriptbun installThe package also runs on Node.js: Node.js needs the compiled files, so run bun run build (or
npm install && npm run build) in chainguard-sandbox-sdk/typescript first, then add it with
npm install ../chainguard-sandbox-sdk/typescript and run the CLI with npx --no-install chainguard-sandbox.
The TypeScript tabs below show both forms: the command for your own project, and the one to run from
chainguard-sandbox-sdk/typescript.
mkdir my-app && cd my-appgo mod init example.com/my-appgo get github.com/sandboxing-dev/chainguard-sandbox-sdk/go@latestIn a module you already have, run only the go get line.
To work from a clone of the repository instead, no project is needed: the clone’s go directory is a
Go module with the CLI and the example programs in it.
git clone https://github.com/sandboxing-dev/chainguard-sandbox-sdkcd chainguard-sandbox-sdk/goThe Go tabs below show both forms: the command for your own module, and the shorter one to run from
chainguard-sandbox-sdk/go.
cargo new my-app && cd my-appcargo add chainguard-sandbox-sdk --git https://github.com/sandboxing-dev/chainguard-sandbox-sdkcargo add tokio --features macros,rt-multi-threadcargo install chainguard-sandbox-sdk --git https://github.com/sandboxing-dev/chainguard-sandbox-sdkCargo finds the crate in the repository’s rust/ directory by its name. tokio is the async runtime the
SDK runs on. The last line installs the chainguard-sandbox command into ~/.cargo/bin: Cargo doesn’t run
a dependency’s commands from your project. In a project you already have, run only the two cargo add
lines there.
To work from a clone of the repository instead, no project is needed: the clone’s rust directory is a
Cargo package with the CLI and the example programs in it.
git clone https://github.com/sandboxing-dev/chainguard-sandbox-sdkcd chainguard-sandbox-sdk/rustThe Rust tabs below show both forms: the installed command, and the one to run from
chainguard-sandbox-sdk/rust.
3. Log In
Section titled “3. Log In”Log in once, with the CLI that comes with any of the packages. It opens your browser (add github,
google-oauth2 or gitlab to skip the provider choice):
uv run chainguard-sandbox login# the same command works in a clone of the repository, from its python/ directorybun run chainguard-sandbox login# or, in a clone of the repository, from its typescript/ directory:bun bin/chainguard-sandbox.ts logingo run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest login# or, in a clone of the repository, from its go/ directory:go run ./cmd/chainguard-sandbox loginchainguard-sandbox login# or, in a clone of the repository, from its rust/ directory:cargo run --bin chainguard-sandbox -- login- Where it’s saved:
~/Library/Application Support/chainguard-sandbox/login.json(macOS) or~/.config/chainguard-sandbox/login.json(Linux). All four packages share it. - How long it lasts: as long as it’s used at least once every 20 hours.
- If a run opens your browser, the saved login has expired. Approve it and the run continues, or renew
it ahead of time with the same
logincommand. - Skipping this step: the first sandbox call opens the browser itself.
Authentication explains what the login covers.
4. Enable Workspaces
Section titled “4. Enable Workspaces”Workspaces has to be turned on once for each organization, by one of its owners. Until it is, every
create fails with “this organization is not entitled to Chainguard Workspaces”.
First check where the organization stands (this changes nothing):
uv run chainguard-sandbox status# the same command works in a clone of the repository, from its python/ directorybun run chainguard-sandbox status# or, in a clone of the repository, from its typescript/ directory:bun bin/chainguard-sandbox.ts statusgo run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest status# or, in a clone of the repository, from its go/ directory:go run ./cmd/chainguard-sandbox statuschainguard-sandbox status# or, in a clone of the repository, from its rust/ directory:cargo run --bin chainguard-sandbox -- statusorganization: XXXXXXplan: Starterworkspaces: offgithub: no account linked yetterms: not accepted yet: - Secured Platform Terms: https://www.chainguard.dev/legal/secure-platform-terms - Master Service and License Agreement: https://www.chainguard.dev/legal/master-service-and-license-agreement - Code Analysis Terms: https://www.chainguard.dev/legal/code-analysis-terms - Terms of Service: https://www.chainguard.dev/legal/guardener - Data Privacy Agreement: https://www.chainguard.dev/legal/supplemental-dpaIf it says workspaces: on and terms: accepted, skip to the next step. Otherwise turn it on:
uv run chainguard-sandbox enable# the same command works in a clone of the repository, from its python/ directorybun run chainguard-sandbox enable# or, in a clone of the repository, from its typescript/ directory:bun bin/chainguard-sandbox.ts enablego run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest enable# or, in a clone of the repository, from its go/ directory:go run ./cmd/chainguard-sandbox enablechainguard-sandbox enable# or, in a clone of the repository, from its rust/ directory:cargo run --bin chainguard-sandbox -- enableenable does three things, in order:
- Terms. It lists the legal documents the organization has not accepted yet and asks you to type
yesto accept them on the organization’s behalf.--accept-termsanswers in advance. - GitHub. Chainguard requires a GitHub account to be linked to the organization before it turns
Workspaces on. Your browser opens GitHub, where you choose the account to link: your own user, or an
organization you own (name it with
--github ORG). The Chainguard GitHub App has to be installed on that account. If it isn’t,enableopens the install page, waits for you, and authorizes again. - Turn it on, with your plan’s allowance.
Add an organization ID at the end to choose the Chainguard organization. If port 8989 is taken on your
machine, pass another with --port.
5. Choose the Organization
Section titled “5. Choose the Organization”Every sandbox lives in a Chainguard organization, identified by a 40-character ID (the “instance”). There are three ways to say which one; the first one set wins:
| How | When to use it | |
|---|---|---|
| 1. In code | instance="XXXXXX" (Python), instance: "XXXXXX" (TypeScript), Instance: "XXXXXX" (Go), instance: "XXXXXX".into() (Rust) |
The program always uses one organization |
| 2. Environment variable | export CHAINCTL_SANDBOX_INSTANCE=XXXXXX (this terminal session) |
Choose per run or per environment |
| 3. Auto-detected | Nothing to set | You belong to exactly one organization |
- How auto-detection works: when neither 1 nor 2 is set, the library asks Chainguard’s account API which organizations you belong to, and uses the only one.
- With several organizations, it stops with an error listing them, and you pick one with 1 or 2.
- Turning it off: set
CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE=1.
To list your organization IDs:
uv run chainguard-sandbox orgs# the same command works in a clone of the repository, from its python/ directorybun run chainguard-sandbox orgs# or, in a clone of the repository, from its typescript/ directory:bun bin/chainguard-sandbox.ts orgsgo run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest orgs# or, in a clone of the repository, from its go/ directory:go run ./cmd/chainguard-sandbox orgschainguard-sandbox orgs# or, in a clone of the repository, from its rust/ directory:cargo run --bin chainguard-sandbox -- orgsID NAMEXXXXXX my-orgIn code: list_organizations() (Python, from chainguard_sandbox import list_organizations),
listOrganizations() (TypeScript, from chainguard-sandbox-sdk), sandbox.ListOrganizations(ctx) (Go), or
chainguard_sandbox::list_organizations().await (Rust).
Each returns the ID and name of every organization you belong to.
6. Create a Sandbox, Run a Command, Use Files
Section titled “6. Create a Sandbox, Run a Command, Use Files”Each program prints the sandbox’s host name and then hi:
Save this as quickstart.py in my-app:
from chainguard_sandbox import Sandbox
with Sandbox.create( packages=["bash", "coreutils", "python-3.13"], # instance="XXXXXX", # your organization ID; overrides $CHAINCTL_SANDBOX_INSTANCE and auto-detection) as sbx: # deleted on exit result = sbx.commands.run("""python3 -c "print('hello from', __import__('platform').node())" """) print(result.stdout, end="")
sbx.files.write("notes/hello.txt", "hi") print(sbx.files.read("notes/hello.txt"))uv run python quickstart.pyIn a clone of the repository the same program is examples/quickstart.py. From the clone’s python
directory:
uv run python examples/quickstart.pySave this as quickstart.ts in my-app:
import { Sandbox } from "chainguard-sandbox-sdk";
{ await using sbx = await Sandbox.create({ packages: ["bash", "coreutils", "python-3.13"], // instance: "XXXXXX", // your organization ID; overrides $CHAINCTL_SANDBOX_INSTANCE and auto-detection }); // deleted at the end of the block
const result = await sbx.commands.run(`python3 -c "print('hello from', __import__('platform').node())"`); console.log(result.stdout.trimEnd());
await sbx.files.write("notes/hello.txt", "hi"); console.log(await sbx.files.read("notes/hello.txt"));}
// connect-node keeps its HTTP/2 session open, so exit explicitly, after the block has disposed the sandbox.process.exit(0);bun quickstart.tsIn a clone of the repository the same program is examples/quickstart.ts. From the clone’s typescript
directory:
bun examples/quickstart.tsconnect-node keeps an HTTP/2 connection open, so short scripts should end with process.exit(0).
Call it outside the block that holds await using: exiting inside the block skips the disposal,
and the sandbox keeps running.
Save this as main.go in my-app:
package main
import ( "context" "fmt" "log"
"github.com/sandboxing-dev/chainguard-sandbox-sdk/go/sandbox")
func main() { // log.Fatal exits without running deferred calls, so the work is in run: // its deferred Kill has already deleted the sandbox when an error gets here. if err := run(context.Background()); err != nil { log.Fatal(err) }}
func run(ctx context.Context) error { sb, err := sandbox.Create(ctx, &sandbox.CreateOptions{ Packages: []string{"bash", "coreutils", "python-3.13"}, // Instance: "XXXXXX", // your organization ID; overrides $CHAINCTL_SANDBOX_INSTANCE and auto-detection }) if err != nil { return err } defer sb.Kill(context.Background()) // delete the sandbox when done, on success and on error
res, err := sb.Commands.Run(ctx, `python3 -c "print('hello from', __import__('platform').node())"`, nil) if err != nil { return err } fmt.Print(res.Stdout)
if _, err := sb.Files.Write(ctx, "notes/hello.txt", []byte("hi")); err != nil { return err } text, err := sb.Files.ReadText(ctx, "notes/hello.txt") if err != nil { return err } fmt.Println(text) return nil}go mod tidygo run .In a clone of the repository the same program is examples/quickstart/main.go. From the clone’s go
directory:
go run ./examples/quickstartSave this as src/main.rs in my-app (replacing the one cargo new wrote):
use chainguard_sandbox::{CreateOptions, Sandbox};
#[tokio::main]async fn main() -> chainguard_sandbox::Result<()> { let opts = CreateOptions { packages: Some(vec![ "bash".into(), "coreutils".into(), "python-3.13".into(), ]), // instance: "XXXXXX".into(), // your organization ID; overrides $CHAINCTL_SANDBOX_INSTANCE and auto-detection ..Default::default() }; // The sandbox is deleted when the closure returns, on success and on error. Sandbox::with(opts, async |sbx| { let res = sbx .commands .run(r#"python3 -c "print('hello from', __import__('platform').node())""#) .await?; print!("{}", res.stdout);
sbx.files.write("notes/hello.txt", "hi").await?; println!("{}", sbx.files.read_text("notes/hello.txt").await?); Ok(()) }) .await}cargo runIn a clone of the repository the same program is examples/quickstart.rs. From the clone’s rust
directory:
cargo run --example quickstartSandbox::with deletes the sandbox when the closure returns, also on error. A Sandbox you create with
Sandbox::create and then drop keeps running; delete it with sbx.kill().await.
What happens:
- Create (about 6–10 seconds): a Workspaces session starts with the packages you listed. The sandbox is ready when the call returns.
- Run: the command runs with bash in
/work, as root. The output streams back, and you get the exit code. A warm sandbox answers in about 0.15 s. - Files: relative paths resolve against
/work, and parent directories are created as needed. - Kill: the context manager,
await using,deferorSandbox::withdeletes the sandbox. Delete sandboxes you’re done with: Workspaces currently allows one sandbox per user, and a leftover one blocks the next create.
