Skip to content

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.

ModeWhat runs without askingWhat waits for you
AskSearching, reading, and shell commands that stay inside the sandboxFile edits, other tool calls, and commands that need the network or write outside the allowed folders
AutoActions a review model judges safeActions the review blocks, which you can still run anyway
YoloEverything, without the sandboxNothing

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.

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.

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.

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.

Approvals you remember are stored on this device only and never sync. Review or clear them in Settings → Permissions.

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

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.