Security: agent tokens, browser sessions and relay keys Added in 0.9.27
A relay has one person who answers for it: you. Since 0.9.27 everything else that talks to the relay has a credential of its own with less reach. Agents get a token of their own, each browser holds a session instead of the relay token, and paired relays sign in with keys. This page says what each one may do, what you see in Settings → Security, and what is still open. For what a relay exposes at all, see the Security overview.
Who holds what #
| Credential | Who holds it | What it opens |
|---|---|---|
| The relay token | You, in your password manager. The relay keeps only its hash | Everything. You sign a browser in with it and pair relays with it |
| A browser session | Each signed-in browser, in its cookie, with a proof key in the page's storage | What you can do in the web UI |
| An agent token | Every session (OAR_), and the oar command |
The routes agents need, none of yours |
| A relay key | A paired relay, one key per direction | Only the routes relays call each other on |
| A sign-in link | Whoever you give it to, once, for 10 minutes | One new browser session |
What agents may do, and what is yours #
Every session's environment gets OAR_, a token bound to that
session's conversation. The session's worker, its CLI and its tools, and OAR's
own agent tools call the relay with it. Agents no longer find the relay token
anywhere: not in the environment, the command line, config., the logs or
a transcript.
An agent token may:
- read sessions, settings and usage;
- prompt, stop, archive, compact and relaunch sessions, and run its own turns;
- put up its own question and plan cards;
- use
relay_, relay events and schedules;tool - use files, drives, git and uploads, and its own conversation's previews;
- move a session into an existing group or out of one;
- queue a relay restart with a reason, and cancel it.
These are yours alone, and an agent token gets 403 AUTH_:
- answering or dismissing any question card, an ordinary one of another
conversation included, a Safety check,
an approval card or a plan card.
relay_'stool answer_says Only the person can answer questions; ask them in the relay UI;question - the Inbox;
- settings, provider logins, pairings, push devices and shared links;
- deleting a session, and making, renaming or deleting groups;
- a restart now, a plain shutdown, updates and installs;
- the live connection of the web UI.
A session's token acts for that session only: relay_ refuses a call for
another conversation (AUTH_), and an agent starts new
sessions only through relay_'s create_, where your Allow
and the session cap apply. When an agent sets owner_, the relay
ignores it.
Scripts you run on the relay host use the same tokens: inside a session,
Authorization: Bearer $OAR_; outside one,
oar agent- prints a token.
Neither is the relay token. A script that sends no token gets 401 The relay
token is no longer in the config; use OAR_AGENT_TOKEN.
Browser sessions #
Signing in exchanges the relay token once, at the sign-in box or through a sign-in address, for a session of that browser. From then on the browser's cookie holds the session, never the token, and the relay keeps only a hash of it.
- Lifetime. A session lasts 30 days after its last use and 400 days at most. The relay keeps at most 50; a new one pushes out the one used least recently.
- The proof key. Signing in also gives the page a second secret, which it keeps in its own storage and sends with every request. A browser sends the relay's cookie to every port of the relay host, so a dev server an agent runs there receives it when you open that server. Without the proof key the cookie opens nothing but the attachments, generated pictures and media a browser loads by itself (see What this does not close). Clearing the site's data in the browser removes the key: that browser signs in again.
- The key stays with the relay. The page sends the proof key only to the
relay's own address, port included, under
/. A picture an agent puts in a reply from another address, another port of the relay host included, never gets it, and has no 🖍️ in the viewer.api/ - Files by path. A file the page opens by its path (a picture, a video, a
download, a PDF in a new tab) carries a file capability,
k, in its address. The page asks for it with its proof key. It opens that one file, only together with this browser's cookie, for at most 10 minutes, and the page renews it as needed, so a long video goes on. A file link copied out of the page stops working after that. A wrong or expiredkgets403 AUTH_, the same answer whatever the path, so it tells nothing about the files.FILE_ CAPABILITY - Media addresses carry a tag. The media
gallery hands out every address with a
tag
t; a media address without its tag gets404, whoever asks, so a copied cookie cannot walk through the media. The tag does not expire, but whenrelay-is replaced, old media addresses stop working and the gallery hands out new ones.secrets. json - Browsers from before 0.9.27 hold the token in their cookie. That cookie opens nothing any more: when the page starts, it trades the cookie once for a session and its proof key, without the sign-in box. A tab left open from before the update runs the old page and needs one reload.
- Signed out. A browser whose session no longer counts shows This browser was signed out on its sign-in page; a notification you answer from it says Signed out, open OAR.
- Scripts make no sessions. A request with the relay token in an
Authorizationheader acts as you without a session and never adds a browser to the list.
Settings → Security #
Settings → Security is about who can use this relay. Agents and paired relays cannot open it.
- Browsers signed in lists every browser with a session here, this one first and tagged this browser: its name (from the browser and system it reported, until you Rename it), when and how it signed in (the relay token, a sign-in link, the terminal, or carried over from before sessions), when it was last seen and its last address. A browser whose last request reached the relay from its own host through a proxy or tunnel there shows this host (forwarded for …), with the forwarded address in brackets.
- Sign out on a row ends that browser's session at once, closes its live connection and stops its push notifications. Sign out all other browsers keeps only this one; Sign out this browser brings up the sign-in box here. Each asks first.
New sign-in notices #
When a browser signs in with the relay token, a sign-in link or the terminal, every other signed-in browser is told before the sign-in completes:
- one row in the banner under the header, however many there are: New
browser signed in:
, , via … , with Sign it out and Got it, or 3 new browsers signed in (latest: …). Show all opens the list over the conversation, each browser with how and when it signed in and Sign it out; one Got it dismisses them all; - a push notification New browser signed in, also while a device has the app open, to every device that holds a session other than the new one. It has a Sign it out action, and a tap opens Settings → Security. Several within 5 minutes replace one another. The switch is A new browser signed in in Settings → Notifications.
A sign-in that reaches the relay from its own host through a proxy or tunnel there shows this host, with the forwarded address in brackets, never that address alone.
The relay keeps the notices for 7 days. Each browser dismisses them for itself only, so a new session cannot hide its own sign-in from the others. A browser that signs in again sees the notices of the last 7 days again, the ones it had dismissed included. A terminal sign-in's notice stays while that browser is signed in, however many sign-ins follow.
Sign in another device #
You no longer need to type the relay token on a phone.
- On a signed-in browser, open Settings → Security → Sign in another device and press Make a sign-in link.
- Open the link on the other device, or press Show QR code and scan it with that device's camera.
The link (…/) signs one browser in, once, within 10 minutes. The
tab shows how long it has left. Whoever opens it first is signed in, so show
or send it only where you alone can see it. The QR code hides again after a
minute, when you leave the page or close Settings, once the link is used or
expired, and on Hide QR code. A new link ends the previous one, and a
restart of the relay ends it too.
On the relay host, oar url --sign-
prints such a link and its QR code in a terminal, for the address a phone
reaches. The relay makes at most 3 of these in 10 minutes, and a new one
replaces the one before it, which then no longer works; the command says so.
The list of browsers says from the terminal (oar url --sign-in) for a
browser that signed in this way.
Two relays reached under the same host name with different ports
(host:, host:) share one sign-in cookie in a browser and sign each
other out. Give each its own host name.
The relay token #
The relay token is the person's credential: keep it in your password manager.
The relay keeps only its hash, in relay- in the data folder; see
Where secrets live. New tokens
start with oaro1_; a token from an earlier version keeps working.
- It is shown once.
oar setupin a terminal shows a new token once, with a sign-in link and a QR code. Without a terminal (a service, a script, an agent) nothing prints a token, because that output lands in logs agents can read. oar urlprints no token. The relay cannot: it holds only the hash.- Lost it? Sign in another device from a browser that is still signed
in, or replace the token. With no browser signed in, run
oar setup --new-in a terminal on the relay host.token
Generating a new relay token #
Settings → Security → Relay token says whether a token is set, that the relay keeps only its hash, and when it was made or last replaced. Generate new relay token asks first, The current token stops working at once. Signed-in browsers stay signed in; agents keep working., then shows the new token once:
- hidden until you press Show, with Save in password manager (your password manager offers to keep it, under the relay's name), Copy and Copy pairing link;
- when the old token was last used by something other than a browser page, such as a script or an older paired relay, and from which address;
- the paired relays that still call with the old token, each with Open there, which opens that relay's Settings → Relays with Add a relay ready for the pairing link. Relays that sign in with a key keep working and are not listed.
Closing the dialog removes the token from the page. Clear your clipboard after pasting it: clipboard history keeps it.
What changes at once: the old token stops working. Signed-in browsers stay
signed in, agents, their tokens and session workers carry on, and keyed
paired relays keep working. A script that sent the old token needs the new
one, or better OAR_. In a terminal, oar setup --new- does
the same after you type NEW, and restarts the relay.
A relay that 0.9.26 or older started through oar copilot, or one started
with a manual --token, keeps the old token on its supervisor's command line
until it is stopped and started once. Do that before you generate a new token;
see Upgrade notes.
The banner and the Recommended dot #
After the update to 0.9.27 a banner under the header says Your relay token was readable by agents until this version. Generate a new one. Generate new token opens the dialog above; Dismiss hides it, once for the whole relay. While a new token is still recommended after you dismissed the banner, the Security tab keeps a small dot and the token row a Recommended tag, until you replace the token.
The banner also says The relay token was changed outside OAR when the token
changed without the relay doing it: an auth put back into
config., or a changed relay-. Dismiss it if it was you;
otherwise generate a new token. Only your own signed-in page shows it, never
a shared view.
Files the relay never serves #
Whatever the credential, the relay token included, OAR's file routes never
serve or change the relay's own files: relay-, the database
(oar. with its -wal and -shm files, its backups and a backup being
written) and config.. They answer 403 FILE_. The file
browser cannot rename, move or delete them,
nor a folder that holds one, and the media gallery never serves one a message
names. A link or a hard link to one of them is refused too. This keeps them
out of the file routes only: an agent's own shell can still read them (see
What this does not close).
Paired relays #
Paired relays no longer keep each
other's relay token. With 0.9.27 or later on both, pairing uses the token from
the other relay's pairing link once, to exchange keys. From then on each relay
signs in to the other with its own key, which opens only the routes relays
call each other on: never settings, files, pairing, a session's billing, or
answering a card or an ask (403 REMOTE_). Replacing a
relay's token no longer breaks a keyed pairing. Relays paired before switch to
keys by themselves within about a minute once both run 0.9.27.
- Two-way. With Also add this relay there checked, each relay gets a key from the other.
- One way. Unchecked, the token from the link is used for the add alone, in memory, and never kept. The other relay gives this one an inbound-only key and lists it as Inbound only: it never calls this relay, and its Remove revokes the key at once. Here the row says One way.
- The token while you add. With 0.9.27 on both, the token from the link
is held in memory only while the add runs, and never written to the
database once a key works. Only an add that ends without a working key (an
older relay, or a failed exchange) stores it, until a key works. A token
stored and dropped like that can stay readable in the database's free pages
and its
oar.until SQLite reuses them; if that matters to you, replace that relay's token.db- wal - Re-pair in Settings → Relays exchanges keys again in one click. When nothing this relay holds works there any more, or the other relay is older, it opens Add a relay with the address filled in: paste that relay's pairing link and the entry is updated in place.
- Renew key and Revoke key act on one relay. Keys renew by themselves every 30 days. A revoked key stays void until you renew it, or until that relay is added again from this relay's pairing link, which gives it a working key again. Only removing the relay and generating a new relay token lock it out for good.
Verified and claimed origins #
A prompt from a paired relay names the relay whose key signed it in, under the name you gave it here, never what the request says about itself.
- Verified. A prompt that came in on a key. It may do what the limits allow.
- Claimed. A relay without a confirmed key here (an OAR older than 0.9.27, or a key not confirmed yet) still reaches its sessions, but its prompt shows a claimed tag, the agent reads "(unverified)" in its header line, and it opens nothing: no reply access, no hop allowance, no push suppression, no asks or watches. The sending agent is told why. Prompts stored before 0.9.27 read as unverified too.
- Refused claims. A key that claims to be another relay is refused
(
REMOTE_), and so is any other credential that claims to be a relay that has a key (RELAY_ ORIGIN_ MISMATCH REMOTE_). Each refusal is logged and counted on that relay's row, N refused claims since start, and the first one per relay puts a notice in the Inbox.RELAY_ PEER_ KEY_ REQUIRED - A changed identity is held. Once a relay has a key, or this relay holds a key from it, its address and relay id are pinned. If they change, or another relay answers at its address, its keys are revoked, this relay sends it nothing it holds for it (the key it gave this relay, or a token), and nothing new is issued until you Confirm on its row. Setting the address back to the one it was keyed at lifts a hold that only the address change set.
A paired relay's questions are answered on that relay, signed in there. The Inbox shows them read-only with Open there, and for a relay on 0.9.27 with option buttons that open the question there in a small window; see Questions and the Inbox.
Edits to sensitive files #
Claude, Claude API and DeepSeek sessions ask you before an edit to a file that
Claude Code marks as sensitive, because a change there can alter how git, a
shell or a tool behaves: shell startup files such as ., ., and
anything under . or ., among others. Such an edit waits on a
Safety check card in
every relay mode, autopilot included, with the file and the whole change, and
Allow once and Deny. Only you can answer it: an agent token and a
paired relay's key are refused. It never allows more than that one edit, and
an unanswered card leaves the file unchanged. An agent or a paired relay that
watches the session gets only the card's fixed first line and the File:
line, never the change.
Reading such a file, or sending one through the relay, asks nothing, and neither does a command that writes it in a way Claude Code does not flag. The card is a check on the agent's edits, not a sandbox.
What this does not close #
Agent tokens keep agents' tools apart from yours. They are not a sandbox: an agent runs as the same operating-system user as the relay, and that user can still do the following.
- Change the relay's files. An agent can write
relay-,secrets. json config., the database or the relay's code, then queue a restart, and so install a token of its own. The relay only notices it: at its start it compares the token's hash with a copy in its database and reports The relay token was changed outside OAR. An agent that edits both can get past that. From the same file it can also make any session's agent token. The file routes refuse these files, but an agent's shell does not use them.json - Use the terminal paths. The terminal checks of
oar setup --new-andtoken oar url --sign-are friction, not a boundary: an agent can fake a terminal or call the route within oar agent-. A sign-in made this way is announced to every other browser, as above, and shows "via the terminal" in the list of browsers. Sign such a browser out, then replace the token.token - Take a browser's session on the relay host. A browser on the same machine and user keeps its cookie and proof key where that user can read them. Both together are a full session: whoever holds them can do what you can in the web UI, including making a new token. To recover, generate a new relay token, sign in with it, then Sign out all other browsers. A new token alone signs no browser out.
- Read the cookie-only content. Attachments, generated pictures and indexed media that a browser loads by itself, by their id or hash, still open on the cookie alone, without the proof key, so a server on another port of the host that receives your cookie can fetch them. Files by path are not among them: they need the proof key or a file capability. An agent token reads all of these anyway.
- Read the credentials for paired relays that this relay keeps in its database, and a token it stored for one once, which can linger in the database's free pages. A key opens only the relay routes there, and Revoke key on that relay voids it.
- Find an old copy of the token from before 0.9.27: shell history, a
backup, a copied
config., or the command line of a relay's supervisor thatjson oar copilotof an earlier version or a manual--tokenstarted, until that relay is stopped and started once. If agents ran on this relay before, generate a new token after the update. - Stop the relay. A process of the same user can end it, so the
oarcommand's checks before a stop are a convenience, not a protection.
The relay token itself still opens everything, for anyone who has it.