Sandboxing

Reasons Forge makes LLM calls. The derive step runs unconstrained model output. Run it in a sandbox.

Sandbox tiers

Tier	Tool	Isolation	Best for
Lightweight	bubblewrap, firejail, sandbox-exec	Process-level	Your own code, trusted docs
Container	Docker, Podman	Filesystem + network	Open source repos, shared environments
Full VM	QEMU, Firecracker, cloud VMs	Complete	Untrusted code, adversarial inputs

Using sandboxes

# Docker
reasonsforge run --sandbox=container code --repo ./project

# Lightweight (Linux)
reasonsforge run --sandbox=bubblewrap code --repo ./project

# Full VM (via cloud or local QEMU)
reasonsforge run --sandbox=vm code --repo ./project

How to choose

The right tier depends on what the forge is processing:

• Your own code and docs — lightweight sandbox is fine. You trust the input; you just want a safety net around the LLM output.
• Open source repos you trust — container. Good isolation without the overhead of a full VM.
• Untrusted code, unknown repos, adversarial inputs — full VM. The forge cannot affect the host at all.

Design principles

All tiers produce the same output. A reasons.db built in a Docker container is identical to one built in a VM or with bubblewrap. The sandbox is an operational concern, not a forge concern.

Modules do not know which sandbox they run in. The sandbox wraps the forge process; the forge module code is unchanged regardless of tier.

API keys are injected, not stored. Keys are passed as environment variables into the sandbox. They are never written to the filesystem inside the sandbox.

Without a sandbox

You can run reasonsforge directly without any sandbox:

reasonsforge code --repo ./my-project --output reasons.db

This is fine for development and trusted inputs. For anything else, use a sandbox.

Caution

Running without a sandbox means LLM-generated code during the derive step executes with your user permissions. Only do this with inputs you trust completely.