Documentation

pip install ./sdk/python          # from a box checkout

from sdbox import Client, Sandbox

npm install ./sdk/typescript      // from a box checkout

import { Client, Sandbox } from "box-sdk";

go get github.com/chxperiments/box/sdk/go

import "github.com/chxperiments/box/sdk/go"

cargo add --git https://github.com/chxperiments/box sdbox

use sdbox::{Client, Command, Sandbox};

sb = Sandbox("agent")
sb.up()
...
sb.down()

# or
with Sandbox("agent") as sb:
    ...

const sb = new Sandbox("agent");
await sb.up();
...
await sb.down();

// or
await sb.withUp(async (sb) => {
  ...
});

sb := box.New().Sandbox("agent")
if err := sb.Up(ctx); err != nil {
	return err
}
defer sb.Down(ctx)

let sb = Sandbox::new("agent")?;
sb.up()?;
...
sb.down()?;

r = sb.exec(["python3", "-c", "print(6*7)"])
r = sb.exec("ls -la | head", timeout=10)
r = sb.exec("wc -c", stdin=b"bytes")

r = Sandbox("agent").run("pytest -q")

let r = await sb.exec(["python3", "-c", "print(6*7)"]);
r = await sb.exec("ls -la | head", { timeout: 10 });
r = await sb.exec("wc -c", { stdin: Buffer.from("bytes") });

r = await new Sandbox("agent").run("pytest -q");

r, err := sb.Exec(ctx, box.Cmd("python3", "-c", "print(6*7)"))
r, err = sb.Exec(ctx, box.Command{
	Argv: []string{"sh", "-c", "ls -la | head"}, Timeout: 10 * time.Second})

r, err = sb.Run(ctx, box.Sh("pytest -q"))

let r = sb.exec(Command::new(["python3", "-c", "print(6*7)"]))?;
let r = sb.exec(Command::sh("ls -la | head").timeout(10))?;
let r = sb.exec(Command::new(["wc", "-c"]).stdin(b"bytes".to_vec()))?;

let r = Sandbox::new("agent")?.run("pytest -q")?;

sb.write_file("/data/task.py", "print(1)")
data = sb.read_file("/data/result.json")

await sb.writeFile("/data/task.py", "print(1)");
const data = await sb.readFile("/data/result.json");

err := sb.WriteFile(ctx, "/data/task.py", []byte("print(1)"))
data, err := sb.ReadFile(ctx, "/data/result.json")

sb.write_file("/data/task.py", "print(1)")?;
let data = sb.read_file("/data/result.json")?;

trial = Sandbox("agent").fork("trial")
trial.run("python3 refactor.py").check()

for ch in trial.diff():
    print(ch.kind, ch.path)

if tests_pass:
    trial.apply()       # returns how many changes were merged
else:
    trial.discard()

const trial = await new Sandbox("agent").fork("trial");
(await trial.run("python3 refactor.py")).check();

for (const ch of await trial.diff()) console.log(ch.kind, ch.path);

if (testsPass) await trial.apply();
else await trial.discard();

trial, err := box.New().Sandbox("agent").Fork(ctx, "trial")
trial.Run(ctx, box.Sh("python3 refactor.py"))

changes, _ := trial.Diff(ctx)
for _, ch := range changes {
	fmt.Println(ch.Kind, ch.Path)
}
if testsPass {
	trial.Apply(ctx)
} else {
	trial.Discard(ctx)
}

let trial = Sandbox::new("agent")?.fork("trial")?;
trial.run("python3 refactor.py")?.check()?;

for ch in trial.diff()? {
    println!("{} {}", ch.kind, ch.path);
}
if tests_pass { trial.apply()?; } else { trial.discard()?; }

r = sb.exec("make test")
r.exit_code, r.stdout, r.stderr, r.duration_ms, r.timed_out
r.ok; r.stdout_text
r.check()               # raises CommandFailed on a non-zero exit

from sdbox import NotFound, NotUp, BoxError

const r = await sb.exec("make test");
r.exitCode; r.stdout; r.stderr; r.durationMs; r.timedOut;
r.ok; r.stdoutText;
r.check();              // throws CommandFailed on a non-zero exit

import { NotFound, NotUp, BoxError } from "box-sdk";

r, err := sb.Exec(ctx, box.Sh("make test"))
r.ExitCode; r.Stdout; r.Stderr; r.Duration; r.TimedOut
r.OK()

box.IsNotFound(err); box.IsNotUp(err)

let r = sb.exec("make test")?;
r.exit_code; r.stdout; r.stderr; r.duration_ms; r.timed_out;
r.ok(); r.stdout_text();
let r = r.check()?;      // Error::CommandFailed on a non-zero exit

match err { Error::NotFound(_) | Error::NotUp(_) => {}, _ => {} }