Remote relays and pairing Added in 0.9.4

If you run more than one OAR relay, for example one on your workstation and one on a server, you can pair them. An agent in any conversation can then list and read the sessions of the other relay, prompt one, start a new one, wait for the reply and bring a question the other agent asked back to you. You decide which relays an agent may touch, and how far.

The agents use the relay_tool tool for this. Its actions are described in the reference; this page is about what you set up and what you see. For sessions on the same relay, see Agent sessions.

Pairing #

1. Open Settings → Relays.
2. Under Add a relay, paste the other relay's web address: the address you open it with in a browser.
3. Leave Also add this relay there checked if the other relay should list this one too. Press Add.

OAR checks the address with this relay's own token, or with the ?token= the pasted link carries. Only if that fails does a field Token of the other relay appear; paste the other relay's token there and press Add again. You can also open the field first with Use a different token. The token is sent once and is not kept in the page.

The relay reads the other relay's name from the other relay. With Also add this relay there checked, it then introduces itself using its Public address, so the pairing works in both directions. The status line under the form tells you how it went, for example that the relay was added and added this one too, or that adding it there failed and why. The relay on the other side shows the entry with a Paired automatically tag. That relay keeps the entry even when it cannot reach the address yet.

This relay's name and address #

Under Settings → Relays, the top of the tab shows this relay's name and the fields other relays need:

• Relay name is set under General; the Relays tab only shows it. When it is empty, the machine's host name is used.
• Public address is how other relays reach this one: the address you open this relay at from another device. It is needed for Also add this relay there. If it is empty when you add a relay, OAR stores the address of the page you pair from as the public address, unless that page is on a loopback address such as localhost; then the pairing back fails until you enter one.
• Accept prompts from other relays' agents is described below.

Removing a pairing #

Remove on a relay's row ends this relay's side: agents here can no longer work on that relay. It does not undo the other side:

• The other relay keeps its own entry for this one. Remove it there too to unpair both ways.
• If the pairing handed over this relay's token, the other relay still holds it. Removing the entry does not revoke it. Rotate this relay's token to lock the other relay out.

When the tokens differ #

If both relays use the same token, nothing is handed over. If the other relay needs a different token to call this one back, the introduction carries this relay's token, and the other relay's agents can then work here. A relay that is already in the other relay's list keeps the address and token stored for it; change those in its own settings.

Online or offline #

Each paired relay shows a dot and a line with its host name, its OAR version (when known) and when it was last seen, or not reached yet. For a dot other than Online or Not checked yet, the reason is shown under the name. This relay checks every paired relay once a minute. Check checks one now. Open opens the relay in a new tab.

Mention a relay to unlock it #

Agents can always see which relays are paired. But a paired relay is locked in a conversation until you open it, so that an agent does not reach into a relay you did not mean. Two things open it:

• You mention it in one of your messages. Type @ and pick the relay from the list, or write its name or its host name. A host name that is an IP address or localhost never counts, and a relay whose name is an address only counts with a leading @.
• An agent on that relay writes to the conversation. The relay is then open to the conversation, within what Agents may allows, so the agent that was asked can answer, ask back or report later.

Once unlocked, a relay stays open for the rest of the conversation. A prompt from an agent never unlocks any other relay. A locked relay refuses everything except listing the relays; the agent is told to ask you to mention it. This relay itself needs no mention.

What agents may do #

Each paired relay has an Agents may menu in its row. New pairings start at Full.

The reference lists the actions per level.

Accept prompts from other relays' agents #

This switch is on this relay and decides what agents from other relays may do here. It is on by default. When you turn it off, their agents can still list and read sessions and background commands' output here, wait for replies, and see this relay's providers and plan usage. Everything that changes something is refused: sending prompts, starting sessions, answering questions, stopping turns, archiving and unarchiving, and watching sessions here. The refusal they get reads: This relay does not accept prompts from other relays' agents.

The switch is about agents of other relays only. Agents of this relay that work on sessions here are governed by the setting Agents may start and use sessions on this relay, not by this switch.

It is a separate decision from Agents may: that one limits your agents on another relay, this one limits theirs on yours.

Limits that protect you #

• Two relays, not three. A prompt that has already crossed two relays is not passed on to a third unless you unlocked that relay yourself with a mention. The relay the prompt came from can always be answered. Reading and waiting are never limited this way.
• 30 prompts, then you are asked. When the agent of a conversation has sent 30 prompts to other agents without a message from you in between, the next one asks you on a card, in any relay mode. Sending a prompt, starting a session and answering a question each count, and so do those to sessions on this relay. Allow starts the count again.
• Approval in ask and plan. In these relay modes every action that changes something on another relay asks you first on a question card: prompting, starting a session, answering a question, stopping and archiving.
• The agent on the other side is told. The prompt it receives starts with a line saying that another agent is talking to it, naming the sending relay and session.
• Your accounts stay put. A session started on another relay uses that relay's provider accounts, not yours here.

What you see #

On the relay that receives an agent's prompt:

• ↗ from … on the message: a badge naming the sending relay, its session and the agent's model. It links back to the source session.
• ↗ name in the conversation list, on a session that an agent from the relay name created.
• No "reply ready" notification for a turn an agent started. The agent that waits for the reply reports back to its user itself. Notifications for questions still arrive.

On the relay where the agent runs, the call shows as an activity line with a 🛰️, and a question from the remote agent comes as a card in your conversation. Longer waits are set by Longest wait per tool call under Agent sessions; that slider applies to paired relays too.

An agent can also ask to be woken when something happens in sessions on a paired relay. That is called watching sessions; the tool side is in the reference.

Addresses and tokens #

• Remote addresses must use https://. An address pasted without a scheme is read as https://. A pasted web-client link works; OAR reduces it to the relay's base address.
• Plain http:// is accepted only for loopback addresses (an SSH port forward, for example) and private network ranges: 10.x.x.x, 172.16.x.x to 172.31.x.x, 192.168.x.x, 100.64.x.x to 100.127.x.x and the IPv6 fc00::/7 range. A relay reached this way is marked with a warning. On a private range it says the token crosses your network unencrypted.
• A ?token= in a pasted link is used for the pairing and is not kept as part of the stored address.
• The other relay's token is stored on this relay. It never appears in the settings list or in the web page. The tool never gives an agent a token: its calls go through this relay, which adds it. An agent runs as the relay's user, though, and could read what is stored on disk: see Secrets.

If it does not work #

All error codes are listed under Errors.