Quickstart

This guide assumes the user has never opened Pacerelle before. It covers the app screens and the local runtime flow.

Before you start

• Node.js 20 or newer if you use the JavaScript SDK.
• Python 3.12 or newer if you use the Python SDK.
• A Pacerelle account.
• A local process you want to connect, such as an Ollama helper, workflow runner, MCP server, or custom script.

The SDKs connect to Pacerelle using the agent id and token copied from the website.

1. Create the user account

Open the app, choose Create account, and enter:

• email address
• display name
• password
• password confirmation

The password must be at least 12 characters. After registration, the app signs the user in and prepares the current browser for encrypted conversations.

2. Create the agent in the app

After login:

1. Open Agents from the left navigation.
2. Click New agent.
3. Enter a name, for example Local dev assistant.
4. Add an optional description.
5. Click Create agent.

Pacerelle displays:

Click Copy .env configuration and store those values in a local .env file or secret manager.

3. Install one runtime

Use JavaScript if your agent is a Node.js service:

npm i @pacerelle/sdk

Use Python if your agent is a Python process:

pip install --pre pacerelle

Use MCP if you want an MCP-compatible client to drive the local bridge:

npx -y @pacerelle/mcp-server

4. Run a Node.js echo agent

Create agent.mjs:

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

const client = new AgentGatewayClient({
  agentId: process.env.PACERELLE_AGENT_ID,
  token: process.env.PACERELLE_AGENT_TOKEN,
  e2ee: true,
});

client.onMessage(async (message, agent) => {
  await agent.sendMessage({
    conversationId: message.conversationId,
    to: message.from,
    replyToMessageId: message.id,
    text: `Received: ${message.text}`,
  });
});

await client.connect();

Run it:

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

5. Send the first message

In the app:

1. Open Conversations.
2. Select the agent.
3. Send hello.
4. Wait for the local process to reply with Received: hello.

The agent should also show as online while the local process is connected.

Success checklist

• The agent appears online in the app.
• The local runtime logs a successful connection or stays running without an auth error.
• Messages arrive at the onMessage handler.
• Replies appear in the conversation.
• Refreshing the web app keeps the conversation available after the browser is ready.

Next steps

• Read Account and device setup if login or device trust is unclear.
• Read Agents and credentials before putting tokens in production.
• Read SDK integration to connect real agent logic.