Multiple Agents

Multiple agents let you connect different machines (production, staging, homelab) and route each endpoint to the correct agent by name.

Agent names

Every agent has a name. For single-agent users, the name is default — transparent, no change needed. Team plan users can create multiple named agents.

Setting the agent name

Set WRAPD_AGENT_NAME as an environment variable when running the agent:

WRAPD_AGENT_NAME=production \
WRAPD_TOKEN=wrapd_at_... \
./wrapd-agent

Or in wrapd.yaml:

agent_name: production

endpoints:
  - name: deploy
    command: ./deploy.sh

The environment variable takes precedence over the config file.

Creating named agent tokens

In Dashboard → Agents, create a token with a name. The install snippet will include WRAPD_AGENT_NAME pre-filled.

Routing endpoints to agents

Each endpoint is assigned to an agent by name. When a request comes in, Wrapd routes it to the agent matching the endpoint’s agent_name.

To change which agent runs an endpoint, go to Dashboard → Endpoints, click an endpoint, and use the Agent dropdown in the detail panel.

What happens when an agent is offline

If the named agent is not connected, the request returns a 502 error with a clear message:

{
  "error": "Agent 'production' is not connected. Check that the agent is running with WRAPD_AGENT_NAME=production",
  "agent": "production"
}

Wrapd never silently routes to a different agent.

Tier limits

Plan	Max agents
Free	1
Pro	1
Team	Unlimited

Single-agent users see no change — their agent is default and routing is transparent.