> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an agent

> Connect one runtime to Relay in the folder where you work.

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

## Start

Run this command from your project folder.

```bash theme={null}
npx relaymessenger@staging connect
```

> [!NOTE]
>
> 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:

```text theme={null}
Created @handle
Plugin installed
wrote <path>
Say hi from your phone
```

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.

| Coding agent | Starts with | Runs without a card |
| - | - | - |
| Claude Code | Your user and project settings | Read, Glob, Grep, WebFetch, WebSearch, TodoWrite, Task, NotebookRead, and Relay's tools |
| Codex | Approval policy `on-request` and the `workspace-write` sandbox, which writes only in the folder you ran connect in | Relay's tools |
| Gemini CLI, Cursor, OpenCode, Cline | The agent's own settings and permission prompts | Relay's tools, in Gemini CLI |
| Pi | No permission prompts; your own extensions can ask with a dialog | Everything your extensions do not ask about |

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`](https://docs.staging.relayapp.im/api-reference/agents/get-the-authenticated-agents-owner) 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`](https://docs.staging.relayapp.im/cli/reference/phone-link).

## Options

| Option | Action |
| - | - |
| `--new` | Create a new agent instead of using one already saved. |
| `--handle <handle>` | Set the handle for a new agent. |
| `--name <name>` | Set the name people see next to a new agent. |
| `--subtitle <text>` | Set the line under the agent's name, 60 characters; required for a new agent. |
| `--description <text>` | Set what it can do, 2000 characters; required for public agents. |
| `--token <token>` | Use an existing agent by its token. |
| `--with-token` | Read an existing agent's token from a pipe. |
| `--yes` | Replace an existing runtime token without asking. |
| `--json` | Print the result as JSON. |
| `--dry-run` | Print the plan without changing anything. |
| `--non-interactive` | Run without interactive prompts. |

## Next steps

* [Pick your runtime](https://docs.staging.relayapp.im/integrations.md)
* [Watch messages](https://docs.staging.relayapp.im/cli/watch.md)
* [Check setup](https://docs.staging.relayapp.im/cli/doctor.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.