# Connect an outside agent to your workspace

An agent that runs outside ampm, such as a coding assistant in your own terminal, can read a workspace's evidence and recommend what to do next. If you allow it, it can also act. You decide what it may do when you create its handoff, and the agent never holds more than that.

## Create a handoff

Open the **Agent MCP grants** settings page in your workspace and create a handoff. You choose:

- **A session length**: eight hours, one day, seven days, 30 days or 90 days.
- **Action tools**: the closed set of actions the agent may carry out. Leave all of them off and the agent can read and recommend only. [The tool catalog](/docs/agent-access-tools) lists each one.
- **Approval categories**: the kinds of approval the agent may answer for you. [Approval categories](/docs/agent-access-approvals) lists what each one allows.

The page shows a prompt for the agent. You copy it once.

If that response is lost, retrying the same request shows a recovery notice instead of creating
another agent or revealing the handoff again. Inspect the grants list and revoke any access you
no longer need, then choose **Create replacement access**. Reloading the page never submits a
request; inspect the grants list before creating access after a reload.

## Paste the prompt into the agent

The prompt carries a handoff, not a durable secret.

- **It expires in ten minutes and works once.** The first exchange uses it up. A second attempt, or an attempt after ten minutes, fails and you create a new handoff.
- **The session secret is never in the copied text.** The agent exchanges the handoff for its session and keeps the result in its own secure storage. It should not print the session secret or paste it back into a conversation.
- **No sign-in is involved.** The exchange needs no OAuth and no browser cookies, so do not hand the agent your own credentials.

After the exchange the handoff is useless, even to someone who copied the prompt.

## What every session can do

Every session can read the workspace's safe, workspace-scoped evidence and recommend any action, including actions it has no grant for. The agent reasons over what it reads. ampm does not run a second planning model for it. [The tool catalog](/docs/agent-access-tools) lists every read.

Actions are different. The agent can carry out an action only when you granted that tool, and an approval answer only when you granted its category. [How permissions work](/docs/agent-access-permissions) explains how a grant is checked.

## Authority only shrinks

A session's grant is fixed when you create the handoff. From then on:

- Your workspace's current limits for that agent are checked on every call. If you reduce them, the session loses actions or approval categories right away.
- Nothing an active session does, and nothing you change afterwards, can add authority to it.
- To give an agent more, create a new handoff with the larger grant.

Revoking the agent ends the session at once.

## Open a read-only preview

The `showPreview` tool returns an intent for the render-only viewer, defaulting to the bound workspace. An optional path can select its board, task, approval, activity or turn page. Foreign workspace, Settings and account/admin paths are refused before any link is minted. The viewer shows ordinary workspace pages, and its buttons may look usable, but nothing done there changes the workspace. Changes go through the agent's tools, which check its grant.

A preview opens from a one-use link that lasts 60 seconds. The viewer session lasts up to eight hours, or one hour when embedded in another page. It never outlives the agent session that opened it, and it ends when that session is revoked.

## When access ends

If the session is revoked, expires, or a preview cannot be renewed, the agent and any open preview land on an "access ended" page. That page loads no workspace data. The reason is not shown, because the cases look the same from outside. Create a new handoff and give the agent the new prompt.

An agent that sends a lot of requests in a row may be asked to slow down. It gets a 429 answer that says how many seconds to wait, and its session keeps working after that. Only a revoked or expired session lands on the access-ended page.

## Check what an agent did

Every action an agent attempts is recorded with its request id, whether it was allowed, and why a refusal happened. The agent can read its own audit trail. [The tool catalog](/docs/agent-access-tools#request-ids-and-the-audit-trail) explains how outcomes are recorded.