Expand description
The lower-level client under the sandbox API: the parts of the Chainguard Workspaces Sessions
API (chainguard.sandbox.runtime.session.v1.Sessions, the service chainctl develop uses) that
the sandbox API needs, plus login and token handling. It is compatible with chainctl 0.2.398.
It is unofficial: not published or supported by Chainguard. Most programs should use the
Sandbox API instead.
use chainguard_sandbox::workspaces::{Client, ExecOptions, ListOptions, Options};
let c = Client::new(Options { instance: "XXXXXX".into(), ..Default::default() }).await?;
let sessions = c.list(&ListOptions::default()).await?;
let argv = ["go", "test", "./..."].map(String::from);
let res = c.exec(&sessions[0].name, &argv, ExecOptions::default()).await?;
println!("exit {}", res.exit_code);Modules§
- pb
- The generated protobuf messages and gRPC client and server for the SDK’s subset of the Sessions API.
Structs§
- Browser
Login Token - A
TokenSourcebacked by the library’s own login: it mints tokens from the saved refresh token, and when there is none (or it has expired) runsbrowser_login, unlessno_browseris set. Wrap it incached. Concurrent processes share the saved login safely. - Chainctl
Token - Mints tokens by running
chainctl auth token --audience <audience>. It needs a priorchainctl auth login. - Claims
- A token’s unverified identity claims (for display).
- Client
- A connection to the Sessions service. Cloning is cheap and shares the connection.
- Entitlement
- An organization’s Workspaces entitlement.
- Exec
Options - Configures
Client::exec. - Exec
Result - A finished command’s status.
- File
Login Store - Stores logins in a JSON file (0600, in a 0700 directory). The Go, Python, TypeScript and Rust
libraries share
default_login_file, so one login serves all four. - GitHub
Authorization - The result of
authorize_github. It holds no GitHub token: the service exchanges the code itself when the account is linked. - GitHub
Authorize Options - Configures
authorize_github. - GitHubO
Auth Start - What the service hands out to start a GitHub authorization: the Chainguard GitHub App’s OAuth client ID, and a state value the service signed and checks again when the account is linked.
- Identity
Exchange - A
TokenSourcethat trades a token from an external OIDC issuer (GitHub Actions, GitLab, a Kubernetes service account, …) for a Chainguard token, acting as a Chainguard assumable identity that trusts that issuer and subject. - Linked
GitHub - A GitHub account linked to a Chainguard organization.
- List
Options - Filters
Client::list. - Login
Lock - Releases a
LoginStorelock when dropped. - Login
Options - Configures
browser_login. - Login
Result - What the issuer hands back.
- Options
- Configures a
Client. - Organization
- A Chainguard organization (a root IAM group).
- Platform
Error - A non-2xx answer from the platform API.
- Static
Token - Always returns the same token.
- Terms
Document - A legal document an organization accepts.
Constants§
- DEFAULT_
AUDIENCE - The Chainguard token audience the plane accepts.
- DEFAULT_
ENVIRONMENT - The environment document chainctl 0.2.398 uses for a directory without .chainguard/develop.yaml or ci.yaml. Its check is named “develop”.
- DEFAULT_
GITHUB_ OAUTH_ PORT - The loopback port the GitHub authorization redirects to (the one chainctl uses).
- DEFAULT_
ISSUER - Chainguard’s security token service (STS).
- DEFAULT_
PLATFORM_ URL - Chainguard’s account (IAM) API.
- DEFAULT_
URL - The sandbox plane chainctl dials (overridable with
$CHAINCTL_SESSIONS_URL). - DEFAULT_
USER_ AGENT - The user agent sent with every call unless
Options::user_agentsays otherwise. - DEFAULT_
WORK_ DIR - Where the repository lives inside the guest.
- ENABLE_
TERMS - The documents an organization accepts when Workspaces is turned on the way
chainctl develop initdoes it: the Workspaces terms, the Code Analysis Terms (the same switch turns on Chainguard Checks), and the Terms of Service and Data Privacy Agreement that linking a GitHub account requires. - ENV_
AUTH_ TOKEN - A static sessions token (chainctl’s override).
- ENV_
INSTANCE - The organization ID (chainctl’s override).
- ENV_
NO_ DETECT_ INSTANCE - Turns off organization auto-detection when set to “1”.
- ENV_
SESSIONS_ URL - The plane’s URL (chainctl’s override).
- FIRST_
ATTACH_ TIMEOUT - Bounds
Client::complete_first_attach. - GITHUB_
APP_ INSTALL_ URL - Where the Chainguard GitHub App is installed on a GitHub organization or user.
- MAX_
EXEC_ STDIN - The stdin size limit chainctl documents for exec.
- PLATFORM_
AUDIENCE - The audience of tokens for the account API (used to list your organizations).
- WORKSPACES_
TERMS - The documents an organization must accept to use Workspaces: the Secured Platform Terms and the Master Service and License Agreement.
Traits§
- Login
Store - Keeps refresh tokens between runs, per issuer.
- Token
Source - Returns a Chainguard bearer token whose audience includes
DEFAULT_AUDIENCE(or, for the platform API,PLATFORM_AUDIENCE).
Functions§
- accept_
terms - Records that the organization accepts the documents with these IDs. This is a legal act on the organization’s behalf: call it only when the person running your program has agreed to the documents. It needs the owner role; accepting a document again changes nothing.
- accepted_
terms - The IDs of the legal documents the organization has accepted.
tsmust mint platform tokens (None:platform_token_source). - authorize_
github - Sends the person to GitHub to authorize the Chainguard GitHub App and waits for GitHub’s
redirect to a loopback port. It is the flow chainctl uses: PKCE with S256, the account picker
forced, and the state checked on return. Bound it with
tokio::time::timeout. - begin_
github_ oauth - Starts a GitHub authorization.
- browser_
login - Runs the interactive login: opens the issuer’s login page in a browser and waits for the
redirect back to a localhost callback. Bound it with
tokio::time::timeout. - cached
- Reuses a token until a minute before the
expclaim of the JWT. Tokens whose expiry can’t be read are cached for five minutes. Concurrent callers share one fetch, which runs on its own task, so one caller giving up (dropping its future) doesn’t fail the others. The client drops the cached token when the plane answersUnauthenticated(seeTokenSource::invalidate). - default_
login_ audiences - What a browser login asks for: the sessions service and the account API.
$CHAINGUARD_SANDBOX_LOGIN_AUDIENCES(comma-separated) overrides it. - default_
login_ file <user config dir>/chainguard-sandbox/login.json: on macOS~/Library/Application Support/chainguard-sandbox/login.json, on Linux$XDG_CONFIG_HOME(or~/.config)/chainguard-sandbox/login.json, on Windows%AppData%. Overridden by$CHAINGUARD_SANDBOX_LOGIN_FILE.- default_
token_ source $CHAINCTL_AUTH_TOKENwhen set, otherwise the library’s own login (a cachedBrowserLoginToken): tokens are minted from the saved login, and a browser login runs when there is none. chainctl isn’t used; set$CHAINGUARD_SANDBOX_AUTH=chainctlto mint tokens with it instead.$CHAINGUARD_SANDBOX_SOCIAL_LOGINpreselects the login’s social provider (github, google-oauth2, gitlab), and$CHAINGUARD_SANDBOX_NO_BROWSER=1makes a missing login an error (Error::LoginRequired) instead of opening a browser.- detect_
instance - The ID of the only organization the identity belongs to (
Error::NoOrganizationorError::AmbiguousOrganizationotherwise). - enable_
sandbox - Turns on Checks and Workspaces for the organization, with its plan’s monthly allowance. An
allowance Chainguard already granted is kept. It needs the owner role, and the organization
must have accepted the terms first: otherwise the error’s
PlatformError::missing_termslists the documents. - env_
id_ token - Reads the OIDC token from an environment variable (e.g. a GitLab CI
id_tokens:variable). - file_
id_ token - Reads the OIDC token from a file on every call (e.g. a Kubernetes projected service-account token, which is rotated in place).
- github_
actions_ id_ token - Fetches a GitHub Actions OIDC token whose audience is the Chainguard issuer (
""=DEFAULT_ISSUER). The workflow needspermissions: id-token: write. - guest_
path - Resolves p against /work, cleaning it like Go’s
path.Clean. - instance_
name - “instances/{id}”; an already-qualified name is returned unchanged.
- is_
guest_ held - Whether
eis the plane refusing a call because another controller holds the guest (an attached shell that is still heartbeating), including the FailedPrecondition “… held by another controller … Channel already in use” it returns for a few seconds after another client’s attach or exec ends. - is_
session_ name - Whether s is a full resource name “instances/{instance}/sessions/{session}”.
- link_
github_ organization - Links a GitHub account to the Chainguard organization, using an authorization from
authorize_github.github_loginis the account to link, an organization or a user; empty means the GitHub user who authorized. The Chainguard GitHub App must be installed on the account (otherwisePlatformError::github_app_not_installed), and you must own it. An account can be linked to one Chainguard organization at a time. - linked_
github_ organizations - The GitHub accounts linked to the organization.
- list_
organizations - Returns the organizations visible to the token source’s identity, sorted by name.
tsmust mint tokens forPLATFORM_AUDIENCE;Noneusesplatform_token_source. It calls the IAM Groups API:GET /iam/v1/groups?uidp.in_root=true. - logout
- Forgets the saved login for
issuer(“” =DEFAULT_ISSUER).Noneuses the default file. - missing_
workspaces_ terms - The documents Workspaces needs that the organization has not accepted yet.
- normalize_
github_ url - Turns any GitHub remote form —
git@github.com:o/r.git,ssh://git@github.com[:22]/o/r,git://github.com/o/r,https://token@GitHub.com/o/r.git,github.com/o/r— intohttps://github.com/o/r. Credentials are never kept. Other URLs with a scheme lose their credentials and trailing “.git”; scp-style remotes on other hosts are returned unchanged. - open_
browser - Opens
uin the default browser (open on macOS, xdg-open on Linux and BSDs, the URL handler on Windows). No shell is involved. Returns whether it worked. - platform_
token_ source - Mints tokens for the account API (
PLATFORM_AUDIENCE) the same waydefault_token_sourcedoes for sessions: from the saved browser login, or with chainctl when$CHAINGUARD_SANDBOX_AUTH=chainctl. - refresh_
login - Trades a refresh token for a token for
aud(DEFAULT_AUDIENCEif empty). With rotation the issuer returns a new refresh token, which replaces the old one (empty if it didn’t rotate). Returns(token, new_refresh_token). A refused refresh token isError::LoginExpired. - repository_
session - Describes a session opened from a repository URL, like
chainctl develop github.com/org/repo: the repository ashttps://github.com/owner/repo, idle AUTO_HOLD, andDEFAULT_ENVIRONMENTas the fallback for repositories without .chainguard/ files.revisionpins a commit (empty = unpinned). - repository_
url - Normalizes “github.com/o/r”, “git@github.com:o/r.git”, “ssh://git@github.com:22/o/r” and
similar to
https://github.com/o/r. Other URLs keep their scheme (credentials stripped); scp-style remotes on other hosts are returned unchanged; a bare “host/path” gets https://. - tar_dir
- Writes
diras an uncompressed tar stream, with the rules chainctl documents for its workspace upload: symlinks travel as links; sockets, devices and FIFOs are skipped; entries are owned by root. A symlinkeddiris resolved first. A file that changes size while it is being written is truncated or zero-padded to the size in its header, rather than aborting the tar. - tar_
gz_ dir tar_dir, gzip’d, in memory (the sandbox API’supload_dirsends it).- terms_
document_ info - The label and URL of a known document ID, or a document with only the ID set.
- token_
claims - Decodes a JWT’s claims without verifying it.
- token_
fn - Adapts an async function to a
TokenSource. - workspace_
session - Describes a session whose /work tree is uploaded on the first attach (see
Client::complete_first_attach):labelidentifies the workspace (the sandbox API uses/chainguard-sandbox/<name>);repositoryandrevisionare optional metadata;documentis the environment document (YAML),NoneusingDEFAULT_ENVIRONMENTwith provenance SYNTHESIZED. The idle policy is AUTO_HOLD, chainctl’s default. - workspaces_
entitlement - Whether Workspaces is turned on for the organization, its plan, and its session limits.
Type Aliases§
- BoxFuture
- A boxed, sendable future, as returned by
TokenSource::token. - IdToken
Fn - Returns the external OIDC token presented to the STS.
- Message
Sink - Receives progress messages (“open this URL …”). The default writes to stderr.
- Output
Sink - Receives a stream’s output as it arrives.
- Session
- The plane’s session resource.
- Shared
Token Source - A shared token source.
- SkipFn
- Decides whether to leave out a path (relative, slash-separated) and, for a directory, everything under it. The second argument is whether it is a directory.
- UrlOpener
- Opens a URL in a browser; returns false if it couldn’t (the URL is then printed instead).