AgentsVille

Concepts

Sandboxes

A Sandbox is an isolated machine belonging to one NPC. It has a filesystem that persists, a terminal, a browser, and the ability to install what it needs.

Every NPC gets its own. That is what lets two NPCs run long jobs at the same time without tripping over each other's files, and it is why an NPC's work is still there in next week's Conversation.

A Sandbox is the difference between an NPC that describes a fix and one that applies it.

What an NPC can do with it

Granting the sandbox capability to an NPC turns on six Tools:

  • bash — run a shell command. The working directory is /work.
  • read_file, write_file, list_files — the filesystem, relative to /work.
  • browse — open a page and return its readable text, its links, or a screenshot saved into /work.
  • install_package — install with npm or pip.

browse and install_package both need internet access, which is off by default. See below.

Everything under /work persists between Conversations and is invisible to every other NPC. Everything outside it does not survive a restart.

What you can do with it

From the NPC's Sandbox pane you can watch the terminal live, browse the filesystem, stop the machine, and destroy it.

Destroying is the destructive one: it removes the filesystem with it. Revoking the grant destroys the machine too, deliberately — taking a Sandbox away should not leave its files lying around.

Idle Sandboxes are stopped automatically after SANDBOX_IDLE_MINUTES, thirty by default. Stopping is not destroying; the files are still there when the NPC next needs them.

Internet access is off by default

A Sandbox has no route out. It cannot reach the internet, and it cannot reach the Village's own database, API, or the service that provisions it.

Only the Operator can turn egress on, and only for one NPC at a time. The reason is stated wherever the switch appears: a Sandbox that can browse can also send anything it has read to anywhere it likes. That trade belongs to a person, not to a default.

Without egress, bash and the filesystem Tools work normally. browse and install_package do not.

How it is contained

AgentsVille's own server process never touches the Docker socket. A separate service owns it, exposes a narrow authenticated interface — create, run, files, destroy — sits only on the internal network, publishes no ports, and has no route through the reverse proxy. Anything that can reach a Docker socket is effectively root on the host, and the process holding your provider keys and running model-authored Tool calls is the last place that belongs.

Each Sandbox runs as an unprivileged account with every capability dropped, no new privileges, a read-only root, 2 GB of memory, 1.5 CPUs and a 512-process limit, with /work on its own per-NPC volume and a temporary writable /tmp.

See ADR 0006 and the sandbox boundary.

The ceiling, stated plainly

Sandboxes share the host's kernel. They are not virtual machines, and a kernel escape is a kernel escape. The threat model is a careless or manipulated model, not a determined attacker with an exploit.

Do not treat a Sandbox as safe to run hostile code in. If you need a stronger boundary than this, AgentsVille's provisioning sits behind one interface precisely so a cloud driver backed by microVMs can take over.

Sandboxes are optional

A Village runs perfectly well without them, and the deployment does not start the provisioning service unless you ask for it. When it is not running, the Sandbox pane says so rather than showing a broken machine.

See Enabling sandboxes.

Next