Skip to content

Get Started

Quickstart

  • 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:
    • Go 1.23+;
    • Python 3.12+ with uv;
    • Bun 1.3+ or Node.js 20.10+ for TypeScript (the commands below use Bun);
    • Rust 1.85+ with Cargo.

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-app
uv init
uv 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-sdk
cd chainguard-sandbox-sdk/python

The Python commands below work unchanged from chainguard-sandbox-sdk/python.

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/ directory
  • 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 login command.
  • Skipping this step: the first sandbox call opens the browser itself.

Authentication explains what the login covers.

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/ directory
organization: XXXXXX
plan: Starter
workspaces: off
github: no account linked yet
terms: 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-dpa

If 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/ directory

enable does three things, in order:

  1. Terms. It lists the legal documents the organization has not accepted yet and asks you to type yes to accept them on the organization’s behalf. --accept-terms answers in advance.
  2. 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, enable opens the install page, waits for you, and authorizes again.
  3. 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.

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/ directory
ID NAME
XXXXXX my-org

In 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.py

In a clone of the repository the same program is examples/quickstart.py. From the clone’s python directory:

uv run python examples/quickstart.py

What happens:

  1. Create (about 6–10 seconds): a Workspaces session starts with the packages you listed. The sandbox is ready when the call returns.
  2. 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.
  3. Files: relative paths resolve against /work, and parent directories are created as needed.
  4. Kill: the context manager, await using, defer or Sandbox::with deletes the sandbox. Delete sandboxes you’re done with: Workspaces currently allows one sandbox per user, and a leftover one blocks the next create.
  • Sandboxes: every create option, and the sandbox lifecycle.
  • Commands: options, errors, background commands.
  • Files: the filesystem API and bulk transfers.