Repository navigation
Shell and Sandbox
The shell tool lets the model run commands. It ships off, and none of this page applies until you turn it on. This page explains how to turn it on, which commands ask you first, and where each command actually runs.
In config.yaml (or with /config in the TUI), set:
tool_permissions:
shell: trueThat gives the model shell, which runs one command and returns its output. Five more tools let it keep a command running; turn on the ones you want beside it:
| Tool | What it adds |
|---|---|
shell_background |
Start a long command (a test suite, a build, a server) and be woken when it finishes |
shell_monitor |
The same, and be woken each time a line of output matches a pattern |
shell_interactive and shell_input
|
Open a shell in the container and type into it, for a REPL or a database client |
shell_sessions, shell_output, shell_kill
|
List, read and stop this conversation's sessions |
The change applies at the next launch.
Install Docker or Podman as well. Commands that may run code go to a container, and without a container runtime they are refused, with a message saying how to fix it. Only read-only commands run without one, on your machine.
shell_approval_mode in config.yaml decides which commands ask you first. There is no second switch: tool_approvals has no shell key, so nothing can disagree with the mode.
| Mode | Behaviour |
|---|---|
always |
Every command asks, whatever it does |
tiered |
Shipped. Only a read-only command whose arguments all stay in the workspace runs without asking. Anything that could run code asks, even inside the container |
contained |
Anything the container confines runs without asking unless it needs the network, code included. Reads outside the workspace and network commands still ask. Shown on the startup banner and the TUI's badge |
never |
Nothing ever asks |
never is the old unbounded behaviour, kept on purpose. In that mode cat ~/.aws/credentials runs on your machine, unprompted, and its output goes into the model's context. You reach it only by writing the word never.
shell_approval_mode is refused in a project's .venastine/settings.json, by name: a project's settings outrank your own, and a cloned repository must not be able to set this. An agent can still add approval to commands the mode would run unasked, but it can never wave one past the mode. An unknown mode stops the harness at startup rather than guessing, because one guess asks about everything and the other about nothing.
These settings are read once, at startup. If any is set weaker than the shipped default, the harness says so at launch, in the log, and as a badge in the TUI for the whole session.
Under tiered and contained, each command is classified once, and that same answer decides both whether it asks and where it runs, so what you approved is what runs.
| Tier | What it is | Where it runs | Asks under tiered
|
Asks under contained
|
|---|---|---|---|---|
INERT |
A read-only command, every argument inside the workspace | Container (your machine when there is no container runtime) | no | no |
HOST_READ |
Read-only, but an argument reaches outside the workspace | Your machine | yes | yes |
SANDBOXED |
Anything else without network; it may run code | Container | yes | no, once Docker or Podman is confirmed up |
SANDBOXED_NET |
Any word is on the network list (curl, pip, git, ...) |
Container, with network | yes | yes |
UNKNOWN |
Could not be classified | none | yes | yes |
The read-only commands are inert_commands in config.yaml (ls, cat, grep, wc and others), and the network list is network_allowed_commands. Every word of a command is checked against the network list, so cd x && pip install . is recognised, except for a read-only command, where only the first word counts: grep pip notes.txt still runs unasked. The model can also declare requires_network: true for something the list cannot see, such as a script that opens a socket. That only ever adds network access, and the command then asks wherever your mode allows a prompt.
Rules worth knowing, because they explain prompts that might surprise you:
-
There is no list of interpreters.
python -c,pytest(which runsconftest.py) andmake(which runs a Makefile) all run code, so every command that is notINERTis treated as able to. -
The argument check does not parse shell syntax, deliberately. Every word after the first is read as a path that must stay inside the workspace. A parser that got it wrong would auto-approve something dangerous. The cost is an occasional extra prompt:
grep /etc/passwd notes.txtsearches for a string that looks like a path, and asks. -
Quoted or escaped arguments are never
INERT. The executor strips quotes and backslashes, socat "/etc/passwd"would otherwise be checked as one thing and run as another. Such commands go to the container instead. -
On Windows, use forward slashes.
cat sub\dir\notes.txtcounts as escaped, moves to the container, and fails there. -
An approved host read still reads your machine. If you say yes to
cat /etc/shadow, it runs on the host, because that is what you approved.
The container comes from Docker, or from Podman when Docker cannot run one. Podman is used only when it can enforce the limits below; a rootless Podman that silently ignores them is refused, and the reason is shown. Inside the container:
- your workspace is mounted at
/workspace; - a
.venastine/folder in the workspace is mounted read-only, so a command cannot rewrite the definitions that feed later sessions; - the limits are 120 seconds, 2048 MB of memory, one CPU core and 200 processes, with no network unless the command is
SANDBOXED_NET; - output comes back cut at 50,000 characters.
The image is docker.io/library/python:3.13-slim. Change it with sandbox_docker_image in config.yaml or the AGENT_SANDBOX_IMAGE variable, and the limits with the sandbox_* keys.
The workspace may not be the harness itself. A workspace that is, or sits inside, the harness's install folder or ~/.config/venastine/ is refused at startup, because a sandboxed command would then have unattended write access to the code about to run next.
With no container runtime, allow_insecure_sandbox_fallback: true lets non-read-only commands run as an ordinary process on your machine instead. That process has no filesystem isolation and no network restriction. Each run asks first unless you also set auto_approve_sandbox_fallback: true. On Linux and macOS it is held to 30 CPU-seconds and 2048 MB; on Windows only the 120-second clock applies.
shell_background and shell_monitor return at once with a session id, and wake the model when the command finishes (or, for a monitor, when a line matches its pattern). At most four sessions run at once, shared with any subagents. Each is capped at one hour, and only the first 10,000 and the last 190,000 characters of its output are kept, in memory.
While one of the model's background sessions runs, your prompt is blocked. Ctrl+B and /kill stop a session, and stay usable while you are blocked. An interactive shell from shell_interactive does not block you, and nothing wakes the model when it closes, so the model is told to close it when done. In the TUI, ctrl+click a session's name in the transcript to read its command and output.
Two more places a command can run both ship off. Each is named on the startup banner and the TUI's badge while it is on.
-
WSL (
allow_wsl_backend: true, optionallywsl_distro): the model can ask for a command to run in a WSL distribution instead of the container, for work that needs your machine or a Linux toolchain the image lacks. WSL is not a sandbox. It sees your own files, always has the network, has no memory or process limits, and can start Windows programs. So only a read-only command inside the workspace runs there without asking, and a command naming a protected path is refused outright. -
SSH (
allow_ssh_backend: true, withssh_host,ssh_user,ssh_remote_workspaceand a pinnedssh_host_key): the model can run commands on that one machine. Nothing runs there without asking, not even a read-only command, because the workspace check would be answering about the wrong filesystem. It authenticates with a key or a runningssh-agent, and a host key that changes is refused.
/secrets in the TUI, or --secrets in the CLI, stores the values those backends need (an SSH key passphrase, a login, a sudo password) in ~/.config/venastine/secrets.json, encrypted under a master passphrase you type once a session. Values are only ever entered at a masked prompt, never on a command line. A stored value never reaches the model: it is stripped from tool output whatever your redaction setting.
On WSL and SSH only, a command can run as root. The harness supplies the stored sudo password on the command's input and nowhere else, and asks you every time, in every approval mode except never. With no stored password for that machine, the command is refused, and the refusal names the entry to create.
Checked against release 0.3.12 (commit f33ef8a). The README's shell section is the reference.
Start here
Guides
Reference