Permissions & sandboxing

Every tool call passes a permission gate, and every session can run inside an OS-level sandbox. This is the part that decides how much autonomy is safe.

The permission gate

Tools do not call your system directly. Each invocation is wrapped, and the wrapper evaluates the current mode, your configured rules, and whether plan mode is active:

flow

evaluatePermission(mode, rules, planResearching, readOnly)
  → "allow"  → run immediately
  → "deny"   → throw (the model sees a tool error)
  → "ask"    → prompt: allow once / allow for session / deny

Precedence is fixed: deny rules win, then allow rules, then the mode default. A deny rule cannot be overridden by loosening the mode, which is what makes it useful as a guardrail rather than a suggestion.

Permission modes

Cycle modes at any time with Shift+Tab, including mid-turn — the change applies to the next tool call, so you can tighten things the moment a run looks wrong.

Mode	Behaviour
`ask`	Default. Read-only tools run; anything mutating or networked prompts first.
`accept-edits`	File edits run without prompting; shell commands and network access still ask.
`bypass`	Everything runs unprompted. No gate.
`auto`	An AI layer classifies each call, auto-allowing safe ones and escalating risky ones to you.

Set the starting mode per session with --permissions:

bash

tachyon --permissions accept-edits

Allow and deny rules

Rules live in settings and apply regardless of mode, which makes them the right home for anything you never want to think about again — auto-allowing your test runner, and permanently denying commands that touch production.

.tachyon/settings.json

{
  "permissions": {
    "allow": ["bash(npm test)", "bash(npm run lint)", "read"],
    "deny": ["bash(terraform apply)", "bash(kubectl *)"]
  }
}

Because a repo's .tachyon/settings.json is committed, deny rules are also how a team encodes shared guardrails — everyone who runs the agent in that repo inherits them.

OS-level sandboxing

The permission gate governs what the agent asks to do. Sandboxing governs what it is capable of doing, and is enforced by the kernel rather than by application logic:

Linux — bwrap (bubblewrap) namespaces.
macOS — Seatbelt.
Anywhere — Docker, for full isolation or parity with CI.

Network access is denied by default. Tools that reach the network — web_fetch, web_search — are the exception rather than the norm, and a sandboxed session cannot exfiltrate a repository even if convinced to try.

Confirm what is actually active on your machine with tachyon doctor. If no backend is available, the agent runs unconfined and the permission gate is your only control.

Picking a posture

Three configurations cover most real use:

Learning a new repo — ask, sandbox on. Slow and chatty, but you see every step.
Routine work you understand — accept-edits, sandbox on, deny rules for anything deployment-shaped. Edits flow; commands still stop.
Long autonomous runs — auto inside --worktree, so the blast radius is a throwaway branch and a bad run costs you a git worktree remove.