Bash sandbox + snapshots

In Web Forge, every session gets its own isolated Linux container. The agent runs bash against it. Network is on. Files in your workspace are mirrored in. Snapshots restore the container in 1-2 seconds on resume.

Installed tools

Out of the box:

Category	Tools
Shells	bash
Version control	git
Network	curl, wget
JSON / data	jq
Search	ripgrep (`rg`), fd
Python	python3, pip, pytest, black, ruff, requests, httpx
Node	nodejs, npm, typescript, prettier, eslint
Other	tree, file, stat, sort, uniq, awk, sed

Need more? The agent can pip install or npm install - network is on, the install lands in the container. Caveat: those installs don't persist across snapshot restore unless they're in package.json or requirements.txt in your workspace (workspace files are re-mirrored on each container spawn).

Resource limits

Per container:

Cap	Value
Memory	1 GB
CPU	1 core
PIDs	200
Capabilities	dropped (no privileged ops)
No new privileges	yes
User	`sandbox` (unprivileged)

Per bash call:

Cap	Value
Default timeout	60 seconds
Max timeout	300 seconds
Stdout/stderr capture	16 KB each
Command length	8 KB
Concurrent execs	4

For long-running commands (servers, watchers, dev builds), set run_in_background=true. The agent gets a shell_id it can poll with bash_output and terminate with kill_shell.

Workspace mount

Your virtual workspace files appear at /workspace/ inside the container. The agent's bash sessions start there.

Read: any file in /workspace/ (the agent sees current snapshots of workspace files at container spawn).
Write: changes inside /workspace/ inside the container DON'T sync back to the browser workspace. To update browser-visible files, use workspace_write / workspace_edit.
The split is intentional - keeps node_modules and build artifacts out of your zip download.

Snapshots

After 30 minutes of session idle, the container is committed to a snapshot image (forge-snap:<session-id>) and stopped. The container itself is removed; the snapshot stays.

On next use, the snapshot is restored as a fresh container in 1-2 seconds. State preserved:

Files in /home/sandbox/, /tmp/, /opt/, and anywhere else outside /workspace/.
Installed packages (pip install, npm install).
Background processes are NOT preserved - they have to be restarted by the agent.
Workspace mirror is refreshed from current browser state (which may have changed during the gap).

Snapshot cap: 20 per system. Oldest evicted when full. Each snapshot is ~280 MB.

Bash in plan mode

Plan mode (Shift+Tab into plan) strips bash from the tool list server-side. The agent literally cannot exec anything. Use this when researching - you don't want a misfired rm.

Network

Network is on for:

pip, npm, apt (where allowed)
curl, wget
DNS resolution
Outbound HTTPS

This means the agent can install dependencies, fetch from APIs, etc. It also means any malicious script the agent runs can phone out. Don't share session URLs with strangers.

Security model

The sandbox uses Docker isolation. Caveats:

Container, not VM. Kernel is shared with host. Container escape vulnerabilities (rare but real in the wild) bypass isolation.
Manager has docker socket. The container that orchestrates spawning has root-equivalent access on the host. This works for self-hosted single-user; it's NOT multi-tenant safe.
Don't paste secrets into prompts. The agent reads everything you send.

For multi-tenant production isolation, you'd want firecracker microVMs or similar - out of scope for IsonForge today.

Background bash

For long-running tasks (dev server, file watcher):

> start the dev server

The agent calls bash with run_in_background=true. Returns immediately with a shell_id. The agent can:

Poll output: bash_output(shell_id) - returns new lines since last poll.
Wait, run other tools, then poll again.
Kill: kill_shell(shell_id) - SIGTERM, then SIGKILL after 3s.

In your REPL view, background shells show as separate streaming panes.

CLI equivalent

The CLI doesn't have a sandbox - it runs bash directly in your shell. This is intentional: CLI users have a real project directory and want real effects. Web Forge users have a virtual workspace and need sandbox isolation.

For CLI, bash is gated by permission modes (default = ask; safe-bash prefixes auto-approve; dangerous commands flagged).

Caveats

Cold spawn 1-2s. First bash call in a session takes 1-2 seconds while the container starts.
Snapshot bloat. 20 snapshots = ~5.6 GB on the host. Self-hosted operators should monitor.
Workspace mirror is point-in-time. Files modified in your browser while the agent is bash-ing don't sync until next mirror refresh.