Skip to content

API Reference

API Reference

The same API in four languages. Each follows its language’s conventions:

  • Python: snake_case, keyword arguments, durations in seconds.
  • TypeScript: camelCase, an options object, durations in milliseconds.
  • Go: a context.Context first, *Options structs (nil means defaults), time.Duration, and typed errors.
  • Rust: async methods on Tokio (and the same API in blocking), options structs with ..Default::default(), std::time::Duration, and one Error enum.

Full generated references: Python, TypeScript, Go, Rust (rustdoc).

Python TypeScript Go Rust
Create Sandbox.create(*, packages, envs, name, egress, egress_policy, document, source, source_revision, start_timeout, client, instance) Sandbox.create({packages, envs, name, egress, egressPolicy, document, source, startTimeoutMs, client, instance}) sandbox.Create(ctx, *CreateOptions) Sandbox::create(CreateOptions)
Reconnect Sandbox.connect(id, *, envs, client, instance) Sandbox.connect(id, {envs, client, instance}) sandbox.Connect(ctx, id, *ConnectOptions) Sandbox::connect(id, ConnectOptions)
List Sandbox.list() → list[SandboxInfo] Sandbox.list() → SandboxInfo[] sandbox.List(ctx, *ConnectOptions) → []Info chainguard_sandbox::list(ConnectOptions) → Vec<Info>
Delete by ID Sandbox.kill(id) → bool Sandbox.kill(id) → bool sandbox.Kill(ctx, id, *ConnectOptions) → bool chainguard_sandbox::kill(id, ConnectOptions) → bool
Delete sbx.kill() → bool sbx.kill() → bool sb.Kill(ctx) → bool sbx.kill() → bool
Pause sbx.pause() sbx.pause() sb.Pause(ctx) sbx.pause()
Keep awake sbx.keep_alive(seconds) sbx.keepAlive(ms) sb.KeepAlive(ctx, d) sbx.keep_alive(Duration)
State sbx.get_info(), sbx.is_running() sbx.getInfo(), sbx.isRunning() sb.GetInfo(ctx), sb.IsRunning(ctx) sbx.get_info(), sbx.is_running()
ID sbx.sandbox_id, sbx.name sbx.sandboxId, sbx.name sb.ID, sb.Name sbx.id, sbx.name
Organizations list_organizations() → list[Organization] (id, name) listOrganizations() → Organization[] sandbox.ListOrganizations(ctx) → []Organization list_organizations() → Vec<Organization>
Organization instance= on create/connect/list instance Instance (else $CHAINCTL_SANDBOX_INSTANCE, else auto-detected) instance
Underlying client sbx.client sbx.client sb.Client() sbx.client()
Scope with Sandbox.create() as sbx await using sbx = … defer sb.Kill(ctx) Sandbox::with(opts, async |sbx| …)
Defaults DEFAULT_PACKAGES, DEFAULT_WORKDIR, DEFAULT_COMMAND_TIMEOUT, environment_document() DEFAULT_PACKAGES, DEFAULT_WORKDIR, DEFAULT_COMMAND_TIMEOUT_MS, environmentDocument() DefaultPackages, DefaultWorkdir, DefaultCommandTimeout, Document() DEFAULT_PACKAGES, DEFAULT_WORKDIR, DEFAULT_COMMAND_TIMEOUT, document()
Python TypeScript Go Rust
Run (shell string) run("…", *, cwd, envs, timeout, stdin, on_stdout, on_stderr) → CommandResult run("…", {cwd, envs, timeoutMs, stdin, onStdout, onStderr}) → CommandResult Run(ctx, "…", *RunOptions) → *CommandResult run("…"), run_with("…", RunOptions) → CommandResult
Run (argv) run([…], …) run([…], …) RunArgs(ctx, []string, *RunOptions) run_args([…]), run_args_with
Background run(…, background=True) → CommandHandle run(…, {background: true}) → CommandHandle Start(ctx, "…", *StartOptions), StartArgs → *CommandHandle start("…"), start_with, start_args_with → CommandHandle
List list() → list[ProcessInfo] list() → ProcessInfo[] List(ctx) → []ProcessInfo list() → Vec<ProcessInfo>
Reattach connect(pid) connect(pid) Connect(ctx, pid) connect(pid)
Kill kill(pid) → bool kill(pid) → bool Kill(ctx, pid) → bool kill(pid) → bool

CommandResult: exit_code / exitCode / ExitCode, stdout, stderr.

CommandHandle:

  • Python: pid, id, wait(on_stdout, on_stderr), poll(), kill(), stdout, stderr, exit_code, and iteration.
  • TypeScript: pid, id, wait({onStdout, onStderr}), poll(), kill(), stdout, stderr, exitCode.
  • Go: PID, ID, Wait(ctx, *WaitOptions), Poll(ctx), Kill(ctx), Stdout(), Stderr(), ExitCode().
  • Rust: pid, id, wait(), wait_with(WaitOptions), poll(), kill(), stdout(), stderr(), exit_code().
Python TypeScript Go Rust
Read read(path, format="text") or format="bytes" read(path, {format}) Read(ctx, path), ReadText read(path) → Vec<u8>, read_text
Write write(path, data) → WriteInfo write(path, data) → WriteInfo Write(ctx, path, data) → *WriteInfo write(path, data) → WriteInfo
Write many write_files([{path, data, mode}]) write([{path, data, mode}]), writeFiles WriteFiles(ctx, []WriteEntry) write_files(Vec<WriteEntry>)
List list(path) → list[EntryInfo] list(path) → EntryInfo[] List(ctx, path) → []EntryInfo list(path) → Vec<EntryInfo>
Exists exists(path) exists(path) Exists(ctx, path) exists(path)
Describe get_info(path) getInfo(path) GetInfo(ctx, path) get_info(path)
mkdir -p make_dir(path) → bool makeDir(path) → bool MakeDir(ctx, path) → bool make_dir(path) → bool
Remove remove(path) remove(path) Remove(ctx, path) remove(path)
Rename rename(old, new) → EntryInfo rename(old, new) → EntryInfo Rename(ctx, old, new) → *EntryInfo rename(old, new) → EntryInfo
Local file in/out upload(local, remote), download(remote, local) upload, download Upload, Download upload, download
Local dir in/out upload_dir(local, remote), download_dir(remote, local) uploadDir, downloadDir UploadDir, DownloadDir upload_dir, download_dir

See Errors for the table of types per language.