Permissions and Sandbox
ChatShell’s tools can read and change files and run shell commands on your computer. The permission mode decides how much of that happens without your approval. Choose a mode per conversation from the chat input toolbar.
| Mode | What runs without asking | What waits for you |
|---|---|---|
| Ask | Searching, reading, and shell commands that stay inside the sandbox | File edits, other tool calls, and commands that need the network or write outside the allowed folders |
| Auto | Actions a review model judges safe | Actions the review blocks, which you can still run anyway |
| Yolo | Everything, without the sandbox | Nothing |
New conversations start in the default mode set in Settings → Permissions, which is Auto on a fresh install. If the model can’t review actions, an Auto conversation uses Ask instead. Switching a conversation to Yolo always asks you to confirm.
Shell commands run inside the OS sandbox. A command that stays inside it runs without a prompt. When a command needs to reach the network or write outside the allowed folders, ChatShell shows one approval card for it. File edits and other tool calls wait for your approval.
On a machine without a sandbox, every shell command is confirmed too.
Before a tool call runs, the conversation’s model reviews it and approves the safe ones without prompting you. The tool calls of one turn are reviewed together. Each review appears as a collapsible card with the outcome, the risk, and the reasoning. If the review blocks something you want, choose Run anyway once the reply finishes.
Shell commands still run inside the sandbox. If the model cannot review actions, Auto is unavailable and the conversation uses Ask.
Every tool call runs without asking and without the sandbox. Use it only for work you would be comfortable running yourself without looking.
In every mode
Section titled “In every mode”A built-in blocklist stops catastrophic commands, such as erasing the disk, no matter which mode is active. You can also give a conversation one working directory to keep its file tools in one folder.
The OS sandbox
Section titled “The OS sandbox”In Ask and Auto mode, shell commands run inside the operating system’s sandbox:
- macOS: Seatbelt
- Linux: bubblewrap
- Windows: no sandbox yet, so Ask mode confirms every shell command
The sandbox keeps commands to the allowed folders and blocks network access unless you approve it. Settings → Permissions shows whether a sandbox is available on this machine.
When the sandbox stops a command, the card lets you choose Run once outside sandbox or Allow network this session.
Approving a tool call
Section titled “Approving a tool call”An approval card offers:
- Allow once: run this call only.
- Allow for this session: run calls like this without asking for the rest of the session. The card shows exactly what the approval covers, such as the commands or the folder.
- Remember on this device: run calls like this without asking in future conversations too.
- Deny: skip the call.
Cards also warn you about risky calls, such as a command that contacts the network, deletes files outside the working directory, or reads a file that often holds API keys. Commands flagged by the security check always ask, even if you allowed similar ones for the session.
If several tools ask at once, the requests queue and appear one at a time. Switching modes clears session approvals.
Remembered approvals
Section titled “Remembered approvals”Approvals you remember are stored on this device only and never sync. Review or clear them in Settings → Permissions.
What the assistant cannot touch
Section titled “What the assistant cannot touch”- ChatShell’s own data folder, where your conversations and encrypted keys live, is off limits to every tool.
- Reading shell configuration files, which often contain secrets, needs your approval.
- The sandbox blocks access to stored credentials.
Bash environment
Section titled “Bash environment”Shell commands start with a minimal set of environment variables. To pass more through, such as a variable your build needs, add it in Settings → Permissions.