Proxy agents: reaching a database that has no public address
Status (2026-11-19 (IST)): in progress and off by default. A cell serves agents only where its operator turns on
REYANSH_AGENT_RELAY. What exists today: creating, enrolling, approving and deleting an agent, the agent itself, a PostgreSQL source pointed at an agent (saved, tested and run through it), a pipeline that waits while its agent is down (below), with the agent-offline, flapping and duplicated alerts, and the app’s Proxy agents pane (list, approve, delete: below). What does not yet: re-keying, agent images and binaries released for download, and creating an agent from the app (it is created with the API). This page says only what is built.
A proxy agent is a small program you run beside your database: in a container, on a VM or in a Kubernetes pod. It connects out to us on port 443, so you open no inbound port, and our workers reach your database through it. Your configuration decides which databases it may open and which account key it accepts; nothing we send can widen either.
How it is set up
Section titled “How it is set up”sequenceDiagram autonumber actor M as A member of your account participant API as This service's API participant A as Your agent participant R as The relay (this service) M->>API: POST /v1/agents {name} API-->>M: the agent, its enrollment token (shown once, 24 h), its environment M->>A: start it with REYANSH_AGENT_URL, REYANSH_AGENT_ENROLL, REYANSH_AGENT_AUTHORIZED_KEYS, REYANSH_AGENT_ALLOW A->>A: make its own Ed25519 key (it never leaves the agent) and print its SHA256: fingerprint A->>R: connect (TLS, port 443), naming itself by its public key R-->>A: unknown key A->>R: POST /agent/v1/enroll, the token in the Authorization header, its public key R->>R: the token found by its SHA-256 and spent; the key sealed to this agent; pending approval A->>R: connect again; R challenges; A signs a tagged message (never anything an SSH session could sign) R-->>A: welcome: connected, key pending approval (nothing is routed to it yet) M->>API: compare the fingerprint the page shows with the line the agent printed M->>API: POST /v1/agents/{id}/approve {fingerprint} API-->>M: approved (a different key enrolled in between would be 409 agent_key_changed)- The token works once. A second agent using it is refused
token_used, and that refusal is in your agent’s log. The token is shown in the create’s answer only; a replay of that request answersnullin its place. - Approval is a person’s act, never an API key’s: the comparison is what makes a stolen token worthless.
- Ten agents an account. Deleting one burns its key and token and keeps its record.
In the app
Section titled “In the app”Settings › Network and security › Proxy agents (/settings/network/agents) lists the account’s agents, for every
role, a page at a time with Load more: each one’s name and id, whether it is connected (from which address and
since when), waiting for its first start (with when its token stops being valid, or that it expired), not
connected, or deleted, its version, and the allow list it reported. The list is read when you open the pane, after
each Approve or Delete, and when you press Check again; never on a timer.
- Approve this key, on an agent whose key is waiting: the question shows the fingerprint the pane read, to compare
with the line the agent printed, and approving sends exactly that fingerprint. If another key is waiting by then
(
409 agent_key_changed), the pane reads the agents again and says so: compare the fingerprint shown now before you approve. - Delete, on any agent not deleted: the question says what is burned. If a source still reaches its database through it, nothing is deleted and the sources are named, each a link.
- An agent is created with the API (
POST /v1/agents, above): its one-time token is never shown by the app.
Pointing a source at an agent
Section titled “Pointing a source at an agent”A PostgreSQL source saved field by field takes connection.connect {"method": "agent", "agent": {"id": "agt_...", "key_id": "ssh_..."}}: the agent, and the account SSH key (GET /v1/ssh-keys) listed in the agent’s
REYANSH_AGENT_AUTHORIZED_KEYS. The connection’s host and port are the database as your network sees it
(db.internal:5432), dialled by the agent and only when its allow list names them; nothing on our side judges that
name.
- The connection test asks the relay first: an agent that is not connected answers
422 agent_offline, one whose key nobody has approvedagent_awaiting_approval, one deleted (or of another account)agent_deleted. Nothing is dialled in any of those. - While a source uses an agent, deleting the agent is
409 agent_in_useand retiring its key409 ssh_key_in_use, each naming the sources. Edit the source first. - Where the region does not serve agents, a source cannot be saved through one (
422 method_not_offered), and a pipeline whose source already uses one is stopped and told; it starts again by itself once agents are back.
How a worker reaches your database
Section titled “How a worker reaches your database”sequenceDiagram autonumber participant W as A worker (this service) participant R as The relay participant A as Your agent participant D as Your database W->>R: the spawn's ticket, over a local socket R->>R: the ticket is this spawn's, its account's agent, connected and approved R->>A: open data connection N (over the agent's own outbound connection) A->>R: a second outbound connection for N, signed R->>R: pair the two; from here the relay copies bytes and reads none W->>A: SSH: the agent's key pinned, our account key authenticates W->>A: a channel to db.internal:5432 A->>A: on your allow list? resolve once, dial only the checked addresses A->>D: TCP W->>D: TLS with your database and the PostgreSQL protocol, end to end inside the channelWhen the agent is down
Section titled “When the agent is down”sequenceDiagram autonumber participant S as The supervisor (this service) participant R as The relay participant P as The pipeline's state S->>R: may this spawn reach agent agt_...? (Ready) R-->>S: not connected, or its key not approved S->>P: awaiting_connection + a pipeline_awaiting_connection row carrying the restart streak (one transaction) Note over P: health `awaiting_connection`, status `running`; the feed shows "Waiting for the proxy agent" loop every reconcile tick, and at once whenever an agent connects S->>R: is the agent ready now? R-->>S: not yet end R-->>S: ready (connected, key approved) S->>S: start the pipeline again: a fresh ticket bound to the new worker's process S->>P: resume the streak from the waiting row, the wait cut out of its 14-day clock- A waiting pipeline runs no worker, so it is metered nothing and charged nothing; it resumes from where it stopped. A run that was still open when the wait began (its worker stopped without finishing, because the agent dropped) is ended there as a failed run, which is free: whatever of it was already charged is refunded.
- An agent connecting wakes the reconciler, so its waiting pipelines start within seconds.
- A wait is not a restart. The pipeline’s count of restarts and its 14 days of automatic restarts carry on across the wait from where they stood, and the days spent waiting are not counted in the 14: an agent that is offline for a weekend does not use up a pipeline’s restarts, and one that keeps dropping still reaches “retrying”.
- After 5 minutes your account is told once per agent (
source_agent_offline), naming how many pipelines wait. When a run measured a waiting pipeline’s replication slot before the wait, the message says how much log the database was keeping for it then; when none was measured it states no size.
The slot watch reads your replication slot through the agent
Section titled “The slot watch reads your replication slot through the agent”While a pipeline does not run (paused, given up, waiting), our slot watch reads its replication slot about every 10 minutes so the alerts can say how much log your database is keeping for it. For a database reached through an agent, that read goes through the agent exactly as a pipeline’s worker does:
- the read is one
worker --checkwith the slot scope: one connection and one read-only query ofpg_replication_slots. Nothing is created, advanced or dropped on your database; - it gets its own relay ticket, bound to that one process and ended when it finishes, and it pins the agent’s approved key;
- the database’s host is never looked up on our side: the agent opens the connection only if its allow list admits the target;
- if the agent is not connected, or its key is not approved, the read is not attempted; if it is connected but
does not answer our relay’s request for the read’s connection, your database is not tried either (the agent
connects to the database only inside that connection). Either way the alert (
source_log_unmeasured) then saysagent_offline, never that we could not reach your database, and keeps the last measurement with its time. The slot is read again once the agent is connected and answering; - where proxy agents are switched off, the read is not attempted and the reason is
agent_preview.
If the agent refuses the connection because the database is not on its allow list, the reason is
agent_forwarding_refused, and the message names the agent’s allow list (REYANSH_AGENT_ALLOW): add the database’s
host and port, exactly as the source’s connection names them. The agent refuses before it connects to anything, so
your database was not tried. (Until 2026-11-17 this was reported as rejected, the word for your database turning the
read down; rejected now means your database’s own refusal, or the agent refusing our key or presenting a key we did not approve.)
The agent’s configuration (all from its environment)
Section titled “The agent’s configuration (all from its environment)”| Variable | What it is |
|---|---|
REYANSH_AGENT_URL |
this service’s address, https:// and the host, no path |
REYANSH_AGENT_ENROLL |
the enrollment token; read only to enroll; logged only as rae_**** and four characters |
REYANSH_AGENT_AUTHORIZED_KEYS |
the account key line(s) the agent accepts (GET /v1/ssh-keys), one per line; a line with options is refused |
REYANSH_AGENT_ALLOW |
the targets it may open: db.internal:5432 (a name), 10.0.4.17:5432 (an address), 10.0.4.0/24:5432 (a range), [2001:db8::1]:5432. Empty refuses every connection. A /0 range or a port range is refused at start |
REYANSH_AGENT_STATE |
the directory it keeps its key in (mode 0600) |
REYANSH_AGENT_KEY_FILE |
instead, a key it only reads (a Kubernetes Secret mounted read-only, made with ssh-keygen -t ed25519) |
REYANSH_AGENT_CA_FILE |
an extra certificate authority, for a proxy that inspects TLS |
HTTPS_PROXY |
honoured |
Retiring or replacing an agent
Section titled “Retiring or replacing an agent”Delete the agent (Delete in the app’s Proxy agents pane, or DELETE /v1/agents/{id}): its key and token are
burned at once, its connection and every
session through it are closed, and its next connection is told agent_deleted, so it stops. Then wipe its
state directory (REYANSH_AGENT_STATE), or replace the key Secret it reads (REYANSH_AGENT_KEY_FILE), before
that machine runs an agent again: a new agent must enroll a NEW key, because a key is one agent’s.
A name on the allow list trusts your DNS
Section titled “A name on the allow list trusts your DNS”db.internal:5432 allows every address your resolver answers for that name, at the moment the agent asks. If
someone can change that name’s answer inside your network, they can point the agent elsewhere on that port. List
an address or a range (10.0.4.17:5432, 10.0.4.0/24:5432) instead where your DNS is not under your control.
What the agent does, and refuses
Section titled “What the agent does, and refuses”- It serves SSH
direct-tcpipchannels and nothing else: no shell, no command, no remote forward. - A target not on its list is refused with
agent: target_not_allowed. A name is resolved once; only the answers on the list are dialled, so a name that answers differently a second later cannot move a connection. - It pings us every 20 s, reconnects with a backoff from 1 to 30 s after a drop, and never updates itself.
- It logs one JSON line per event: its start (with its fingerprint), each connection and channel, each refusal. Never a payload, a key or the token.