Virtual Infrastructure (Sandboxing)

interface Sandbox {
  fs: VirtualFs;
  computer: VirtualComputer;
  dispose?(): Promise<void>;
  init?(sandboxId?: string): Promise<void>;
  sandboxId?(): string | undefined;
}

import { LocalAgent } from "noumen/local";
import { UnsandboxedAgent } from "noumen/unsandboxed";

// Equivalent to new Agent({ ..., sandbox: LocalSandbox({ cwd }) })
const sandboxed = LocalAgent({ provider: "anthropic", cwd: "/my/project" });

// Equivalent to new Agent({ ..., sandbox: UnsandboxedLocal({ cwd }) })
const raw = UnsandboxedAgent({ provider: "anthropic", cwd: "/my/project" });

const agent = LocalAgent({
  provider: "anthropic",
  cwd: "/my/project",
  localSandbox: {
    sandbox: {
      filesystem: { denyRead: ["/etc/shadow"] },
      network: { allowedDomains: ["api.openai.com"] },
    },
  },
});

pnpm add @anthropic-ai/sandbox-runtime

import { LocalSandbox } from "noumen/local";

const sandbox = LocalSandbox({ cwd: "/my/project" });

const sandbox = LocalSandbox({
  cwd: "/my/project",
  sandbox: {
    filesystem: {
      allowWrite: ["/my/project", "/tmp"],
      denyRead: ["/etc/shadow", "~/.ssh"],
    },
    network: {
      allowedDomains: ["api.openai.com", "registry.npmjs.org"],
    },
  },
});

import { UnsandboxedLocal } from "noumen/unsandboxed";

const sandbox = UnsandboxedLocal({ cwd: "/my/project" });

import { SpritesSandbox } from "noumen/sprites";

const sandbox = SpritesSandbox({ token: process.env.SPRITE_TOKEN! });
const agent = new Agent({ provider, sandbox });

// Sprite created automatically on first createThread(). Cleaned up by:
await agent.close();

const sandbox = SpritesSandbox({
  token: process.env.SPRITE_TOKEN!,
  spriteName: "my-sprite",
});

pnpm add dockerode

import { DockerSandbox } from "noumen/docker";

const sandbox = DockerSandbox({ image: "node:22", cwd: "/workspace" });
const agent = new Agent({ provider, sandbox });

// Container created and started on first createThread(). Cleaned up by:
await agent.close();

import Docker from "dockerode";
import { DockerSandbox } from "noumen/docker";

const docker = new Docker();
const container = await docker.createContainer({
  Image: "node:22",
  Cmd: ["sleep", "infinity"],
  Tty: false,
});
await container.start();

const sandbox = DockerSandbox({ container, cwd: "/workspace" });
const agent = new Agent({ provider, sandbox });

await container.stop();
await container.remove();

pnpm add e2b

import { E2BSandbox } from "noumen/e2b";

const sandbox = E2BSandbox({ template: "base" });
const agent = new Agent({ provider, sandbox });

// E2B sandbox created on first createThread(). Cleaned up by:
await agent.close();

import { Sandbox as E2BSandboxSDK } from "e2b";
import { E2BSandbox } from "noumen/e2b";

const e2b = await E2BSandboxSDK.create();
const sandbox = E2BSandbox({ sandbox: e2b, cwd: "/home/user" });
const agent = new Agent({ provider, sandbox });

await e2b.close();

pnpm add freestyle-sandboxes

import { FreestyleSandbox } from "noumen/freestyle";

const sandbox = FreestyleSandbox({ cwd: "/workspace" });
const agent = new Agent({ provider, sandbox });

// VM suspended on close — resumes instantly on next session:
await agent.close();

const sandbox = FreestyleSandbox({
  snapshotId: "abc123",
  cwd: "/workspace",
});

import { freestyle } from "freestyle-sandboxes";
import { FreestyleSandbox } from "noumen/freestyle";

const { vm } = await freestyle.vms.create({ workdir: "/workspace" });
const sandbox = FreestyleSandbox({ vm, cwd: "/workspace" });
const agent = new Agent({ provider, sandbox });

pnpm add ssh2

import { Agent } from "noumen";
import { SshSandbox } from "noumen/ssh";
import fs from "node:fs";

const sandbox = SshSandbox({
  host: "dev.example.com",
  username: "deploy",
  privateKey: fs.readFileSync("/home/deploy/.ssh/id_ed25519"),
  cwd: "/home/deploy/project",
});
const agent = new Agent({ provider, sandbox });

// SSH connection closed on dispose:
await agent.close();

import { Client } from "ssh2";
import { SshSandbox } from "noumen/ssh";

const client = new Client();
await new Promise<void>((resolve) => {
  client.on("ready", resolve);
  client.connect({ host: "10.0.0.5", username: "root", privateKey: key });
});

const sandbox = SshSandbox({ client, cwd: "/workspace" });
const agent = new Agent({ provider, sandbox });

client.end();

import type { Sandbox, VirtualFs, VirtualComputer, CommandResult, ExecOptions } from "noumen";

class MyComputer implements VirtualComputer {
  async executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult> {
    // your implementation
  }
}

const sandbox: Sandbox = {
  fs: new MyCustomFs(),
  computer: new MyComputer(),

  // Optional: enable auto-creation and session-aware lifecycle
  async init(sandboxId?: string) {
    // Create a new resource or reconnect to sandboxId
  },
  sandboxId() {
    return "my-resource-id"; // persisted in session metadata
  },
  async dispose() {
    // Tear down auto-created resources
  },
};

interface VirtualFs {
  readFile(path: string, opts?: ReadOptions): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  appendFile(path: string, content: string): Promise<void>;
  deleteFile(path: string, opts?: { recursive?: boolean }): Promise<void>;
  mkdir(path: string, opts?: { recursive?: boolean }): Promise<void>;
  readdir(path: string, opts?: { recursive?: boolean }): Promise<FileEntry[]>;
  exists(path: string): Promise<boolean>;
  stat(path: string): Promise<FileStat>;
}

interface VirtualComputer {
  executeCommand(command: string, opts?: ExecOptions): Promise<CommandResult>;
}