Run in production
Security and encryption
What Pacerelle encrypts, what the relay can and can't see, how to verify an agent, and what stays your responsibility.
Pacerelle is built so that the service in the middle can deliver your conversations without being able to read them. This page explains exactly what that covers.
End-to-end encryption
Messages are encrypted with the Signal protocol on the sender's device and decrypted only on the recipient's — your phone or browser on one side, your agent's machine on the other. Each device and each agent has its own keys; the relay only ever handles public keys and ciphertext.
Files are encrypted separately with a fresh AES-256-GCM key per file. The key, the file name and its type travel inside the encrypted message; the relay stores a file it can't open, under a generic name.
What the relay can and can't see
| Encrypted — the relay can't read it | Visible to the relay — needed to operate the service |
|---|---|
| Message text | Your account email and profile |
| Widget questions and answers | Agent names, descriptions and avatars |
| File contents, names and types | Who is in which conversation |
| When messages are sent, and their size | |
| Whether an agent is online | |
| Attachment sizes |
End-to-end encryption protects the path between you and your agent. Once your agent has decrypted a message, it's your code's job: if it sends the text to a hosted model API, that provider sees it under its own terms. For maximum privacy, use a local model.
No open ports
Your agent connects out to Pacerelle over TLS. Nothing listens on your machine, so there's no port to forward, no public IP to expose and no inbound attack surface created by Pacerelle.
Verify your agent
Each agent has a verification code: the fingerprint of the public identity key its program published. Comparing it proves you're talking to your program and not to an impostor.
Print the code on the agent's machine
await client.connect();
console.log("Verification code:", await client.getVerificationCode());Open the verification in the app
In the conversation with the agent, open the options and choose Verify.
Compare every group of characters
If the codes match, the agent is verified. If they differ, cancel and check which program is connected with that agent's token.
Always read the code on the agent's machine. A code sent inside the conversation proves nothing.
Agent tokens
- A token lets a program connect as your agent. It's shown once; store it like a password.
- Replacing a token disconnects the current program and invalidates the old token immediately.
- Agent Connect runtime tokens expire after 15 minutes, and revoking an installation stops new ones from being issued.
The agent's state file
The SDK keeps the agent's private keys in a local state file. Anyone who can read it can decrypt that agent's future messages, and deleting it resets the agent's identity. Keep it private, backed up, and used by a single process. Locations are listed in the Production checklist.
Your responsibilities as an agent builder
Pacerelle protects the conversation. What your agent does with it is up to you:
- Ask before acting. Use widgets and the permission policy before destructive, costly or external actions.
- Least privilege. Run the agent under an account that can only reach what it needs.
- Treat input as untrusted. Messages and files can contain instructions aimed at your model (prompt injection). Never let content alone trigger sensitive actions.
- Keep logs clean. Don't log message content, files, widget answers or tokens in production.
- Don't forward silently. Ask before sending user content or files to third-party services.