Skip to main content

Crate chainguard_sandbox

Crate chainguard_sandbox 

Source
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:

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 service chainctl develop uses) that the sandbox API needs, plus login and token handling. It is compatible with chainctl 0.2.398.

Structs§

CommandHandle
A background command.
CommandResult
A finished command’s output and exit code.
Commands
Runs commands in a sandbox.
ConnectOptions
Configures Sandbox::connect, list and kill.
CreateOptions
Configures Sandbox::create. The default is a sandbox with DEFAULT_PACKAGES and open egress.
EntryInfo
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_files and upload_dir where 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).
ProcessInfo
Describes a background command.
RunOptions
Configures Commands::run_with and Commands::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.
SetupOptions
Selects the organization for workspaces_status and enable_workspaces.
StartOptions
Configures a background command (Commands::start_with).
WaitOptions
Configures CommandHandle::wait_with.
WorkspacesStatus
An organization’s Workspaces setup.
WriteEntry
One file for Files::write_files.
WriteInfo
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, …).
FileType
“file”, “dir” or “symlink”.

Constants§

DEFAULT_COMMAND_TIMEOUT
Bounds a foreground command when RunOptions::timeout is None.
DEFAULT_PACKAGES
The toolchain a sandbox gets when CreateOptions::packages is None: 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::create would send for o.
enable_workspaces
Turns Workspaces on for the organization, so sandboxes can be created in it. It is what chainctl develop init --parent ORG does 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::connect it does not attach to the sandbox first, so it also deletes one that never started or cannot be attached to. Errors as for Sandbox::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::instance and $CHAINCTL_SANDBOX_INSTANCE take). With exactly one, Sandbox::create uses 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
Result with this crate’s Error.
TextCallback
Receives a command’s output as text, as it arrives.