Agents and credentials

An agent is the Pacerelle record for one local runtime. The runtime can be a Node.js process, Python process, MCP server, or any service built with the SDK.

Create an agent

In the web app:

1. Sign in.
2. Open Agents from the left navigation.
3. Click New agent.
4. Enter a clear name, for example Ollama laptop or Release helper.
5. Add a short description if future you will need context.
6. Click Create agent.

Pacerelle then shows a confirmation panel with the credentials your local process needs.

Copy the environment variables

The confirmation panel contains:

Use Copy .env configuration. Paste the copied values into the .env file used by your local runtime.

What the id and token do

PACERELLE_AGENT_ID tells the runtime which Pacerelle agent it represents. It is not the secret, but avoid publishing it unnecessarily.

PACERELLE_AGENT_TOKEN lets the runtime connect as that agent. It is secret. Treat it like a password.

Store the token safely

Do:

• keep the token in .env, Docker secrets, or your hosting secret manager
• add .env to .gitignore
• use separate agents for development and production
• rotate the token if it was pasted into the wrong place

Do not:

• commit the token to Git
• paste it into browser code
• share it in screenshots, support tickets, or public logs
• reuse the same token across unrelated machines

Check online status

After your local runtime starts, return to Agents. The agent should show as online while the runtime is connected.

If it stays offline:

1. Confirm the .env file has both PACERELLE_AGENT_ID and PACERELLE_AGENT_TOKEN.
2. Restart the runtime after editing .env.
3. Confirm the token belongs to the same agent.
4. Check that your network allows outbound WebSocket traffic.

Rotate a token

Rotate the token when:

• it was exposed
• you moved the runtime to another machine
• a teammate no longer needs access
• you are separating development and production

After rotation:

1. Copy the new .env configuration.
2. Replace the old token in your runtime environment.
3. Restart the local process.
4. Confirm the agent returns online.

Delete an agent

Delete an agent when you no longer want that local runtime to connect. Deleting an agent stops future connections for its token. Create a new agent if you need a clean setup.

Naming guidance

Use names that explain where the runtime lives and what it does:

• MacBook Ollama
• Home NAS file agent
• n8n automation runner
• Release checklist MCP