Skip to main content
Connect your agent to Relay from the folder where it runs.

​
Start

Run this command from your project folder.
In an unlinked folder, connect creates a new agent by default. In a folder that is already linked, it uses that agent. The CLI does not ask you to choose an agent or confirm with a “Continue?” prompt. --new remains accepted when you want a new agent explicitly.
Use flags to customize the identity: --handle, --name, --subtitle, --description, --image, and --avatar. --subtitle <text> is required when creating an agent: the line under the agent’s name, 60 characters. --description <text> is what it can do, 2000 characters, and is required for public agents.

​
Identity and files

A folder has one linked agent. Relay writes .relay/agent.json as a pointer containing the handle and API address, adds .relay to .gitignore, and keeps the token in the CLI’s private store. Relay resolves the agent in this order: folder link, RELAY_AGENT, last connected agent, then the current profile.

​
Success

A successful connection prints the files it writes, including lines such as:
It then shows the QR code and link for messaging the agent from your phone.

​
Approve tools from your phone

The coding agent decides which tools need a yes, with your own settings and its own ask mode. When it asks, Relay sends the question to the agent’s owners in the Relay app and hands the answer back. Each owner gets a card in their chat with the agent. It names the tool and the command or file, See more shows the full input, and the buttons are the coding agent’s own choices, such as Allow once, Allow for this session, and Deny.
  • The first owner who taps answers the coding agent, and the card changes in place to show what happened, for example “@alice allowed this once.”
  • A tap from someone who is not an owner gets “Not authorized.” and changes nothing.
  • With no answer in 600 seconds, the tool is not approved and the card reads “Timed out, not approved.” Codex and Pi use their own time limit when they set one.
  • The owners are the people GET /v1/me names in owner_people. When none of them has a Relay app account, the tool is not approved and the terminal says to link a phone, from Settings in Relay Console or with relay phone link.

​
Options

​
Next steps