# How to use Claude Code agents with Relay > Give Claude Code database access without a connection string: install the Relay skills, open a local port, scope a subagent and keep a person on writes. - URL: https://blog.userelay.sh/guides/how-to-use-claude-code-agents-with-relay - Author: Relay Engineering - Published: 2026-11-10 - Updated: 2026-11-10 - Tags: claude code, ai agents, relay cli, skills ## Short answer Install the Relay skills with relay skills add --agent claude-code, open the database with relay connect, and point Claude Code at the local port it prints. Claude never holds a password. Relay checks, masks and logs each statement, and risky writes wait for a person to approve them. Claude Code is good at databases: it reads schemas, writes queries, checks its own results. The usual way to let it do that is a `DATABASE_URL` in `.env`, which puts a long-lived password wherever Claude's context goes. Relay replaces the string with a local port. This guide sets that up, teaches Claude how to use Relay with the official skills, and scopes a subagent to read-only work. ## What do I need before I start? - Claude Code, installed and signed in. - The Relay CLI, signed in to a workspace that already has a connection. The examples use one called `pg-prod`; the [PlanetScale](/guides/how-to-use-planetscale-with-relay) and [Supabase](/guides/how-to-use-supabase-with-relay) guides show how to create one. ```bash brew install relay-sh/tap/relay relay login relay connections list ``` ## How do I teach Claude Code to use Relay? Install the Relay skills. `relay skills` finds the coding agents on your machine and writes the skills where each one reads them; for Claude Code that is `~/.claude/skills`: ```bash relay skills add --agent claude-code relay skills list ``` To share them with everyone who clones a repository, install them into the project instead. That writes to `.claude/skills`, which you can commit: ```bash relay skills add --agent claude-code --project ``` Start a new Claude Code session to load them. `relay skills add` again updates them; `relay skills remove` deletes only what it installed. ## How does Claude reach the database? Open the connection in a terminal you control: ```bash relay connect pg-prod ``` ``` pg-prod (postgres) Listening: 127.0.0.1:5432 ... Connect with: psql "postgresql://:noop@127.0.0.1:5432" ``` Then tell Claude where it is. A few lines in the project's `CLAUDE.md` save repeating it every session: ```markdown ## Database - The database is reachable only through Relay at postgresql://:noop@127.0.0.1:5432. The credentials are placeholders; never ask for or look for a real password. - If the connection is refused, ask me to run `relay connect pg-prod`. - Prefer `relay runbook list -c pg-prod` for anything a runbook already covers. ``` The session belongs to you. Everything Claude runs is checked against your workspace's policies, masked by the connection's rules and recorded in the audit log against your account. When you press `Ctrl+C`, the port closes and Claude's access ends with it. ## How do I scope a subagent to read-only work? Claude Code subagents live in `.claude/agents/`, each a Markdown file with its own instructions and tool list. A database analyst that can read, query and report, but not edit files, looks like this: ```markdown --- name: db-analyst description: Answers questions about production data. Use for read-only SQL through the Relay port. tools: Bash, Read, Grep --- You query the database only through psql at postgresql://:noop@127.0.0.1:5432. Run SELECT statements only. Show the SQL you ran next to each answer. If a query is blocked or held by Relay, report the message as is and stop. ``` Pair it with permission rules in `.claude/settings.json`, so the commands it needs run without a prompt and the ones it must not run are refused: ```json { "permissions": { "allow": ["Bash(psql:*)", "Bash(relay status)", "Bash(relay runbook list:*)", "Bash(relay runbook show:*)"], "deny": ["Bash(relay connections delete:*)", "Bash(relay db delete:*)"] } } ``` Claude Code's permissions decide which commands run. Relay decides what those commands may do to the database. Keep both: the first protects your machine, the second protects your data. > **Defence in depth.** Use a read-only database user for the connection Claude reads through. Relay policies and masking then sit on top of a role that cannot write in the first place. ## How do runbooks help an agent? A runbook is a reviewed statement from your workspace's Git repository, bound to the connections it may run on, with parameters bound by the driver rather than spliced into SQL. For an agent that is the safest kind of query: it picks a runbook and fills in values, and cannot change the statement. ```bash relay runbook list -c pg-prod relay runbook show find_customer relay runbook run find_customer -c pg-prod --param customer_id=42 --json ``` `--json` gives Claude a result it can parse. `relay runbook run` is pinned to the version shown by `show`; add `--version` to fail instead of running a newer one. ## What happens when Claude tries a risky write? If your policy holds a statement for approval, it does not run on its own. It waits for a decision from someone allowed to make one. You, or whoever reviews changes, decide from a terminal: ```bash relay approvals list relay approvals get relay approvals approve --reason "CHG-1234" ``` `get` shows the full statement before you decide. Approval lets that statement run once; `relay approvals deny ` rejects it, a request nobody answers expires, and the requester can `cancel` their own while it waits. `relay approvals list --status all` shows the history. ## Can I run this in CI? Yes, with an API key in `RELAY_TOKEN` instead of a browser login. The CLI then ignores saved profiles and requires the server to be named, so a key is never sent somewhere by default: ```bash export RELAY_TOKEN=... # from your CI secret store export RELAY_SERVER=api.userelay.sh:443 relay runbook run nightly_report -c pg-prod --json ``` Runs execute as the user who created the key, with that user's access and masking. ## Questions ### Does Claude Code see the database password? No. Claude connects to `127.0.0.1` with placeholder credentials the proxy ignores. Relay keeps the real credential encrypted, or resolves it from your secret store, and uses it only on the upstream side. ### Can Claude Code open the tunnel itself? It can run `relay connect` as a background command, but it is simpler and easier to reason about if you run it in your own terminal. The session then lasts exactly as long as you keep it open. ### What happens when Claude tries a write my policy holds? The statement waits for a decision instead of running. Someone with the right role approves or denies it, for example with `relay approvals approve --reason CHG-1234`. Approval lets that exact statement run once.