SDK Reference

The SDK and the CLI are two interfaces over the same store. They write the same files, enforce the same rules, and raise the same error codes — so you can mix them freely. Reach for the SDK when you are generating environments programmatically, wiring Silo into a test suite, or building tooling on top.

import { Silo } from "@burn0/silo";

const silo = await Silo.open({ cwd: process.cwd() });
const env = await silo.environments.create({ name: "support", template: "blank" });

await env.data.add("tickets", [{ id: "TKT-001", status: "open" }]);
await env.tasks.add({
  id: "TASK-001",
  title: "Triage the queue",
  instruction: "...",
  verifierId: "VER-001",
  difficulty: "easy",
});
await env.tools.scaffold({ name: "close_ticket", description: "..." });
await env.verifiers.scaffold({ id: "VER-001", taskId: "TASK-001" });

const report = await env.validate();

`Silo.open()`

Binds to one project root.

const silo = await Silo.open({ cwd: "/path/to/project" });

cwd defaults to process.cwd(). It is captured once rather than read again further down, so a single process can serve several projects at the same time. Opening a path that is not a directory throws environment_not_found.

Member	Returns
`silo.cwd`	The resolved project root
`silo.environments`	The environment registry
`silo.environment(name)`	Shorthand for `silo.environments.open(name)`

Environments

await silo.environments.list();                                   // string[]
await silo.environments.create({ name, template, tools });        // SiloEnvironment
await silo.environments.open(name);                               // SiloEnvironment

create is silo init. open binds to one that already exists and throws environment_not_found if it does not. A SiloEnvironment exposes name, cwd, the four resource collections, and validate().

Resources

Each resource collection mirrors the matching CLI command family.

SDK	CLI
`env.data.list()`	`data list`
`env.data.get(name)`	`data show`
`env.data.add(name, value)`	`data add`
`env.data.update(name, value)`	`data update`
`env.data.put(name, value)`	(add or update)
`env.data.remove(name)`	`data remove`
`env.tasks.list()`	`task list`
`env.tasks.get(id)`	`task show`
`env.tasks.add(task)`	`task add`
`env.tasks.update(task)`	`task update`
`env.tasks.put(task)`	(add or update)
`env.tasks.remove(id)`	`task remove`
`env.tools.list()`	`tool list`
`env.tools.scaffold(options)`	`tool add`
`env.verifiers.list()`	`verifier list`
`env.verifiers.scaffold(options)`	`verifier add`

put has no CLI equivalent — it adds or replaces without caring which, which is what you want in a generator that may run twice.

const entries = await env.data.list();      // DataEntry[]
const tickets = await env.data.get("tickets");
const tasks = await env.tasks.list();       // SiloTask[]

Mutating methods return the path they wrote, so a generator can log exactly what it produced.

Scaffolding

const result = await env.tools.scaffold({
  name: "close_ticket",
  description: "Close a resolved ticket.",
});

const verifier = await env.verifiers.scaffold({
  id: "VER-001",
  taskId: "TASK-001",
  name: "Ticket closed",
});

Both return a ScaffoldResult describing the file created and the barrel entry added. As with the CLI, the generated code compiles and fails on purpose — it never contains business logic.

Validation

const report = await env.validate();

if (!report.ok) {
  for (const finding of report.findings) {
    console.error(`${finding.level} ${finding.code} ${finding.message}`);
  }
}

Same shape as env validate --json: ok, findings[] and counts. It runs the real TypeScript compiler, not a file-presence check.

Errors

Every failure throws a SiloError with a stable code:

import { SiloError, isSiloError } from "@burn0/silo";

try {
  await env.tasks.add(task);
} catch (error) {
  if (isSiloError(error) && error.code === "task_already_exists") {
    await env.tasks.update(task);
  }
}

isSiloError is a type guard, so error.code and error.details are typed inside the branch. See Error Codes.

Authoring exports

The SDK also re-exports what environment code itself is written against:

import {
  defineTool, bindTools, toolError, ToolError,   // tools
  defineVerifier, check, optional,               // verifiers
} from "@burn0/silo";

Those are the values your tools/ and verifiers/ files import. They are runtime values, not types, so the package must be installed for an environment to run — not only to type-check.

Running

Running a rollout is currently a CLI concern. To run agents from a script, shell out:

execFileSync("npx", ["@burn0/silo", "run", "--env", "demo", "--task", "TASK-001"]);

Artifacts land in .silo/runs/<runId>/ either way, and result.json is designed to be read back programmatically — see Run Artifacts.

Getting Started

Environments

Running Agents

Guides

Reference

SDK Reference

`Silo.open()`

Environments

Resources

Scaffolding

Validation

Errors

Authoring exports

Running

​Silo.open()

​Environments

​Resources

​Scaffolding

​Validation

​Errors

​Authoring exports

​Running

`Silo.open()`

Environments

Resources

Scaffolding

Validation

Errors

Authoring exports

Running