·
+ · · ·
· · · +
· · · ·@ ···
· ·· @@@@@@@@ ·
· ··@@@@@@@@@ · ·
----------- · + @@@@@@@@@··
·· ·· ··------------------- ·@----------- ·
·· · ·· · ·· ·· · · · · ------\ · + + -// · ···· ·-----------------------
·· · · · · · · · ·· ··\\- · ------- ···· · · ·· · · · · --------------
· · · · ·· ·· · ·· · ·------- ----- + ---- ----------------· · ·· · ·· ··· ·· · · · · · · -------------------------
·· ·· · ·· · · · ···· ·· · ···--------------- · ------------- · ----------------- · · ··· ·· ··· · ·· · · ·· · · ·· · · · · · ·· · · · · · ··· · · ·· ··· ·
·· ·· · ····· ·· ·· ·----·· ··· ·· · · · ·· · · · · · ··· ·· ··· · · · · · · · · · · ···· ·· · · · ··· ·· · · · ·· · · · ····· ···-----\\
··· · · · ··· -----::::--------· ···· ---------\·· ··· · · ··· · · · --------- · · ---- ·· · ·· · · ··· · · --------\· ·· ··· · · //-==-:--:
· -----------------------::-:=:::--:-::------------------=-==-:=::-\\· · ·· ·· ·-----\· ----------::---::=------::-\\\ · · · · · · --------------:------:---- · · · -///=--:::-:-:
----:-:-:--=--:--:---::-=-:--==::=:-=:-----:::::---::::-:::--:--::::-\--------· -----:-----\----==::=-::--:=:=-:=:-=:::----=:=\\\ --/--:--::-=-===:::-::::-::::--\--------------::---::-:::-:
:-:---::-:-:--:=:-=-----:-=:-:=::-:=:----:::=-::--=::::::---:::-=---:::::-:-::---=:--::-:::--=-::-:-::-:--=-::-=--:=-::---=:-:::-:\---·· ///-==:--:-------:-::---::::=-::=:-:-:=:-::=:=---:::-:==:::::-
-::--=--:--=-:::----=-====:=:--:-:-==::-==:=---=-=::=--=-:=-===:--=-==:-=---:-:::::-:-----:-::=-::--=::--==-:-:=---=:-:-:::--::--::=-------:=::::-=:-:-:-:-:=:::-::-=::-:-:-::--:::-::--==:-::==::::-:-:
____\------:::==:-=:--:=:--:=--:-=:-=--:___/__\\--_:::==::____=/_\\=-----=--::/______\=::-=:::=:::==:________::-:-:-:::--==:-===--::--:--:--:-::--:::=-::=-=-:=:=:--::-:-=-::::---=:-:=:-::-:::---=----:
#*+#*\______\-=-:--==--:==:-:::-:-______+++++**=__+_______#=**_**+#\\-----:://**+=*##+\______________++***+*+_\\-:----:::/______________________________________________::-::::______\\-:-=:==--==---:--
**#+**++#*+**\\-::-==:-=::=-:--///*#**+=+#**+#+#*+++*++++*+#*#**#++**\\_:://+#*##**#*#*#+++*+*++++*+=+=+*##+*++*\\-:::://#*++######=+#+#***+***#=+**+++*++++++*****#*+**_____/_+***#+*=\\:=--:-::-::---:
**#*+*++**+*++=\____:____-___//+*+++++#+##**#%###*#*#*+*+*+#+*******++*+__+#*+***##+*##***#**+*#*#*##****##*#*+##+\____+*+*#+#+++*#+**+*+*+#++*#+**##++*#*#***++**+***+*#*+**++++#*+*+*++\\\--/_______\:
#*%*##%*+##%#**+#+=*_++++_+=++++*#+#+**#**+##%%#%##%**#**+##**#*#%%+++#*+##+##*#%###%%#%##*#*%**#+#****+#*######+*+++***#***###*###+*+***#*+#**##*%#*##+*+####++*%*#**#*##+*##+*##*###*+#+#+__*****+*#=_
#%#%#**%##*%**+*+++#******+**#+#*#*%%**##%###%%#*###**%#%%%#%***%%**###*#++#%*##*@#%#*#%###*%*%#%#####%%%*#*####*%##*#*++##*#%#%###*#%##%**#*##**##%*#*%*#**%***##%%**#***##+**%%%*#%#%**##*#**++#**##**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.
- Author
- Relay Engineering
- Published
- Updated
- Reading time
- 3 min
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 or Supabase guides to create one.
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:
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:
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:
## 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:
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.
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:
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:
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:
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.