# Tileward in OpenAI Codex

How to add Tileward Context to Codex from `config.toml` and Tileward Governance as a hook that runs before the prompt reaches the model, how managed hooks make it an organisation-wide control, and how the gate fails closed. Both read the same API key.

Page: https://tileward.com/docs/codex/

## Tileward Context: recall instead of resend

Four lines in `~/.codex/config.toml`. The CLI and the IDE extension share that file.

```
# ~/.codex/config.toml
[mcp_servers.tileward_context]
url = "https://context.tileward.com"
bearer_token_env_var = "TILEWARD_API_KEY"
```

- Codex reads the key from the named environment variable rather than storing it in the file, so the config is safe to keep in a dotfiles repo.
- Run `/mcp` in a session to confirm it connected, then ask the model to remember something, start a new thread, and ask it to recall.
- A project-scoped `.codex/config.toml` works only in a project you have marked trusted; otherwise Codex silently ignores project-local config and no server loads. Use the global file if you would rather not mark the project trusted.

## Tileward Governance: a gate, not a system prompt

Codex runs a `UserPromptSubmit` hook before the prompt reaches the model, and a hook that exits 2 stops it, with the reason shown to you. The gate ships as a plugin:

```
codex plugin marketplace add Tileward-com/tileward-codex-marketplace
codex plugin add tileward-guard@tileward
export TILEWARD_API_KEY=tw_live_...
```

- Access to the Codex marketplace is added on request: email [hello@tileward.com](mailto:hello@tileward.com) with the GitHub account that will install it, and the commands above then work as written.
- `/hooks` in a session shows the gate loaded.
- Bind a policy to the key first, in the console under Settings → API keys. A key with no policy refuses nothing.
- Each refusal is recorded against Codex's turn id, so it is findable in the audit next to the prompt that caused it.

## For an organisation: a control, not a guardrail

Codex has a managed-hooks tier, and it is what turns the plugin into a control:

```
# requirements.toml, delivered through managed configuration
allow_managed_hooks_only = true
```

- Per Codex's documentation, that key is honoured only in `requirements.toml`; the same line in `config.toml` does nothing, silently.
- With it set, Codex ignores user, project and session hook configuration and loads managed hooks only, and a managed hook ignores a user's `enabled = false`.
- Managed configuration reaches the machine through MDM or an enterprise configuration bundle, not through a file the user can edit.
- Verify on one machine before rolling it out: a marketplace that cannot be cloned and a hook that cannot start both surface as non-blocking errors, and the prompt runs.

## When Tileward is unreachable

- The prompt is blocked: the hook exits 2 on every failure path, an unreachable Tileward and an unhandled exception included. Codex has no HTTP hook type, so the gate is always a local process.
- Set `TILEWARD_FAIL_OPEN=1` in the environment if you would rather a prompt ran during an outage.
- A hook that exceeds its timeout is killed and the prompt runs, so the script keeps its own timeout under the hook's.
- Exit 2 blocks only when a reason is written to standard error, which the Tileward hook always does.
- Codex runs a hook through a login shell, so keep the shell profile on governed machines silent for non-interactive shells: anything the profile prints on the allow path is handed to the model as extra context.

## Related

- [Connect a client](https://tileward.com/docs/): every other client, and the endpoint table
- [Tileward in Claude Code](https://tileward.com/docs/claude-code/): the same setup for Claude Code
- [Tileward in ChatGPT](https://tileward.com/docs/chatgpt/): Context as a ChatGPT connector
- [Console](https://app.tileward.com): API keys and the policies bound to them