Expand description
Simple Chainguard Sandbox SDK for Rust: create a sandbox on Chainguard Workspaces, run commands in it, move files in and out, and delete it. The API is shaped like the E2B, Vercel Sandbox and Modal SDKs, and matches the Go, Python and TypeScript SDKs.
Unofficial. This SDK isn’t affiliated with or supported by Chainguard. It’s compatible with
chainctl 0.2.398 and the Sessions API it uses.
use chainguard_sandbox::{CreateOptions, Sandbox};
#[tokio::main]
async fn main() -> chainguard_sandbox::Result<()> {
let out = Sandbox::with(CreateOptions { packages: Some(vec!["bash".into(), "python-3.13".into()]), ..Default::default() }, async |sbx| {
let r = sbx.commands.run("python3 -c 'print(2+2)'").await?;
sbx.files.write("notes/hello.txt", "hi").await?;
Ok(r.stdout)
})
.await?; // the sandbox is deleted here
print!("{out}"); // 4
Ok(())
}Programs without an async runtime use blocking.
The first call opens your browser to log in to Chainguard; the login is saved and shared with
the Go, Python and TypeScript SDKs. Workspaces must be turned on for your organization once
(enable_workspaces, or chainguard-sandbox enable).
The layers:
Sandbox,Commands,Files: the simple sandbox API.workspaces: the lower-level client (sessions, exec, login, tokens, the platform API).
Re-exports§
pub use workspaces::TermsDocument;
Modules§
- blocking
- The same API for programs without an async runtime.
- workspaces
- The lower-level client under the sandbox API: the parts of the Chainguard Workspaces Sessions
API (
chainguard.sandbox.runtime.session.v1.Sessions, the servicechainctl developuses) that the sandbox API needs, plus login and token handling. It is compatible with chainctl 0.2.398.
Structs§
- Command
Handle - A background command.
- Command
Result - A finished command’s output and exit code.
- Commands
- Runs commands in a sandbox.
- Connect
Options - Configures
Sandbox::connect,listandkill. - Create
Options - Configures
Sandbox::create. The default is a sandbox withDEFAULT_PACKAGESand open egress. - Entry
Info - Describes a file, directory or symlink.
- Files
- Reads and writes a sandbox’s filesystem. Relative paths resolve against /work. Every call is a
small shell program run in the sandbox, so each costs one round trip (about 0.15 s once the
sandbox is warm); batch with
write_filesandupload_dirwhere you can. - GitSource
- Starts the sandbox from a GitHub repository instead of an empty tree: the plane clones it into /work (no upload).
- Info
- Describes a sandbox.
- Organization
- A Chainguard organization a sandbox can live in. A Chainguard organization (a root IAM group).
- Process
Info - Describes a background command.
- RunOptions
- Configures
Commands::run_withandCommands::run_args_with. - Sandbox
- A handle to one sandbox. Cloning is cheap; clones refer to the same sandbox. The sandbox runs one command at a time: concurrent calls queue in the plane.
- Setup
Options - Selects the organization for
workspaces_statusandenable_workspaces. - Start
Options - Configures a background command (
Commands::start_with). - Wait
Options - Configures
CommandHandle::wait_with. - Workspaces
Status - An organization’s Workspaces setup.
- Write
Entry - One file for
Files::write_files. - Write
Info - Describes a written file.
Enums§
- Error
- Everything that can go wrong. The variants mirror the typed errors of the Go, Python and
TypeScript SDKs (
CommandExitError,NotFoundError,ErrBusy, …). - File
Type - “file”, “dir” or “symlink”.
Constants§
- DEFAULT_
COMMAND_ TIMEOUT - Bounds a foreground command when
RunOptions::timeoutisNone. - DEFAULT_
PACKAGES - The toolchain a sandbox gets when
CreateOptions::packagesisNone: a shell, the core tools, git, curl, jq, Python and Node.js. Package names are Chainguard (Wolfi) package names, e.g. “python-3.12”, “go”, “nodejs-22”, “bun”, “rust”. - DEFAULT_
WORKDIR - Where commands run and relative paths resolve.
Functions§
- document
- The environment document
Sandbox::createwould send foro. - enable_
workspaces - Turns Workspaces on for the organization, so sandboxes can be created in it. It is what
chainctl develop init --parent ORGdoes for an existing organization, without chainctl. It needs the owner role, and does nothing if everything is already in place. The steps: - kill
- Deletes the sandbox with the given ID (short ID, display name or resource name). Returns false
if there was none. Unlike
Sandbox::connectit does not attach to the sandbox first, so it also deletes one that never started or cannot be attached to. Errors as forSandbox::kill. - list
- Returns the sandboxes this API created (sessions with a sandbox label) in the instance.
- list_
organizations - The organizations you belong to (their IDs are what
CreateOptions::instanceand$CHAINCTL_SANDBOX_INSTANCEtake). With exactly one,Sandbox::createuses it automatically when no organization is set. It uses the saved login’s account-API token. - workspaces_
status - Whether Workspaces is turned on for the organization and which required terms it still has to accept. It changes nothing.
Type Aliases§
- Result
Resultwith this crate’sError.- Text
Callback - Receives a command’s output as text, as it arrives.