Guides
Authentication and Organizations
Every call needs two things:
- A Chainguard token for the sessions service.
- An organization ID (the “instance”) that says where sandboxes live.
Simple Chainguard Sandbox SDK uses the Workspaces libraries’ login and organization handling, so there’s nothing sandbox-specific to set up.
Logging In
Section titled “Logging In”By default the libraries log in through your browser, the same way chainctl does. chainctl itself
isn’t needed:
- First call: with no saved login, the library opens the Chainguard login page (GitHub, Google, GitLab, or your organization’s identity provider) and waits for the redirect back to a local port.
- Saving: the refresh token is saved to
login.json(mode 0600) in your user config directory. All four libraries share it. - Later calls: the library mints one-hour tokens from the saved login without a browser.
How long a login lasts:
- The refresh token is valid for 20 hours and is replaced on every use, so a login lasts as long as it’s used at least once every 20 hours.
- When it expires, the next call opens the browser again. Approve it and the call continues. To renew
ahead of time, run the
logincommand again.
Log in ahead of time with any library’s CLI. Add github, google-oauth2 or gitlab to skip the
provider choice:
uv run chainguard-sandbox loginuv run chainguard-sandbox whoami # who you're logged in as, and the token's expiry# run these in a project with the package added, or in a clone of the repository from its python/ directorybun run chainguard-sandbox loginbun run chainguard-sandbox whoami# or, in a clone of the repository, from its typescript/ directory:bun bin/chainguard-sandbox.ts loginbun bin/chainguard-sandbox.ts whoamigo run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest logingo run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest whoami# or, in a clone of the repository, from its go/ directory:go run ./cmd/chainguard-sandbox logingo run ./cmd/chainguard-sandbox whoamichainguard-sandbox loginchainguard-sandbox whoami# installed with cargo install (see the Quickstart); or, in a clone of the repository, from its rust/ directory:cargo run --bin chainguard-sandbox -- logincargo run --bin chainguard-sandbox -- whoamiChoosing the Organization
Section titled “Choosing the Organization”There are three ways; the first one set wins.
- In code:
instance=(Python),instance(TypeScript),Instance(Go),instance(Rust), onSandbox.create,Sandbox.connect,Sandbox.list, or the libraryClient. - Environment variable:
export CHAINCTL_SANDBOX_INSTANCE=XXXXXX. - Auto-detection: used when neither is set:
- the library lists the organizations your identity belongs to;
- with exactly one, it uses it;
- with several, it fails with a message listing their IDs and names;
- with none, it fails with “your identity belongs to no Chainguard organization”.
Turn auto-detection off with CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE=1, or in code: detect_instance=False on the
Python Client, detectInstance: false on the TypeScript Client, NoDetectInstance: true in Go
Options, no_detect_instance: true in Rust workspaces::Options. When no organization can be found, the error lists all three ways and how to look up the IDs.
When detection runs:
- Go, Python and Rust: when the client is created, so in
Sandbox.create/connect/list. - TypeScript: on the first call that needs the organization, then remembered.
- Cost: one extra request, about 0.3 s. Setting the organization explicitly skips it.
Listing organization IDs:
| Command | In code | |
|---|---|---|
| Python | uv run chainguard-sandbox orgs |
from chainguard_sandbox import list_organizations |
| TypeScript | bun run chainguard-sandbox orgs |
import { listOrganizations } from "chainguard-sandbox-sdk" |
| Go | go run github.com/sandboxing-dev/chainguard-sandbox-sdk/go/cmd/chainguard-sandbox@latest orgs |
sandbox.ListOrganizations(ctx) |
| Rust | chainguard-sandbox orgs (after cargo install) |
chainguard_sandbox::list_organizations() |
| chainctl | chainctl iam organizations list |
— |
In a clone of the repository the CLI runs from each language’s directory: uv run chainguard-sandbox orgs
from python/, bun bin/chainguard-sandbox.ts orgs from typescript/ (after bun install),
go run ./cmd/chainguard-sandbox orgs from go/, and cargo run --bin chainguard-sandbox -- orgs from rust/.
How Detection Works, and What the Login Covers
Section titled “How Detection Works, and What the Login Covers”Organizations aren’t part of the sessions service. They live in Chainguard’s account API (IAM), a
different service at https://console-api.enforce.dev. That has two consequences:
- A different API call. The libraries list organizations with
GET https://console-api.enforce.dev/iam/v1/groups?uidp.in_root=true. Organizations are the root groups your identity can see. This is the same APIchainctl iam organizations listuses. - A different token.
- Audiences: every Chainguard token names the services it’s for (its audience). A sessions token
(
https://sessions.chainbox.dev) is refused by the account API, and the reverse. - What the login asks for: the browser login lists the audiences it wants, and the saved refresh
token can then mint tokens for any of them. The libraries’ login asks for two:
https://sessions.chainbox.devandhttps://console-api.enforce.dev. (chainctlasks for all of Chainguard’s services.) - Two tokens: sandbox calls use a sessions token, and auto-detection uses an account-API token. Both are minted from the same saved login.
- Audiences: every Chainguard token names the services it’s for (its audience). A sessions token
(
What the account-API audience allows.
- The token’s power: an account-API token acts as you, with your Chainguard roles. Like a chainctl login, it could do anything your roles allow in the account API, not just list organizations.
- What the libraries do with it: they only read the list of organizations.
- Keeping it out of the login: set
CHAINGUARD_SANDBOX_LOGIN_AUDIENCES=https://sessions.chainbox.devbefore logging in. Auto-detection then can’t work, so set the organization in code or withCHAINCTL_SANDBOX_INSTANCE.
Logins made before auto-detection existed cover only the sessions audience.
- Sandbox calls keep working with them.
- Auto-detection needs one new login to add the audience. With
CHAINGUARD_SANDBOX_NO_BROWSER=1it fails with “the saved login doesn’t cover https://console-api.enforce.dev; log in again”; otherwise it opens the browser. - The old login isn’t deleted just because it lacks an audience. It’s only forgotten when it has expired or is refused for an audience it covers.
Other token sources:
- chainctl: with
CHAINGUARD_SANDBOX_AUTH=chainctl, detection useschainctl auth token --audience https://console-api.enforce.dev. - A fixed token: with
CHAINCTL_AUTH_TOKENor a custom token source, detection is skipped unless you also pass an account-API token source:platform_token_source=(Python),platformTokenSource(TypeScript),PlatformTokenSource(Go),platform_token_source(Rust). Otherwise set the organization explicitly.
Enabling Workspaces
Section titled “Enabling Workspaces”Sandboxes can be created only in an organization where Workspaces is turned on. A new organization
starts with it off, and create then fails with WorkspacesNotEnabledError (Go: ErrNotEnabled, Rust: Error::NotEnabled),
carrying the service’s message “this organization is not entitled to Chainguard Workspaces”.
Turning it on takes three things, done once by an organization owner:
- Accept the terms. Workspaces is offered under the Secured Platform Terms and the Master Service and License Agreement. Turning it on also involves the Code Analysis Terms (the same switch turns on Chainguard Checks), and the Terms of Service and Data Privacy Agreement that linking GitHub requires.
- Link a GitHub account to the organization: your own user, or a GitHub organization you own. The service refuses to turn Workspaces on without one. The Chainguard GitHub App must be installed on the account, and you authorize the link in your browser.
- Turn the feature on. The organization gets its plan’s allowance (on the Starter plan: one sandbox per user and three in the organization at a time).
From the command line, chainguard-sandbox status shows where an organization stands and
chainguard-sandbox enable does all three, asking before it accepts anything (see the
Quickstart). From code:
from chainguard_sandbox import enable_workspaces, workspaces_status
st = workspaces_status() # reads; changes nothingif not st.ready: for doc in st.missing_terms: # show these to the person, and get their agreement print(doc.label, doc.url) st = enable_workspaces(accept_terms=True) # only once they have agreedimport { enableWorkspaces, workspacesStatus } from "chainguard-sandbox-sdk";
let st = await workspacesStatus(); // reads; changes nothingif (!st.ready) { for (const doc of st.missingTerms) console.log(doc.label, doc.url); // show these, and get agreement st = await enableWorkspaces({ acceptTerms: true }); // only once they have agreed}st, err := sandbox.Status(ctx, nil) // reads; changes nothingif err == nil && !st.Ready() { for _, doc := range st.MissingTerms { // show these to the person, and get their agreement fmt.Println(doc.Label, doc.URL) } st, err = sandbox.Enable(ctx, &sandbox.SetupOptions{AcceptTerms: true}) // only once they have agreed}use chainguard_sandbox::{SetupOptions, enable_workspaces, workspaces_status};
let mut st = workspaces_status(&SetupOptions::default()).await?; // reads; changes nothingif !st.ready() { for doc in &st.missing_terms { // show these to the person, and get their agreement println!("{} {}", doc.label, doc.url); } let o = SetupOptions { accept_terms: true, ..Default::default() }; // only once they have agreed st = enable_workspaces(&o).await?;}| Python | TypeScript | Go | Rust | |
|---|---|---|---|---|
| Read the setup | workspaces_status() |
workspacesStatus() |
sandbox.Status(ctx, nil) |
workspaces_status(&SetupOptions) |
| Turn it on | enable_workspaces(accept_terms=True) |
enableWorkspaces({ acceptTerms: true }) |
sandbox.Enable(ctx, &sandbox.SetupOptions{AcceptTerms: true}) |
enable_workspaces(&SetupOptions { accept_terms: true, .. }) |
| Result | WorkspacesStatus: .ready, .enabled, .missing_terms, .github_accounts, .plan, .max_sandboxes, .max_sandboxes_per_user |
the same, in camelCase | *WorkspacesStatus, with Ready() |
WorkspacesStatus, with ready() |
| Organization | instance= |
instance |
SetupOptions.Instance |
instance |
| GitHub account to link | github_account= |
githubAccount |
SetupOptions.GitHubAccount |
github_account |
| Port for GitHub’s redirect | github_port= (8989) |
githubPort |
SetupOptions.GitHubPort |
github_port |
| Never open a browser | open_browser=False |
openBrowser: false |
SetupOptions.NoBrowser |
no_browser: true |
- Accepting terms is explicit. Without
accept_terms/acceptTerms/AcceptTerms, an organization with unaccepted terms getsTermsNotAcceptedError(Go:*TermsNotAcceptedError, Rust:Error::TermsNotAccepted), which lists the documents with their URLs. Nothing is accepted or changed. Pass the flag only when the person running your program has read and agreed to them: it is a legal act on the organization’s behalf. - The GitHub step needs a person.
enableopens a browser on GitHub and waits (up to 10 minutes) for you to choose the account and authorize. Only an authorization code passes through your machine; the SDK never holds a GitHub token. If the organization already has an account linked, this step is skipped. - The app must be installed first. If the Chainguard GitHub App isn’t on the account,
enablefails withGitHubAppNotInstalledError(Go:*GitHubAppNotInstalledError, Rust:Error::GitHubAppNotInstalled), which carries the install page. Install it and callenableagain; the CLI does this loop for you. - Without a browser,
enablefails withGitHubLinkRequiredErrorinstead of waiting. - One Chainguard organization per GitHub account. Linking an account that is linked elsewhere fails.
- It is safe to repeat. If Workspaces is already on and the terms are accepted, nothing is sent.
- Checks comes with it. The same switch turns on Chainguard Checks.
- Owner role. All three steps need it, and you must own the GitHub account. Members without the role can still read the status.
- Not covered: creating the account and the organization (use the Console).
The calls behind these are listed in Protocol: Authentication and Organizations.
Environment Variables
Section titled “Environment Variables”| Variable | Effect |
|---|---|
CHAINCTL_SANDBOX_INSTANCE |
The organization ID (overrides auto-detection) |
CHAINGUARD_SANDBOX_NO_DETECT_INSTANCE=1 |
Never auto-detect the organization |
CHAINCTL_AUTH_TOKEN |
Use this sessions token as-is (audience https://sessions.chainbox.dev) |
CHAINGUARD_SANDBOX_NO_BROWSER=1 |
Never open a browser: fail with a “login required” error instead. For scripts and CI |
CHAINGUARD_SANDBOX_SOCIAL_LOGIN |
Preselect the login provider (github, google-oauth2, gitlab) |
CHAINGUARD_SANDBOX_LOGIN_AUDIENCES |
Comma-separated audiences a new login asks for. Default: sessions + account API |
CHAINGUARD_SANDBOX_AUTH=chainctl |
Mint tokens with an installed, logged-in chainctl instead |
CHAINGUARD_SANDBOX_LOGIN_FILE |
Use another login file |
Servers and CI
Section titled “Servers and CI”The libraries also support Chainguard assumable identities: a CI job trades its OIDC token (GitHub
Actions, GitLab, Kubernetes, …) for a Chainguard token. See IdentityExchange in the SDK’s READMEs.
Starter organizations can’t create identities, so on that plan, unattended use needs a saved login or a
token. In CI, set the organization explicitly; detection would need a second, account-API token.
