# How to use Codex agents with Relay

> Let OpenAI Codex query your databases through Relay: Relay skills in ~/.agents/skills, AGENTS.md, the sandbox network setting and approvals for writes.

- URL: https://blog.userelay.sh/guides/how-to-use-codex-agents-with-relay
- Author: Relay Engineering
- Published: 2026-11-10
- Updated: 2026-11-10
- Tags: codex, ai agents, relay cli, skills

## Short answer

Install the Relay skills with relay skills add --agent codex, run relay connect for the database, and describe the local port in AGENTS.md. If the Codex sandbox blocks the connection, allow network access for workspace-write. Codex never sees a password, and Relay checks, masks and records every statement it sends.


Codex works well with databases when it can run `psql` or `mysql` and read the results. What it should not have is a password. With Relay, Codex connects to a local port, and the credential, the policies and the audit log stay on the Relay side. This guide covers the Codex CLI and the IDE extension running on your machine.

## What do I need before I start?

- The Codex CLI or IDE extension, signed in.
- The Relay CLI, signed in, with a connection to open. The examples use `pg-prod`; see the [PlanetScale](/guides/how-to-use-planetscale-with-relay) or [Supabase](/guides/how-to-use-supabase-with-relay) guides to create one.

```bash
brew install relay-sh/tap/relay
relay login
relay connections list
```

## How do I teach Codex to use Relay?

Install the Relay skills for Codex:

```bash
relay skills add --agent codex
relay skills list
```

They go to `~/.agents/skills`. Other agents that read the same directory share that copy, so `relay skills list` may show them installed for more than Codex. To ship the skills with a repository, use `--project`, which writes to `.agents/skills` in the current project. Restart Codex to load them.

## How does Codex reach the database?

Open the connection yourself:

```bash
relay connect pg-prod
```

```
  pg-prod (postgres)
  Listening:  127.0.0.1:5432
  ...
  Connect with:
    psql "postgresql://:noop@127.0.0.1:5432"
```

Codex reads `AGENTS.md` at the root of the repository. Describe the database there, once:

```markdown
## Database
- Reach the database only through Relay at postgresql://:noop@127.0.0.1:5432.
  The credentials are placeholders. Do not look for a password or a DATABASE_URL.
- Read-only by default. If a statement is blocked or held for approval by Relay,
  stop and report the message.
- Prefer `relay runbook list -c pg-prod` and `relay runbook run ... --json`
  when a runbook covers the task.
```

Every statement Codex sends goes through your Relay session: your workspace's policies, the connection's masking and the audit log all apply, under your account. Closing `relay connect` ends Codex's access.

## Why can't Codex connect from inside the sandbox?

In its default `workspace-write` mode, Codex runs commands with network access off, and that can include TCP connections to `127.0.0.1`. If `psql` works in your terminal but fails inside Codex with a connection error, allow network access for that mode in `~/.codex/config.toml`:

```toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true
```

This setting is about Codex's sandbox, not about the database. Relay still decides what each statement may do once it reaches the port.

> **Two layers.** Codex's sandbox and approvals protect your machine. Relay's policies, approvals and masking protect your data. Configure both, and give the Relay connection a read-only database user when Codex only needs to read.

## How do runbooks fit an agent like Codex?

Runbooks are reviewed statements from your workspace's Git repository. Parameters are bound by the driver, never spliced into SQL, so an agent can fill in values but cannot change the statement:

```bash
relay runbook list -c pg-prod
relay runbook show find_customer
relay runbook run find_customer -c pg-prod -p customer_id=42 --json
```

The `--json` output is one JSON document on stdout, with progress and warnings on stderr, which keeps it easy for Codex to parse.

## What happens when Codex tries a risky write?

A statement your policy holds for approval does not run on its own. A person decides:

```bash
relay approvals list --connection pg-prod
relay approvals get <id>
relay approvals approve <id> --reason "CHG-1234"   # or: relay approvals deny <id>
```

Approval lets that statement run once. Unanswered requests expire.

## Can I use it with codex exec?

Yes. `codex exec` runs Codex non-interactively, which suits scripts and scheduled jobs. Keep `relay connect` running alongside it, or, in CI, authenticate the Relay CLI with an API key:

```bash
export RELAY_TOKEN=...          # from your CI secret store
export RELAY_SERVER=api.userelay.sh:443
relay connect pg-prod &
codex exec "Summarise yesterday's failed payments from the payments table"
```

With `RELAY_TOKEN` set, the CLI ignores saved profiles and refuses to guess the server, so the key is only ever sent where you pointed it.

## Questions

### Does this work for Codex cloud tasks?

Not as written. A cloud task runs in a remote container, so it cannot reach the port `relay connect` opened on your machine. This guide covers the Codex CLI and IDE extension running locally.

### Is turning on network access in the sandbox safe?

It widens what Codex's commands can reach, beyond the database. Keep `approval_policy = "on-request"` so Codex still asks before commands that need more than the sandbox allows, and keep it off for projects that do not need a database.

### Where do the Relay skills go for Codex?

`relay skills add --agent codex` writes them to `~/.agents/skills`, a directory other agents share, so they get a single copy. With `--project` they go to the repository's `.agents/skills` instead.