Quickstart — Pacerelle Docs

In this guide you'll create an agent in the Pacerelle app, run a small program on your computer, and exchange your first end-to-end encrypted message with it.

You need: a Pacerelle account and either Node.js 20+ or Python 3.12.

Create an agent in the app

Open Pacerelle, go to Agents and choose Connect an agent. Give it a name — for example My assistant — and continue.

Pacerelle registers the agent and shows its configuration: an agent ID and a secret agent token.

Save the configuration

Copy the configuration into a file named .env in an empty folder on the machine that will run the agent:

.env

PACERELLE_AGENT_ID=agent_...
PACERELLE_AGENT_TOKEN=...

The token is shown only once

Store it now. It lets a program connect as your agent, so keep it out of source control and screenshots. If you lose it, you can replace it at any time.

Install the SDK

npm init -y
npm install @pacerelle/sdk

Write the agent

This agent answers every message by repeating it. It's the smallest program that proves the whole encrypted path works.

agent.mjs

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

const agentId = process.env.PACERELLE_AGENT_ID;
const token = process.env.PACERELLE_AGENT_TOKEN;

// Keeps the agent's encryption keys on disk between restarts.
const state = createNodeSignalSnapshotStore(agentId);

const client = createNodeAgentGatewayClient({
  agentId,
  token,
  e2ee: true,
  signalSnapshot: state.signalSnapshot,
  onSignalSnapshot: state.onSignalSnapshot,
  onOpen: () => console.log("Connected. Send a message from Pacerelle."),
});

client.onMessage(async (message, agent) => {
  await agent.reply(message, { text: `You said: ${message.text}` });
});

await client.connect();

Run it

node --env-file=.env agent.mjs

Leave the terminal open. In Agents, your agent now shows as online.

Send your first message

Open the conversation with your agent — on the web or in the mobile app — and send Hello. Your agent answers You said: Hello.

That's it: your phone and your computer just exchanged an end-to-end encrypted message through Pacerelle, without opening a single port.

What just happened

On start, the SDK generated the agent's encryption keys, published its public keys and opened an outbound, authenticated WebSocket to Pacerelle.
Your app encrypted Hello for your agent's keys. The relay stored and forwarded ciphertext only.
The SDK decrypted the message on your machine and called your handler.
Your reply was encrypted locally and delivered back into the same conversation.

Keep the state file

The SDK saves the agent's private keys locally — ~/.pacerelle/agents/<agent-id>.signal.b64 in JavaScript, ~/.myagents/<agent-id>/signal.db in Python. Keep it with the agent: deleting it gives the agent a new identity and breaks existing encrypted conversations.

Next steps

Connect a real model

Replace the echo with OpenAI, Anthropic, Ollama or your own workflow.

Ask before acting

Add confirmations, choices and forms to your agent.

Use an MCP host instead

Connect Claude Desktop, Cursor or another MCP host without writing code.

Keep it running

Reconnect automatically, supervise the process and rotate tokens.