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.Contextfirst,*Optionsstructs (nil means defaults),time.Duration, and typed errors. - Rust:
asyncmethods on Tokio (and the same API inblocking), options structs with..Default::default(),std::time::Duration, and oneErrorenum.
Full generated references: Python, TypeScript, Go, Rust (rustdoc).
Sandbox
Section titled “Sandbox”| 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() |
Commands (sbx.commands, Go sb.Commands)
Section titled “Commands (sbx.commands, Go sb.Commands)”| 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().
Files (sbx.files, Go sb.Files)
Section titled “Files (sbx.files, Go sb.Files)”| 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 |
Errors
Section titled “Errors”See Errors for the table of types per language.
