Tool Permissions
Plain jan auto-approves tool calls. Use jan --safe to review writes, shell commands, and
MCP tool calls before allowing them. Approval and shell sandboxing are separate controls: --safe
does not enable the sandbox, and --sandbox does not turn on tool-call approval prompts.
Approval
jan # auto-approve tool calls; shell unconfined by default
jan --safe # ask for approval; shell still unconfined by default
jan --safe --sandbox # ask for approval and confine shell commandsThese sandbox defaults apply unless you have changed the project or global configuration below.
With --safe, built-in reads inside the project do not prompt. Writes and shell commands prompt
unless a policy allow rule or an existing grant covers them; MCP calls prompt unless that tool
already has a grant. Dedicated memory and skill tools do not prompt, including their write tools.
Explicit tool denies still win.
The console shows Allow once and Deny, plus a thread-level option when available.
Use the arrow keys and Enter, or press y to allow once,
n or Esc to deny, and a for the thread-level option when offered.
For write and edit, the request includes a diff preview; for shell, it shows the command.
Read the thread-level option's label before choosing it:
- Allow always (this thread) grants the relevant permission category for built-in file tools, not just that path. Writes inside and outside the project are separate categories. For MCP, the grant covers only the named tool.
- Allow all 'git' commands (this thread) grants the named base command, not every shell call. Compound commands list each base, for example Allow all 'cargo', 'git' commands (this thread). A later command is covered only when all of its bases are granted.
- Allow this exact command (this thread) is used when Jan cannot safely decompose the command; the grant matches its normalized command text rather than a base command.
Grants are held in memory for the thread, not persisted to agent.toml. Choose Allow once when
you only mean to authorize the current request. Sandbox escalation is handled separately below:
it does not offer a thread-level grant.
Capabilities
What each kind of tool does by default:
| Capability or tool group | Examples | Plain jan | jan --safe |
|---|---|---|---|
| Read inside the project | read, ls, find, grep | Allowed | Allowed |
| Network | web_search, web_fetch | Allowed | Allowed |
| Write | write, edit | Auto-approved | Prompts unless allowed or granted |
| Exec | shell | Auto-approved | Prompts unless allowed or command-granted |
| Workspace tools | memory_read, memory_list, memory_write, skill_read, skill_list, skill_write | Allowed | Allowed |
| MCP tools | Tools from configured MCP servers | Auto-approved | Prompts unless that tool is granted |
Tool denies, plan mode, and sandbox restrictions still apply. File access outside the project has separate permission checks; running a command outside the sandbox has its own approval rules below.
Path checks
File-tool paths are checked against the project root and session scratch. Direct reads or writes
outside those roots need a separate permission. Plain jan approves these requests automatically;
--safe asks unless a policy allow rule or an existing grant covers them. These checks do not
prevent all access outside the project. Dedicated memory and skill tools use their own workspace
and do not prompt, including for writes; explicit tool denies still apply.
shell starts in the project root, but its commands can reach outside it when unconfined.
Approval decides whether a call may run; the shell sandbox limits what the command can access.
Plan mode separately blocks write and exec tools before the approval gate.
A symbolic link is followed only while it stays inside the project (or the session scratch). Links
that point back into your own tree - the ones every node_modules is full of - work normally; a
link out of the project is refused, so it can't be used to smuggle a read or a write past the check
above.
Project policy
The project's agent.toml (in ~/.jan/projects/<slug>/) sets what a project exposes:
[tools]
# read-only | deny | allow
default = "read-only"
# Exposed even under deny; the deny list wins over everything
allow = []
deny = []
# Explicit pre-approval for matching built-in tools
allow_write = []
# Whether the sandboxed shell can reach the network
# allow_network = true
# Whether shell commands run under OS confinement at all
# sandbox = truedefault | Effect |
|---|---|
read-only | The default. MCP tools and built-in reads available; built-in writes and exec go through the approval gate (auto-approved unless --safe) |
deny | Locks down all MCP tools. Anything in allow is still exposed |
allow | Exposes everything not in deny |
deny always wins over allow. A tool in both lists is denied.
The shell tool is named shell; it used to be bash, and that name is no longer recognised.
Rename bash to shell wherever you name the tool: allow, deny, hook matchers and a
subagent's allowed_tools. An old deny = ["bash"] matches nothing. The jan CLI warns about
each such [tools] entry when a run starts (the desktop app does not read [tools]), and every
surface refuses a subagent whose allowed_tools still says bash. jan mcp serve --tool bash
says so too.
The shell sandbox
Jan can run shell commands under OS confinement - bubblewrap on Linux, Seatbelt on macOS,
AppContainer on Windows. Confined, a command can write only the project and its scratch
directory, and reaches the network only if allowed. Reads are looser: the CLI keeps $HOME readable
so git and ssh credential helpers work ([tools].allow_home_read, set it to false to close
that), while the desktop masks it entirely.
While the sandbox is on, Jan's own home, ~/.jan, is hidden from every tool and from the shell,
even when you run jan from your home directory. It holds config.toml (provider keys and hooks)
and each project's agent.toml, memory and threads, so no approval can open it: file tools refuse
the path, ls, find and grep leave it out, and the shell sees an empty directory. The agent
still reaches memory and skills through its memory_* and skill_* tools. A git worktree Jan
created under ~/.jan/worktrees/ stays reachable, because it is the project being worked on.
Whether it is on depends on the surface:
| Surface | Sandbox | Can it be changed? |
|---|---|---|
| Desktop chat agent | Always on | No. If no sandbox can be established, shell is withheld rather than run unconfined |
jan CLI and console | Off by default | Yes, see below |
The CLI runs unconfined because it is a coding agent in your own project, started from your own
terminal - the same trust make, git push, or any other tool you run there already has - and
confinement breaks the toolchains projects actually build with often enough to be the wrong default.
Tool-call approval prompts are also off by default. Tool denies and plan-mode restrictions still
apply, but shell calls that do not request sandbox escalation do not pause for approval. Use
--safe for prompts, --sandbox for confinement, or both.
With the sandbox off, a shell command runs with your access, whether approved manually or automatically. Nothing confines it to the project. Turn on the sandbox if you need confinement.
Turning it on
Three levels, most specific first:
jan --sandbox # this session only
jan --no-sandbox # this session only, overriding a setting below# ~/.jan/projects/<slug>/agent.toml - every session in this project
[tools]
sandbox = true# ~/.jan/config.toml - for every project you work on
sandbox = trueA flag beats the project file, which beats the global setting, which beats the default. Every level
works in both directions, which is why --no-sandbox exists: without it, turning confinement on
permanently would leave no way to run a single command without it.
jan cli agent status reports what a run would actually do:
"sandbox": { "enabled": false, "backend": "bubblewrap" }backend is the confinement that would be used. none means none is available on this machine -
with enabled: true that combination is what withholds shell entirely.
Running a command outside the sandbox
Some everyday commands write outside the project: cargo build fills ~/.cargo/registry, and
pip, npm and go write their caches under your home directory. Inside the sandbox these fail
with a read-only file system error. When that happens to a command the task needs, the agent can
ask to rerun it outside the sandbox. It sets escalate on the shell call and gives a one-line
reason. You are asked first, unless allow_escalation is enabled and the command is already
approved to run (see below):
shell wants exec outside the sandbox
$ cargo build
why cargo needs to write ~/.cargo/registry to fetch crates
> Allow once
DenyAn approved command runs with your own access, like a command you typed. The minimal environment (below) still applies. Escalation has additional approval rules:
- Tool-call auto-approval does not approve escalation. Even without
--safe, a request to leave the sandbox still prompts unless you explicitly enableallow_escalation, described below. - The escalation prompt has no "allow always" option. Without
allow_escalation, each escalation needs a fresh answer, even if the command already has an execution grant. - Where approval is needed but nobody can answer, it is refused. That covers a headless
jan cli agent runreading from a pipe or CI, and a subagent whose parent cannot be asked. The command does not run at all, and the model is told how you could enable it. - The desktop never escalates. Its chat sandbox is throwaway by design.
- An escalated command runs outside the sandbox, so
~/.janis not hidden from it. A command that names~/.janoutright is refused before anyone is asked, but that check only reads the command text: a command that reaches the folder indirectly (cd ~ && cat .jan/config.toml) gets past it, and could read your provider keys. Read the command before you approve it.
For unattended runs that accept the risk, allow escalation without a prompt. Nobody then reads
the command, so any escalated command can reach everything you can, ~/.jan included:
jan cli agent run --sandbox --allow-escalation "..."# ~/.jan/projects/<slug>/agent.toml
[tools]
allow_escalation = trueWith allow_escalation, an escalated command skips the escalation prompt when the command itself
is approved: by auto-approval, a policy allow rule for shell, or an existing command grant.
This includes --safe sessions with a matching policy allow or command grant. Otherwise, --safe
shows a single prompt for that request to run outside the sandbox. allow_escalation never skips
an execution approval the command would otherwise need.
Which shell runs commands
On macOS and Linux the shell tool runs bash (or sh where there is none). On Windows it runs
PowerShell, never a bash: the sandbox is an AppContainer, and Git Bash's MSYS runtime cannot start
inside one. Jan uses the first of these that it finds:
- PowerShell 7 (
pwsh), when it is installed under Program Files. The sandbox can only start programs from folders all apps may read, so apwshfrom the Microsoft Store, scoop, a zip in your profile or a dotnet tool is skipped in favor of 5.1. - Windows PowerShell 5.1, which ships with Windows.
cmd.exe.
The model is told which shell it has, so it writes PowerShell or cmd syntax when that is what
runs. Hooks and plugin tools use the same shell. To force a specific shell, set
JAN_AGENT_SHELL to its full path.
The shell environment
The shell does not inherit your full environment. Jan starts it from a minimal base -
PATH, HOME, TMPDIR, locale, and the Windows system keys - so a secret in your environment
(OPENAI_API_KEY, SSH_AUTH_SOCK, and the like) never reaches a command the model runs, whether or
not the sandbox is on. This is deliberate, but it also means a command that needs a variable you
rely on (a proxy setting, git config, a toolchain home) will not see it.
Two keys widen it, without giving up the default:
# ~/.jan/projects/<slug>/agent.toml (per project) or ~/.jan/config.toml (all projects)
[tools]
# Host variables the shell may inherit. Exact names or a "*" wildcard.
env_passthrough = ["SSH_AUTH_SOCK", "GIT_*", "http_proxy", "https_proxy"]
# Explicit values, set regardless of your environment.
[tools.env_set]
RUST_LOG = "info"env_passthroughcopies the named host variables in if they are set. The two scopes merge: the global list and the project list both apply.- A secret-looking name (containing
KEY,TOKEN,SECRET,PASSWORD,PASSWD,CREDENTIAL,HEADERSorAUTHORIZATION, case-insensitive) is never copied by a wildcard - so a broadGIT_*cannot leak aGIT_TOKEN, andOTEL_*cannot copyOTEL_EXPORTER_OTLP_HEADERS, which holds an API key when a launcher configures telemetry. To pass one deliberately, name it inenv_set, which is not filtered. env_setwins overenv_passthroughand over the global value for the same key. Under the sandbox,TMPDIR/TMP/TEMPare always pointed at the run's scratch directory regardless.
Network access
Network access is a property of the sandbox, so it applies when the sandbox is on. Unconfined, a command has whatever network access you do. The two surfaces default differently:
| Surface | How to set network access | Default |
|---|---|---|
| Desktop chat agent | The chat-screen tools toggle (agent_tools). Per session, in the UI | Off |
jan cli code-screen agent | [tools].allow_network in the project's agent.toml | On |
The split is deliberate. The desktop chat agent is ephemeral, so it stays offline unless you opt in.
The CLI is a coding agent in your own project, where one that cannot curl, git fetch, or install
a package would be largely useless.
# Take a CLI agent offline
[tools]
allow_network = falseSubagents
A subagent's tools are narrowed, never widened. For a saved subagent an allowlist further restricts its own; for a one-off it is its toolset. Either way a subagent reaches a subset of what the parent could, so delegation can't be used to escape this policy.
Turning the prompts on
Tool-call approval prompts are opt-in: start with jan --safe to review file writes, shell commands,
and MCP calls that are not already allowed or granted. Dedicated memory and skill tools stay exempt.
Add --sandbox if you also want shell confinement. See run modes.
Auto-approval only removes the prompt. The path checks and [tools] deny all still apply, as does
the shell sandbox where it is on - but on the CLI it is off by default, so auto-approved shell
commands run with your own access unless you turn it on.