# Set up your agent

Need exact steps? Choose [Claude Code](https://docs.extrovert.dev/mcp/client-configuration/#claude-code),
[Codex](https://docs.extrovert.dev/mcp/client-configuration/#codex), [Hermes](https://docs.extrovert.dev/mcp/client-configuration/#hermes),
or [Claude web/mobile](https://docs.extrovert.dev/mcp/email-assistant/#claude-web-desktop-cowork-and-mobile).
For a brand-new account, use [agent-first signup](https://docs.extrovert.dev/quickstart/create-account/).
For an existing account, connect it and create the inbox there; do not sign up again.

## Let your agent handle setup

Give this prompt to your agent:

<blockquote><p>Read https://docs.extrovert.dev/llms.txt and follow its setup checklist in order to send my first email. Stop and report install errors. Do not request credentials in chat.</p></blockquote>

Your agent reuses an existing connection or helps connect your account. If you are new,
it can create a free inbox when signup is available. It asks about your account only
when needed. You choose the access; your agent handles the supported installation steps.

For a new free inbox, choose its address and sender name, then send an email from your
human address to the agent address it gives you. That email claims the inbox. Extrovert
sends a welcome with the address and plan, and prepares your first draft for review.
Your active agent watches for the claim and continues setup. If the wait ends, ask it
to resume the same setup. [How claiming works](https://docs.extrovert.dev/quickstart/authentication/#free-self-signup).

Open the review link and **Sign up** with the same human email if this is your first console visit; otherwise **Sign in** to review that draft. This gives you console access to
the inbox you already own. You can approve it, edit it, or coach your agent to learn your
writing preferences. [Try your first conversation](https://docs.extrovert.dev/quickstart/zero-to-first-email/#your-first-conversation-with-your-agent).

After that practice message is sent, **Review -> Auto-send** offers **Skip review for
emails to you**. This optional setting starts off. It only applies when your verified
email is the sole To recipient, with no Cc/Bcc or aliases. Your writing rules still
apply, and messages including anyone else keep their usual review requirements.
[Learn more](https://docs.extrovert.dev/review-loop/agent-contract/#email-your-human-without-review).

## Already have an account?

In your console, open **Agents -> Connect an agent** in the intended project. Copy the
setup prompt there; it tells your agent to use your existing account and project.
You can also follow the manual steps below. Connecting another agent does not require
creating another account or repeating the first-message tutorial.

At authorization, choose:

1. **Dedicated agent:** select an existing named agent or create one.
2. **Selected inboxes:** select only the inboxes it needs.
3. **Read and send:** let it read mail and prepare messages under your review policy.

Review the application, agent, resources and permissions before authorizing.
No inboxes are selected automatically. Creating an agent identity does not create
an inbox: choose **Create an inbox here** on the Connect an agent page to give it an
address and sender name without leaving setup. Then select that inbox at authorization.
If the signed-in email is wrong, choose **Sign in with another account** on the
authorization screen. Your pending connection stays available after sign-in.
**You keep control:** Dedicated agent gives activity a named identity. Resources and permissions limit
  what it can access. Personal assistant can also have limited access. Full account
  control is for explicitly requested account administration and is not needed for
  ordinary email setup. [Understand the choices](https://docs.extrovert.dev/concepts/connections-and-access/).

## Set it up yourself

Sign in to your existing console account. If you do not have one, create your console
login first and complete account setup. Create or select the agent and inbox you want
to connect, then use the instructions for your application.

### Install the email skills

Using Claude Code? [Install one plugin with skills and hosted MCP together](https://docs.extrovert.dev/mcp/client-configuration/#install-skills-and-hosted-mcp-together).
That path needs no Node.js or separate skills installation. Continue authorization
there instead of adding a second MCP connection below. Already installed a plugin?
Use the [Claude plugin update commands](https://docs.extrovert.dev/operating/agent-updates/#update-a-claude-code-plugin).

Codex also offers a [plugin with skills and local MCP](https://docs.extrovert.dev/mcp/client-configuration/#plugin-with-skills-and-local-mcp).
Hermes uses the standalone skills below alongside its MCP connection.

For a terminal host, run this in the intended host environment (Node.js 20 or later):



```bash
npx --yes --prefer-online skills@latest add extrovert-dot-dev/extrovert-skills --skill extrovert-connect extrovert-send-email extrovert-writing-rules
```



Select the intended host and installation scope. Keep existing pins and customizations.
A complete Extrovert plugin can supply these skills instead; do not install duplicates.
For managed hosts without local installation, use the host's supported connector and
instruction settings. [Host-specific configuration](https://docs.extrovert.dev/mcp/client-configuration/).

### Connect and authorize



```bash
npx --yes --prefer-online @extrovert.dev/mcp setup --host hermes --transport hosted
hermes mcp login extrovert
```



Use the intended Hermes profile for setup and login. Follow the host's reload instructions.

  

```bash
claude mcp add --transport http extrovert https://mcp.extrovert.dev/mcp
```



Inside Claude Code, run `/mcp`, select Extrovert, and authenticate.

  

```bash
codex mcp add extrovert --url https://mcp.extrovert.dev/mcp
codex mcp login extrovert
```



  Use your application's MCP settings with this server URL, then follow its OAuth sign-in:

```text
https://mcp.extrovert.dev/mcp
```

[More client configurations](https://docs.extrovert.dev/mcp/client-configuration/).

  Authorize the dedicated agent and selected inboxes as described above. If Extrovert is
already configured, authenticate that entry rather than adding another one. Reload
when the host requires it, then ask your agent:

> Check your Extrovert connection and show me which agent, inboxes, and permissions you have.

The agent should verify access through that actual connection. Saved configuration
alone does not mean it is connected. Once verified, ask it to prepare a message when
ready; sending still follows your inbox's review policy.

### Local CLI or a browser on another machine

For an existing local credential/profile, use local stdio instead of a second hosted
connection. Configure your host with `setup --host hermes --transport stdio` (or
`--host claude` / `--host codex`) and run:

```bash
npx --yes --prefer-online @extrovert.dev/mcp auth login
npx --yes --prefer-online @extrovert.dev/mcp whoami
```

The CLI reuses working access or opens browser sign-in. For SSH/headless automation,
`auth login --no-browser --json` returns a link. Open it on your browser machine,
approve access, and return its one-use completion code through the initiating secure
input using `auth complete --json`. Keep the code out of ordinary chat and logs.
[Exact completion and recovery steps](https://docs.extrovert.dev/quickstart/authentication/#local-cli-and-stdio-sign-in).

Hosted MCP OAuth and local CLI login are alternatives. Local `whoami` verifies local
access; verify MCP separately when using it.

## Give a worker a scoped key

OAuth avoids manually transferring secrets. For a worker that needs a key, open
**Credentials -> API keys**, select its existing agent, and choose permissions and expiry.
The default is **Read and send email**. Purchase requests and other permissions are
separate choices; add only what this worker needs.
The key acts as that agent within its ownership and project boundary. It does not grant
access to other agents' inboxes merely because they share a project.

Install the key at the hidden prompt:

```bash
npx --yes --prefer-online @extrovert.dev/mcp auth login --with-token
npx --yes --prefer-online @extrovert.dev/mcp whoami
```

If setup should create the agent, issue an **Enrollment key** instead. Choose its
permissions, domain/inbox limits and expiry. Enrollment defaults to **Create, read and
send email** and **Single-use**. Enable reuse only when you intend to enroll multiple agents:

```bash
npx --yes --prefer-online @extrovert.dev/mcp enroll --agent-handle support-agent
```

Paste the enrollment key at the hidden prompt. The CLI saves the resulting agent key
privately. Select an isolated `EXTROVERT_PROFILE` for each worker before these commands;
keep the same profile when configuring local stdio. Never paste keys into chat,
command arguments, or source files. Revoking enrollment stops future redemption;
already-issued agent keys must be revoked separately.

To create inboxes, grant suitable reach and `mailbox:create`, or create the inbox in
the console first. Full account control is not required. Use **Connections** to inspect
OAuth grants and **Credentials** to manage keys. [Access and revocation](https://docs.extrovert.dev/concepts/connections-and-access/).

## Know what happens next

| Status | Your next step |
| --- | --- |
| **Inbox claimed** | Your matching email established ownership. Let your agent finish verifying its connection. |
| **Agent connected** | Your agent has verified its identity through that connection. Have it check its inbox access, then open the prepared draft or ask it to prepare a message. |
| **Draft awaiting review** | Open the review link. Approve the draft or coach your agent in the feedback box. |
| **Message sent** | Check the recipient's inbox. Sending confirmation does not establish receipt. |

You can always ask your agent which step it has verified and what happens next.

Project and organization owners/admins can optionally [skip review for email between agents](https://docs.extrovert.dev/review-loop/agent-contract/#email-between-agents-without-review). Both settings start off and require every recipient to belong to the sender's enabled project or exact organization. Discover the current choices through `get_inbox.internal_email_review` (SDK: inbox detail), then submit normally. Writing rules and sending limits still apply; this grants no additional inbox access.