drej — Sandboxes as objects

The primitives underneath

Everything, one SDK.

Start a live container in one call. Pick any Docker image, set resource limits, and get back a Sandbox you hold like any other object.

Run commands and get stdout, stderr, and exit code back. Stream live output to your process, set a working directory, inject environment variables.

Read and write files directly inside the sandbox. Inject source code, pull build artifacts, inspect logs — all from TypeScript with no extra tooling.

Snapshot the container at any point — filesystem, processes, memory. Resume later from the exact same state. Pay for compute only when you need it.

Branch a running container from any checkpoint. Each fork is an independent Sandbox — run parallel test shards, A/B variants, or speculative executions.

Define a named environment once — image, resources, setup script. drej builds it, snapshots it, and restores from that snapshot on every subsequent call.

Every exec is logged to a durable ledger. Query past sessions, inspect exec counts and timing, or delete records — all through a typed API.

Read the docs GitHub →

index.ts

const sb = await client.sandbox({
  image: "node:22",
  resources: {
    cpu:    "500m",
    memory: "256Mi",
  },
});

const { stdout } = await sb.exec(
  "node index.js",
);
 
// stream live output
await sb.exec("npm test")
  .pipe(process.stdout);

await sb.writeFile("/app/main.py", src);
 
const logs = await sb.readFile(
  "/var/log/app.log",
);
 
const entries = await sb.listDirectory(
  "/app", { depth: 1 },
);

await sb.checkpoint("before-tests");
 
// restore exact state later
const resumed = await client.resume(
  sandboxId,
);
await resumed.exec("npm test");

await sb.checkpoint();
const fork = await sb.fork();
 
// two independent containers, same state
await Promise.all([
  sb.exec("npm test -- --shard=1/2"),
  fork.exec("npm test -- --shard=2/2"),
]);

const env = client.environment("ci", {
  image: "node:22",
  resources: { cpu: "500m", memory: "512Mi" },
  setup: async (sb) => {
    await sb.exec("npm ci");
  },
});
 
// builds once, restores from snapshot
const sb = await env.sandbox();
await sb.exec("npm test");

const sessions = await client.sandboxes.list({
  status: SandboxStatus.Running,
  limit: 20,
});
 
const details = await client.sandboxes.get(
  "ci", sandboxId,
);
// { status, execCount, startedAt }

Chain sandbox steps into one lazy pipeline. Nothing runs until you await .pipe() or .result() — the whole thing executes as a single unit.

Get combined stdout and any files you read back as vars, in one return value — no manual bookkeeping across steps.

retry and when branch on runtime state — exit codes, captured vars — right inside the builder callback.

Fan a step out over a list with forEach, with an optional concurrency cap for parallel branches.

Read the docs GitHub →

index.ts

import { workflow } from "@drej/workflow";
 
await workflow(client)
  .sandbox(
    { image: "node:22", resources: { cpu: "500m", memory: "512Mi" } },
    (sb) => {
      sb.exec("node --version");
      sb.exec("npm --version");
    },
  )
  .pipe(process.stdout);

const { stdout, vars } = await workflow(client)
  .sandbox(
    { image: "node:22", resources: { cpu: "500m", memory: "512Mi" } },
    (sb) => {
      sb.exec("node --version > /tmp/ver.txt");
      sb.readFile("/tmp/ver.txt", "nodeVersion");
    },
  )
  .result();
 
console.log(vars.nodeVersion);

sb.retry(
  3,
  (sb) => {
    sb.exec("curl -f https://api.example.com/health");
  },
  { delayMs: 2000, backoff: "exponential" },
);
 
sb.when(
  (ctx) => ctx.exitCode === 0,
  (sb) => sb.exec("tar -xzf /tmp/cache.tar.gz"),
  (sb) => sb.exec("npm ci"),
);

const packages = ["lodash", "zod", "tsx"];
 
sb.forEach(
  packages,
  (sb, pkg) => sb.exec(`npm install ${pkg}`),
  { concurrency: 3 },
);

Spin up a Pi coding agent in a sandbox and stream its response back to your process in one call.

Redirect the agent mid-response — it adjusts course immediately, without waiting for the current turn to finish.

Watch Pi's tool calls as they happen — not just the final text — for full visibility into what the agent is doing.

Branch from any earlier message in the conversation, or wipe the slate clean — the sandbox filesystem stays untouched either way.

First run installs and checkpoints the CLI. Every run after restores from that snapshot in seconds.

Read the docs GitHub →

index.ts

import { Agent, textOnly } from "@drej/agent";
 
const agent = await Agent.load(
  "./agents/hello-agent.json",
);
 
for await (const chunk of textOnly(
  agent.prompt("Summarize this repo."),
)) {
  process.stdout.write(chunk);
}

const stream = textOnly(
  agent.prompt("Write a very long essay..."),
);
 
setTimeout(() => {
  agent.steer("Stop — give me 3 bullets instead.");
}, 1500);
 
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

for await (const ev of agent.prompt(
  "Run /workspace/script.py",
)) {
  if (ev.type === "text")
    process.stdout.write(ev.text);
  if (ev.type === "tool_start")
    console.log(`[tool] ${ev.toolName}`);
}

const points = await agent.getForkMessages();
const forked = await agent.fork(points[0].entryId);
console.log(forked.text.slice(0, 40));
 
// or wipe the slate clean
await agent.newSession();

const agent = await Agent.load(
  "./agents/hello-agent.json",
);
console.log(agent.fromSnapshot); // true
 
// force a full reinstall
await Agent.load("./agents/hello-agent.json", {
  rebuild: true,
});

One command starts OpenSandbox locally in Docker and writes your project config — no manual server setup.

Fetch an agent spec from any URL, validate it, and save it locally — dependencies resolved recursively.

Load any saved spec with @drej/agent — the CLI only manages specs on disk; the sandbox work happens on load.

Read the docs GitHub →

terminal

$ bunx drejx init
 
Starting OpenSandbox in Docker...
OpenSandbox running at
http://localhost:8080 — ready.

$ bunx drejx add \
    https://example.com/specs/code-reviewer.json
 
Agent spec saved: agents/code-reviewer.json

import { Agent, textOnly } from "@drej/agent";
 
const agent = await Agent.load(
  "agents/code-reviewer.json",
);
 
for await (const chunk of textOnly(
  agent.prompt("Review this repo."),
)) {
  process.stdout.write(chunk);
}

The RLM agent orchestration framework.

One task, split recursively.

Real workloads, not demos.

Everything, one SDK.

Ready to orchestrate?