Step 3 of 3

Run a tool

Wrap your AI coding tool with veil run.

What you will do: Learn the flags of veil run, build a command for OpenCode, check the sandbox offline and add another tool.
Before you start: veil built in Step 1, and for the gateway profile, the gateway from Step 2.
What comes next: Read the threat model and best practices before you rely on veil.

Usage and flags

veil run [--profile offline|gateway] [--gateway HOST:PORT] [--workspace DIR] [--home DIR] -- COMMAND [ARGS...]

Flags of `veil run`
Flag	Default	Meaning
`--profile`	`offline`	`offline` has no network at all. `gateway` allows only the gateway.
`--gateway`	none	`HOST:PORT` of the gateway proxy. It is required with `--profile gateway`, and only then.
`--workspace`	current directory	The only host directory mounted read-write.
`--home`	empty, discarded	A dedicated directory mounted as `HOME`, so logins and tool state survive between runs.

veil refuses /, your real home directory and its parents as a workspace or home. It also refuses hidden directories directly under your home as a workspace. Never run it with sudo.

Command builder

Fill in the fields to build a veil run command. The builder checks the same rules as the command line. With JavaScript off, the example below is the OpenCode command from the README.

Resulting command:

./veil run --profile gateway --gateway gateway.local:8118 --workspace ~/projects/demo --home ~/veil-homes/opencode -- opencode run "add a subtract function to calc.py"

Create the home directory first, for example with mkdir -p ~/veil-homes/opencode. Replace gateway.local with the name or IP of the machine that runs the gateway. The dedicated home keeps OpenCode's login and configuration away from your real HOME.

Offline smoke test

This checks the sandbox without any network:

mkdir -p /tmp/veil-demo
./veil run --workspace /tmp/veil-demo -- /bin/sh -c 'echo "HOME=$HOME"; hostname; ls /workspace'

Using another tool

Find the domains the tool needs. Check its documentation, or watch the gateway's 403 responses.
Add the domains to the gateway allowlist in privoxy/allowlist.action. See Step 2.
Use a separate --home directory for each tool.
Make sure the tool honors HTTPS_PROXY. A tool that ignores it cannot reach the network in the gateway profile: it fails instead of leaking.