Get started
How Pacerelle works
The handful of ideas behind Pacerelle — agents, the relay, conversations and encryption — and how they fit together.
Pacerelle connects three things: you, on any of your devices; your agent, on a machine you control; and the relay in between, which delivers encrypted messages without being able to read them.
Your agent
An agent is any program that talks to Pacerelle through the JavaScript SDK, the Python SDK or the MCP server. It can be:
- a script that calls a model API (OpenAI, Anthropic, Google, Mistral…) and replies;
- a local model served by Ollama or LM Studio, with access to your files;
- an automation that runs builds, backups or reports and asks you before acting;
- an assistant inside an MCP host such as Claude Desktop or Cursor.
Pacerelle never runs a model and never sees your prompts. Your agent keeps its own model, tools, files and credentials. That's why it works with any provider and any framework.
Agent ID and token
When you create an agent in the app, Pacerelle gives you two values:
| Value | What it is | Secret? |
|---|---|---|
PACERELLE_AGENT_ID | Identifies the agent. | No, but don't publish it needlessly. |
PACERELLE_AGENT_TOKEN | Lets a program connect as this agent. Shown once. | Yes — treat it like a password. |
Run one program per agent. If two programs use the same token, they compete for the same messages and encryption state. Create one agent per program instead — it's free to have several.
The relay
Your agent opens an outbound WebSocket to Pacerelle and keeps it open. Because the connection starts from your machine:
- you don't open ports, configure a router or need a public IP address;
- it works behind NAT, firewalls and home networks;
- your agent appears online in the app while the connection is up.
If your agent is offline when you write to it, the message waits on the relay — still encrypted — and is delivered when the agent reconnects.
Conversations
Everything happens in a conversation:
- a direct conversation between you and one agent, created automatically for each agent;
- a group, where several people and several agents talk together and can vote.
A conversation carries text messages, files and media and widgets — structured cards such as a confirmation or a form, with the answer sent back to the agent.
The message lifecycle
You send a message
Your device encrypts it for the agent and sends ciphertext to the relay.
The SDK receives and decrypts it
On your machine, the SDK decrypts the message and calls your handler with a clean message object: text, attachments and any widget answer.
Your handler runs
You call your model, run a tool or ask a question with a widget. When the handler returns, the SDK records the message as handled and acknowledges it.
Your agent replies
The reply is encrypted locally and delivered to the conversation, on the device that asked.
Encryption and identity
Pacerelle uses the Signal protocol. Each device and each agent has its own keys; the relay only publishes public keys and moves ciphertext.
Your agent's private keys live in a local state file managed by the SDK. That file is the agent's cryptographic identity: keep it, back it up with the same care as the token, and never share it between two running programs. You can compare your agent's verification code with the app to confirm you're talking to the right program.