Run agents in production

Use this page when your agent already works locally and you want it to run reliably for real users.

What you deploy

You do not deploy the Pacerelle website. You deploy your own local agent runtime: a Node.js script, Python process, MCP server, container, or worker that connects to Pacerelle with an agent id and token.

Required environment

Every production runtime needs:

PACERELLE_AGENT_ID="agent id copied from Pacerelle"
PACERELLE_AGENT_TOKEN="agent token copied from Pacerelle"
PACERELLE_LOG_LEVEL="info"

Store the token in the secret system provided by your runner. Examples include Docker secrets, systemd environment files with restricted permissions, a CI/CD secret store, or a managed worker secret manager.

Process supervision

Agents are long-running connection clients. Production runners should:

• restart the agent on crash
• restart the agent after machine reboot
• stop gracefully before deploys or upgrades
• keep logs free of tokens and decrypted user content
• report basic connection state, such as started, connected, disconnected, and retrying
• use separate agents and tokens for staging and production

Recommended runners

Choose the runner that matches where your agent lives:

Runner	Good fit
systemd	A Linux server or workstation that should keep the agent alive.
PM2	A Node.js agent running on a server you control.
Docker	A repeatable agent environment with pinned dependencies.
Desktop MCP host	Claude Desktop, Cursor, Zed, or another MCP-compatible app.
Managed worker	A hosted runtime for agents that do not need local files or local models.

Token rotation runbook

Rotate the token when it was exposed, copied to the wrong machine, or a teammate no longer needs access.

1. Open Agents in Pacerelle.
2. Select the agent.
3. Rotate the token.
4. Copy the new .env configuration.
5. Update the runtime secret.
6. Restart the local agent.
7. Confirm the agent is online.
8. Remove the old token from shell history, config files, CI variables, and logs if needed.

Production checklist

• The agent starts without manual terminal interaction.
• The agent comes back online after restart.
• The runtime uses environment variables or a secret manager.
• The token is not stored in public code, screenshots, or logs.
• The agent has the minimum local permissions needed for its task.
• Destructive actions use confirmation or permission widgets.
• File uploads are validated before processing.
• Staging and production use different Pacerelle agents.
• Token rotation has been tested once before an emergency.