Agent Connect — Pacerelle Docs

Agent Connect is for products that run an agent on behalf of their users — a research assistant, a support bot, a home-automation service. Instead of asking users to copy an agent token, your app requests an installation, the user approves it in Pacerelle, and your server receives credentials scoped to that one agent.

How it works

The user creates a connection key

In Pacerelle, the user opens Settings → Security → Agent Connect and creates a one-time connection key, then pastes it into your app.

Your server starts the installation

It calls beginAgentConnect with the key and redirects the browser to the returned authorization URL.

The user approves in Pacerelle

Pacerelle shows your agent's name and description. On approval, it creates the agent and a direct conversation, then redirects to your callback with a one-time code.

Your server exchanges the code

It receives a long-lived installation token, then requests short-lived runtime tokens to connect the agent.

1. Register your app

Register an OAuth client once, with every callback URL you'll use. Keep the returned client_id in your server configuration.

Terminal

curl -X POST https://api.pacerelle.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Research",
    "redirect_uris": ["https://acme.example/pacerelle/callback"]
  }'

2. Start the installation

Run this on your server. Store state and codeVerifier in the user's server-side session.

import { beginAgentConnect } from "@pacerelle/sdk";

const pending = await beginAgentConnect({
  connectKey: keyPastedByTheUser,
  clientId: process.env.PACERELLE_CLIENT_ID,
  redirectUri: "https://acme.example/pacerelle/callback",
  agentName: "Acme Research",
  agentDescription: "Summarizes your research inbox every morning.",
});

session.pacerelleState = pending.state;
session.pacerelleVerifier = pending.codeVerifier;
response.redirect(pending.authorizationUrl);

3. Handle the callback

Check state first, then exchange the code for an installation token. Store that token encrypted, server-side only.

import { exchangeAgentConnectCode } from "@pacerelle/sdk";

if (request.query.state !== session.pacerelleState) throw new Error("Invalid state");

const installation = await exchangeAgentConnectCode({
  code: request.query.code,
  codeVerifier: session.pacerelleVerifier,
  clientId: process.env.PACERELLE_CLIENT_ID,
  redirectUri: "https://acme.example/pacerelle/callback",
});

await saveEncrypted(user.id, {
  installationToken: installation.installationToken,
  agentId: installation.agentId,
});

4. Run the agent

Request a runtime token, then connect exactly like any other agent.

import { requestAgentRuntimeToken } from "@pacerelle/sdk";
import {
  createNodeAgentGatewayClient,
  createNodeSignalSnapshotStore,
} from "@pacerelle/sdk/node";

const runtime = await requestAgentRuntimeToken({ installationToken });
const state = createNodeSignalSnapshotStore(runtime.agentId);

const agent = createNodeAgentGatewayClient({
  agentId: runtime.agentId,
  token: runtime.agentToken,
  e2ee: true,
  signalSnapshot: state.signalSnapshot,
  onSignalSnapshot: state.onSignalSnapshot,
});

agent.onMessage(async (message, client) => {
  await client.reply(message, { text: "Hi! I'm connected. How can I help?" });
});

await agent.connect();

Tokens and lifecycle

Token	Lifetime	Where it lives
Connection key	One use	Pasted by the user into your app.
Installation token	Until the user revokes the installation	Your server, encrypted at rest. Never in a browser.
Runtime token	15 minutes	Your agent process. Request a new one before each reconnection.

Keep one state per agent. Persist the encryption state for each agentId you run. Changing it changes the agent's identity.
The user speaks first. The installation creates a direct conversation; once the user sends the first message, the encrypted session is established and your agent can reply.
Revocation is immediate. If the user revokes the installation in Pacerelle, new runtime tokens are refused. Handle that error by stopping the agent and marking the installation as disconnected.