Sandbox

Every session runs in its own isolated Linux container. You get direct shell access, a full filesystem, and pre-installed runtimes — without the LLM. Use it to set up environments before prompting, inspect results after, or run commands alongside the agent.

Shell Access

Run any command in the session's sandbox:

const os = await session.shell("uname -a");
console.log(os.stdout);

const node = await session.shell("node --version");
console.log(node.stdout.trim()); // v22.x.x

const python = await session.shell("python3 --version");
console.log(python.stdout.trim()); // Python 3.x.x

The return type is always ShellResult:

interface ShellResult {
    stdout: string;
    stderr: string;
    exitCode: number;
}

Set Up Before Prompting

Pre-configure the environment so the agent starts with the right context:

const agent = client.agent("build");
const session = await agent.createSession();

// Set up a project before the agent touches it
await session.shell("mkdir -p /workspace/my-project");
await session.shell("cd /workspace/my-project && npm init -y");
await session.shell("cd /workspace/my-project && npm install zod");

// Now let the agent build on top of it
await session.send(
    "There's a project in /workspace/my-project with zod installed. " +
        "Add a src/schema.ts file that defines a User schema with name, email, and age fields.",
    { onText: delta => process.stdout.write(delta) }
);

Read Files from the Sandbox

Pull file contents directly — no need to ask the agent:

// Text files
const src = await session.getFile("/workspace/my-project/src/schema.ts");
console.log(src);

// Binary files
const buf = await session.getFileBuffer("/workspace/chart.png");

Inspect Results

After the agent finishes, verify its work:

// Run tests
const test = await session.shell("cd /workspace && npm test");
console.log(test.stdout);
console.log(`Exit code: ${test.exitCode}`);

// Check the file tree
const tree = await session.shell("find /workspace -type f -not -path '*/node_modules/*' | sort");
console.log(tree.stdout);

// Read a specific file
const readme = await session.getFile("/workspace/README.md");
console.log(readme);

Pre-installed Runtimes

Each sandbox comes with:

• Node.js (with npm, npx)
• Python 3 (with pip)
• Common CLI tools (git, curl, wget, jq, etc.)

Install additional packages at runtime:

await session.shell("pip install pandas matplotlib");
await session.shell("npm install -g typescript");

Full Example

import { createClient } from "swarmlord";

const client = createClient({
    apiKey: process.env.SWARMLORD_API_KEY!,
});

const agent = client.agent("build");
const session = await agent.createSession();

// Check what's available
const os = await session.shell("uname -a");
console.log(`OS: ${os.stdout.trim()}`);

// Set up a project
await session.shell("mkdir -p /workspace/my-project");
await session.shell("cd /workspace/my-project && npm init -y");
await session.shell("cd /workspace/my-project && npm install zod");

// Let the agent build
await session.send(
    "There's a project in /workspace/my-project with zod installed. " +
        "Add src/schema.ts with a User schema (name, email, age) " +
        "and src/validate.ts that validates sample data against it.",
    { onText: delta => process.stdout.write(delta) }
);

// Inspect
const schema = await session.getFile("/workspace/my-project/src/schema.ts");
console.log("\n--- schema.ts ---");
console.log(schema);

// Run the code
const run = await session.shell("cd /workspace/my-project && npx tsx src/validate.ts");
console.log(`\nExit ${run.exitCode}: ${run.stdout}`);

await session.end();