# The security model

Giving AI hands means deciding, carefully, what those hands may touch.

**How this code is written and checked.** Gezel is open source under the MIT license: anyone can read it, audit it, build it and fork it, and anyone can propose a change. The code itself is written by one team, so every control described here has a single accountable author and one set of conventions. The full threat model, every enforced control and its current status, and the known limitations are in the [security architecture](https://github.com/bendyline/gezel/blob/main/docs/security-architecture.md). Like any software, Gezel will have security bugs we have not found yet, and we fix them as they are reported. If you find one, please report it privately as described in the project's [security policy](https://github.com/bendyline/gezel/blob/main/SECURITY.md) rather than in a public issue. [Governance](https://gezel.com/docs/governance/) says more about who writes Gezel and how a change is checked, and [What leaves this computer](https://gezel.com/docs/what-leaves-this-computer/) lists every kind of network traffic and the security level that allows it.

**Our security model is not designed to be perfect.** In many places, the security design focuses on keeping honest models honest via layers of "defense in depth". This lets gezel still be useful without requiring you to make every fiddly technical security decision, and without requiring exotic and complicated isolation mechanisms (e.g., containers). Think of the security design like multiple 5-foot-tall chain-link fences: it keeps things corralled, but a determined attacker (a purpose-built malicious program already on your machine) could hop over them.

Also, most of this guidance applies whenever a model acts through gezel's own tools — local models and direct API providers (OpenAI and Anthropic keys) alike. If you work through the Claude CLI, Codex CLI, or GitHub Copilot, those harnesses run their own tool loops under their own security designs: gezel configures them — permission modes, sandbox settings — but the enforcement is theirs. Like us, those providers put a lot of work and thought into securely managing threads, but flaws can happen anywhere.

## How gezel secures a model's hands

Gezel layers its guardrails:

### The service is locked to your machine

The background service listens only on your computer, over an encrypted loopback channel, and requires a credential that rotates every time the service starts. The desktop app also pins the service's certificate. These controls keep the service off your local network and reject clients that do not have a current credential.

They are not a wall against malicious software already running as **your** operating-system account, or against an administrator. Software with those powers can generally read files your account can read, including Gezel's user-scoped connection details. The separately installed machine engine has a credential that local user daemons can discover by design, but that credential is limited to inference and model management — it cannot read projects, the crew, chats, tools, or credentials.

### In a container, people sign in

[Gezel in Docker](https://gezel.com/docs/gezel-in-docker/) is the one way Gezel answers on a network. Its listener is separate from the service's own: it accepts only people signed in with an account and programs holding a key you made, and it leaves out every route that trusts a caller on the same computer. By default it answers only on the computer running Docker; reaching it from other devices goes through HTTPS you put in front of it. Passwords are stored as scrypt hashes, sign-ins slow down after repeated mistakes, and History records who did what. Every account can do everything for now, terminals included, so add only people you trust with that computer.

### Workspaces have walls

A model using Gezel's workspace tools sees that project's workspace — not your whole disk. Paths those tools receive are checked against the workspace boundary before a file is read or written, so "../" tricks and symlink hops end at the wall. Provider-native tools and explicitly approved full-trust commands are different execution classes; their limits are described below.

### Scripts run in layered isolation

Gezel's **sandboxed standalone-script tools** run code in a separate process wrapped in several independent layers:

- **Its own small world.** The script gets a fresh scratch area, and its writes are confined to that area and the project workspace — not your disk. Node's permission model checks the file boundary as one layer of the sandbox.
- **No calling for backup.** The script can't launch other programs, spawn workers, or load native extensions. Where the operating system can enforce it (next point), a script also can't quietly open its own connection to the internet — when a model needs the web, it goes through gezel's named tools (search, fetch, the browser), which are policy-checked and show up in History. In most configurations, whatever a script does, it does alone, inside the fence of the project workspace.
- **The operating system holds the outer wall where it can.** Untrusted code that must run without network access starts only when Gezel can apply a supported OS boundary — macOS Seatbelt, the Windows sandbox (Microsoft's process container, on recent Windows 11), or a probed systemd boundary for compatible Linux jobs. Otherwise Gezel refuses to start it. On macOS and Windows that wall surrounds every script run, and on Windows it also holds the script to the same folders as the file limits above. Settings → Security & compliance shows whether the Windows sandbox is active on your PC, says why when it isn't, and has a switch to turn it off. One narrow compatibility path exists for byte-verified first-party scripts shipped in Gezel's standard library or catalog: where a job cannot use the OS boundary, those trusted bytes may run with the remaining filesystem limits, subprocess/worker/addon denial, environment scrubbing, and JavaScript network-denial layers. Edited, user-authored, and model-authored scripts do not receive that exception.
- **Scripts a model writes follow your network setting where there is no wall.** On Windows when the Windows sandbox is off or not available, and on Linux without the systemd boundary, `run_nodejs_script` and `derive_file` are withheld unless your security level already lets Gezel use external services (as Free does). When it does, these scripts run with the other layers but with ordinary network access. That access is direct: it skips the checks the named web tools apply, its requests do not appear in History, and it can reach addresses on your own machine and local network. On macOS, on Windows with the sandbox active, and on Linux with the boundary, they always run without network access.
- **A time and memory leash.** Every run has a deadline and can be capped on memory, so a runaway script gets stopped instead of dragging your machine down.

The layers deliberately overlap, but they are defense in depth rather than a promise that hostile code can never escape.

Some tools deliberately run with more authority. **Package scripts and installed package binaries** (`run_package_script` and `run_npx`) are off unless Settings → Security & compliance has **Run package scripts** on, which Unrestricted does and Lockdown does not. When it is on, and after showing the exact command and receiving your approval, they run as your operating-system account. They may start other programs, use the network, and read or change files outside the project. A persistent approval is tied to the exact command, its arguments, and the content hashes of local inputs Gezel can identify — such as `package.json`, a referenced script, relative static imports, or an installed binary entry. Changing one of those files asks for approval again. Commands can still discover files dynamically, load implicit configuration, resolve other programs through `PATH`, use outside-project or directory/glob inputs, or fetch code from the network, so this binding is not a complete dependency graph and does not turn package commands into a sandbox. A separate switch, **Edit package scripts**, decides whether Gezel may add or change the scripts in a project's `package.json` at all. A script runs later with your whole account, from Gezel or from your own terminal, so planting one is treated as its own permission. With it off, Gezel can still edit the rest of the file, and removing a script is always allowed.

One check runs on every tool call that executes or fetches, before it runs: Gezel refuses a call that names a cloud metadata service such as `169.254.169.254`, a link-local address, a known data-drop, request-capture or tunnel service, or a Linux namespace tool such as `unshare`. That covers Gezel's own tools, third-party toolsets and the browser, and the tool calls a model returns to another app through Gezel's OpenAI-compatible endpoints. It is a tripwire against a model's bad habits, not a sandbox: it reads the call's text and is easy to get around on purpose. Each refusal appears in History. Third-party MCP servers are also not inside the standalone-script sandbox; because they are unconfined local or remote code, Gezel enables them only under the corresponding Security & compliance setting.

### Mutations need consent

Reading is cheap; changing things is not. Changes made through Gezel-managed tools — project-file writes, git operations, and outward-facing actions — go through the policy and per-project consent you control in Settings. Approving a full-trust package command authorizes that command as a whole; Gezel cannot separately mediate every side effect produced inside it. Git itself stays yours in the default managed workflow: Gezel works in your working copy while you control commits, branches, and pushes. A full-trust command can perform any of those operations if the command you approve includes them.

### Prefer mediated connections to services

Being useful means connecting to services like e-mail or data systems. Wherever possible, Gezel keeps that connection in a named, policy-checked connector or tool and gives the model a file or a narrow operation instead of the raw credential. For example, e-mail can arrive as files in the workspace, and sending uses a reviewed request.

That is the preferred path, not a universal guarantee. An approved full-trust package command or an enabled third-party MCP server can make its own network connections. Provider-native tools follow that provider's security and permission model.

### Leverage the node.js/NPM open source ecosystem

At your direction, Gezel can download additional scripts and tools from NPM (the Node.js package catalog). NPM is widely used, but it is not perfect and has experienced compromises. Gezel installs packages with their install-time scripts disabled, preventing that common supply-chain execution path.

Gezel's ordinary install flow accepts packages from the NPM registry only: a package name plus a version, semver range, or dist-tag. It does not accept a URL, Git repository, local file or directory, workspace reference, package alias, or command-line option in that field. Installs can target only the private package directory of an existing project; project identifiers and the resolved destination are checked before the package manager starts. Alternate package sources would need a separate, explicitly approved feature with their own network and path protections.

What happens later depends on the tool type. A standalone script uses the sandbox described above. A package command runs with your account's authority, only when Run package scripts is on and after explicit approval. A third-party MCP server is unconfined and requires the security posture that permits non-builtin toolsets. Review the package, publisher, requested capabilities, and exact command before granting that authority.

### What History records

Gezel writes durable History events for project and crew changes and for tool completions it can observe. Calls through Gezel's own MCP bridge have the strongest coverage. Provider-native tool loops — such as Claude CLI, Codex CLI, or GitHub Copilot — are recorded when their SDK or event stream exposes enough information, so a missing History entry is not proof that an external provider performed no action.

Copilot's built-in tools are disabled by default in favor of Gezel's scoped MCP tools. The explicit `sandboxCopilot: false` compatibility setting restores those built-ins. Their observed completions may still appear in History, but they do not receive Gezel's MCP scope and action-level sink checks, and their audit detail can be incomplete.

History is a useful, user-owned local activity record. It is not a tamper-evident compliance ledger.
