Connect an agent with browser sign-in

The fastest way to connect an AI agent (or the pushrail CLI) to Pushrail is to sign in from your editor. You point the client at the Pushrail server, approve access in your browser, and pick the workspace to use. There's no key to generate, copy, or paste, and the session refreshes itself so you don't have to sign in again every time.

This guide walks through the browser flow end to end, the headless alternative for machines without a browser, and the API-key option for CI. For the full MCP tool list and the safety-mode ladder, see MCP integration.

The browser sign-in flow

1. Point your client at Pushrail. For an AI agent, run pushrail mcp install --client claude (or cursor / windsurf / codex), which writes the MCP config pointing at https://mcp.pushrail.io. For the CLI itself, just run pushrail login.
2. Approve in the browser. The first time the client connects, Pushrail opens your browser. You sign in to your Pushrail account if you aren't already.
3. Pick a workspace. On the approval screen you choose which workspace the agent should act in. This scopes everything the agent does to exactly that workspace.
4. Done. Once you approve, the client is connected. Nothing to copy or paste. From here the agent can use its tools, and the CLI can run commands, against the workspace you picked.

What the workspace picker means

A single Pushrail account can belong to several workspaces, each with its own destinations, keys, and delivery history. The approval screen makes you choose one so the agent operates in a well-defined place:

• Workspace — which tenant's data and configuration the agent sees. Your role in that workspace sets the agent's capability ceiling.

The connection is scoped to the workspace, not to a single environment — it covers that workspace's Development, Staging, and Production environments. To switch an agent to a different workspace, sign in again and pick the new one.

Sessions refresh automatically

Browser sign-ins don't expire the moment the access token ages out. Pushrail issues a session that renews itself in the background, so a connected agent or CLI keeps working without re-prompting you. If you ever need to renew the active CLI credential by hand, run:

pushrail auth refresh

To sign out and discard the stored session, run pushrail logout.

Headless machines and SSH (device sign-in)

On a server, a container, or over SSH there may be no browser to open. Use device sign-in instead:

pushrail login --device

The CLI prints a short code and a URL. Open that URL in a browser on any device — your laptop or phone — sign in, enter the code, and pick the workspace just like the regular flow. The headless machine finishes signing in as soon as you approve.

CI and service agents (API key)

Automated jobs that run unattended should use a key rather than a browser sign-in. Which key depends on what's connecting:

• An MCP client (an AI agent / the MCP server). Use an MCP API key — an account-wide key (begins with pmk_) minted at MCP API keys in the dashboard. Pass it as the Authorization header on the MCP client — see the MCP API key header section of the MCP guide. It's not tied to an environment; the agent names the environment per tool call. With an MCP API key, the agent's ceiling is the key's scope rather than your role: a manage key tops out at write operations, while a read key is read-only.
• The CLI sending events. Sign the CLI in with an environment-scoped API key (created from Settings → API keys), whose environment is fixed by the key:

pushrail login --api-key pr_dev_…

or set PUSHRAIL_API_KEY in the environment so nothing is persisted to disk.

Next steps

• MCP integration — every tool the hosted server exposes and how safety modes work.
• CLI command reference — pushrail login, pushrail auth refresh, pushrail mcp install, and the rest.
• Team & roles — what each workspace role can do.