# SandboxedJS for AI Agents

SandboxedJS provides a high-fidelity, zero-infrastructure execution environment specifically designed for AI agents. Instead of limiting your agent to a handful of tool-calling functions, SandboxedJS gives your model a real POSIX shell, a virtual filesystem, and full Node.js and Python runtimes.

Whether you are building a coding assistant, an automated researcher, or a complex agentic workflow, SandboxedJS ensures that the code your agent writes and executes is isolated from your host system while remaining functionally complete.

## Why a Real Shell for Agents?

Most agent sandboxes provide a restricted set of APIs (e.g., `read_file`, `write_file`). While safe, this creates a "capability gap" where agents struggle with real-world tasks. 

By providing a full shell, your agent can:
- **Manage Complex Projects**: Use `mkdir`, `find`, and `grep` to navigate and analyze large codebases.
- **Install Dependencies**: Use `npm install` or `pip install` to bring in the exact libraries needed for a task.
- **Execute Pipelines**: Chain commands using pipes (`|`) and redirections (`>`), allowing the agent to use standard Unix tools for data processing.
- **Run Multi-Language Workflows**: Seamlessly switch between JavaScript for the frontend and Python for data science within the same container.

## Integration

SandboxedJS is designed to plug into modern agent frameworks. It mirrors the `SandboxBackendProtocolV2` used by [LangChain Deep Agents](https://github.com/langchain-ai/deepagents), making it a drop-in replacement for heavier, infra-dependent backends.

```ts
import { SandboxedJsBackend, installSandboxSkills } from "sandboxedjs/agent";

const box = await createContainer({
  cwd: "/app",
  network: { allowOutbound: true },
});

// Equip the container with standard agent skills (ls, read, write, edit, etc.)
await installSandboxSkills(box);

const agent = createDeepAgent({
  model,
  backend: new SandboxedJsBackend(box, { cwd: "/app" }),
});
```

## Security for Agents

Because the container runs entirely in memory (or within a Worker thread), you can spin up a fresh, isolated instance for every single user session or agent task. 

- **No Host Access**: The agent cannot see your `/Users` directory or environment variables unless you explicitly mount them.
- **Network Control**: Outbound access is off by default. You decide exactly which APIs the agent can reach.
- **Instant Disposal**: Once the task is complete, `box.dispose()` wipes the entire environment instantly.

## Technical Specification

For developers contributing to the agent platform or extending the runtime, see the detailed work specifications in this folder.

- `STATE.md`: Current progress and active tasks.
- `COMMANDS.md`: Available shell commands and their implementations.
- `ROADMAP.md`: The path toward a fully compatible native Python package platform.