Sandboxing

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

Sandbox tiers

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

Using sandboxes

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

# Lightweight
reasonsforge run --sandbox=lightweight code --repo ./project

# Full VM
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 lightweight isolation. 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

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