> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace trust

> Why o4 ignores a project's hooks and MCP servers until you trust it.

A repository can carry o4 configuration that runs code on your machine: hooks, MCP servers, plugins, and settings that change how much o4 asks you. So o4 ignores that configuration in a directory until you mark it as trusted. Trust a workspace after you have reviewed its `.o4` folder and `.o4.md`, usually once per repository you work in.

## Trust a workspace

Run `o4 trust` from the workspace's root:

```bash theme={null}
cd ~/code/my-project
o4 trust
```

```text theme={null}
Trusted workspace: /Users/you/code/my-project
Project hooks and MCP servers from this directory will now run.
```

Trust covers the directory and everything below it, so trusting a repository's root also trusts its subdirectories. o4 resolves symlinks before it records or checks the path.

To revoke trust, run `o4 untrust` from the same directory:

```bash theme={null}
o4 untrust
```

`o4 untrust` removes only the exact directory you run it in. If you trusted a parent directory, subdirectories stay trusted until you untrust that parent.

## What trust controls

Until a workspace is trusted, o4 ignores these project files and folders:

| Project file or folder | What it can do |
| - | - |
| `.o4/config.toml` and `.o4/config.local.toml` | Hooks, permission rules, sandbox settings, the default model, keybindings, and every other [config key](/reference/configuration). o4 doesn't open these files at all. |
| Hooks in `.o4.md` | Hooks written in `hooks` code blocks. The rest of `.o4.md` is still read as [project instructions](/configuration/project-instructions). |
| `.o4/.mcp.json` | Project [MCP servers](/extend/mcp). |
| `.o4/settings.json` | Project overrides of your settings, including the permission default, formatter and language-server commands. |
| `.o4/plugins/` | Project [plugins](/extend/plugins) and everything they bundle: commands, skills, sub-agents, tools and MCP servers. |
| `.o4/skills/` | Project [skills](/extend/skills). |
| `.o4/agents/` | Project sub-agent definitions. |
| `.o4/harness.toml` | Project guides and the check commands [campaigns](/guides/campaigns) run. See [Harness guides and sensors](/extend/harness). |
| The `[watch]` command | The command [`o4 watch`](/guides/watch) runs, taken from `.o4/config.toml`. |

In an untrusted workspace, o4 also keeps your global memory (`~/.o4/memory/global.db`) out of the session. Project memory still works.

Trust also gates these actions in an untrusted workspace:

* `o4 mcp add <name>` refuses to add a project MCP server. Pass `--global` to add it to your own config instead.
* `o4 plugin install --project` refuses to install a project plugin.
* In the agents dashboard, `n` starts a new session only in a trusted directory. Otherwise it shows "`<dir>` is not a trusted workspace".

Project instructions (`AGENTS.md`, `CLAUDE.md`, `.o4.md` and `.o4/instructions.md`) are read whether or not the workspace is trusted. They are text for the model and can't run code by themselves.

When o4 skips project configuration, it logs a warning to `~/.o4/o4.log`: "Ignored project configuration because this workspace is not trusted." The TUI shows startup suggestions when it skips project plugins or MCP servers.

## Trust from the TUI

If a project has MCP servers in `.o4/.mcp.json` and the workspace isn't trusted, o4 shows a suggestion at startup: "N project MCP servers skipped in `<path>`: workspace is untrusted. Trust and load?" Accepting it trusts the workspace, as `o4 trust` does, and starts the project's MCP servers without a restart. The rest of the project configuration, such as hooks, permission rules and settings, loads from the next session.

If a project has a `.o4/plugins/` folder, the startup suggestion tells you the plugins were ignored and to run `o4 trust` after you've reviewed the checkout.

## Where trust is recorded

o4 records trusted directories in `~/.o4/trusted_workspaces.json`:

```json theme={null}
{
  "trusted": [
    "/Users/you/code/my-project"
  ],
  "airlock_suggestion_seen": []
}
```

The `airlock_suggestion_seen` list records workspaces where o4 has already suggested the `airlock` sandbox tier (see [Sandbox](/safety/sandbox#change-the-tier)).

Commands in a sandboxed tier can't read or change this file. If o4 can't read it, for example because it is malformed or a symlink, every workspace is treated as untrusted.

## Skip trust for one run

Two options skip trust without recording anything. Both are meant for automation that already vets the repository, such as CI jobs.

`O4_TRUST_WORKSPACE=1` treats the current workspace as trusted for that process:

```bash theme={null}
O4_TRUST_WORKSPACE=1 o4 --print -p "Run the test suite"
```

`--dangerously-bypass-hook-trust` is narrower. It loads only the hooks from `.o4/config.toml`, `.o4/config.local.toml` and `.o4.md` for this run. Every other project setting, the project MCP servers, and the rest of the list above stay ignored:

```bash theme={null}
o4 --dangerously-bypass-hook-trust --print -p "Update the changelog"
```

<Warning>
  Hooks run shell commands with your permissions. Skipping trust in a repository you haven't reviewed lets that repository run code on your machine as soon as o4 starts.
</Warning>