Skip to content

Shell and Sandbox

SolenopsisCampo edited this page Nov 8, 2026 · 1 revision

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.

Turning it on

In config.yaml (or with /config in the TUI), set:

tool_permissions:
  shell: true

That 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.

Approval modes

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.

What a command is classified as

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 runs conftest.py) and make (which runs a Makefile) all run code, so every command that is not INERT is 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.txt searches for a string that looks like a path, and asks.
  • Quoted or escaped arguments are never INERT. The executor strips quotes and backslashes, so cat "/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.txt counts 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.

Where commands run

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.

Without a container: the weak fallback

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.

Background sessions

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.

Other backends: WSL and SSH

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, optionally wsl_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, with ssh_host, ssh_user, ssh_remote_workspace and a pinned ssh_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 running ssh-agent, and a host key that changes is refused.

Credentials and root

/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.

Clone this wiki locally