Agents

Agents let p2pstream forward public traffic into networks that do not accept inbound connections.

What It Is

An agent is a registered remote worker with a generated public ID and token. It connects outbound to the management server over an authenticated Yamux tunnel on management TLS, receives raw TCP stream requests, dials origins from its own network, and relays bytes back.

When It Matters

Use agents for home lab services, private network apps, remote hosts behind NAT, or route targets that need more than one private network path.

Runtime Behavior

Agent IDs and tokens are generated by management. Tokens are shown once when created or rotated and are stored server-side as hashes.

Agents can also carry labels. User labels are configured in the Agent editor and are used by agent route targets to select eligible agents. Labels under p2pstream.io/ are system-owned and displayed read-only. The built-in exact-agent selector label is:

p2pstream.io/agent-id=<agent public ID>

Agent target selectors require at least one label. All selector labels must match the same enabled agent. Empty label values are allowed, but use them intentionally because role= matches only agents whose role label is present and empty.

Agents connect outbound to management:

• HTTPS for stats and API calls.
• HTTP/1.1 upgrade streaming on /agent/tunnel with Upgrade: p2pstream-yamux for forwarding.

The tunnel runs Yamux keepalives over the upgraded management connection. If another reverse proxy sits in front of the management listener, it must allow HTTP/1.1 upgrade streaming for p2pstream-yamux and keep idle upgraded connections open long enough for long-lived agent sessions.

Compatible peers establish four parallel TCP tunnels by default. They share one agent identity and resource budget; dropping one lane preserves traffic on the others. Reusable HTTP transports distribute requests across these lanes, including HTTP/2 requests to the same origin. Receive windows grow on demand with memory reservations. See Agent proxy performance for tuning and measured results.

Old WebSocket agents are incompatible with this transport. Keep server and agent versions matched after the Yamux breaking change.

The Agents page puts enabled offline agents and version differences first, then supports search by name, ID, version, or label and filtering by state or version difference. The Fleet tab shows each agent's reported version beside the selected management server version. Stable releases and immutable SemVer prereleases are ordered using SemVer and marked Update available or Ahead of server. Development, nightly, legacy mutable staging, and custom builds are only marked as different when their version or reported commit differs because their upgrade direction cannot be inferred safely. A mutable-tag agent that predates commit reporting is marked Build unverified instead of being assumed current. The same table shows current connected or offline duration, uptime percentage over the observability retention window, connection and disconnect counts, load, and visible Investigate and Edit actions. Each row's Details link opens an agent details drawer with the agent ID and exact selector (each with a copy button), user labels, and runtime facts such as uptime, capacity allowance, memory, and file descriptors, plus an Edit agent shortcut; lifecycle actions such as enable/disable, rotate, uninstall, and delete live in each row's More menu. The Activity tab shows the newest connection sessions and is filtered automatically when Investigate is selected. Its availability history defaults to All agents: one lane per agent on a shared 24h, 7d, or 30d axis, worst uptime first and disabled agents last, with connected and disconnected time and hatched time before an agent was observed; selecting a lane opens that agent's detailed timeline. Uptime is calculated from retained connections rows, clipped to the retention window and the agent creation time. If the management server restarts after a crash or forced stop, stale open connection rows are closed at startup so old sessions do not appear active forever.

By default, agents reject insecure HTTP management URLs and verify HTTPS certificates. For auto-generated management TLS, pass one of:

Variable	Use
MANAGEMENT_CA_FILE	Path to a PEM CA bundle on the agent host.
MANAGEMENT_CA_PEM_BASE64	Base64-encoded PEM CA bundle, useful for generated snippets.

The Install agent modal can generate a one-line Linux systemd installer, a Docker Compose service, or a direct CLI command. Each generated form configures writable durable management trust; Docker uses a named state volume and direct CLI runs use a local state directory. The Linux command includes the issued credentials and automatically downloads the matching installer and binary from the selected GitHub release, verifying their SHA-256 checksums before installation. Optional local file overrides are available under advanced options. Staging builds pin the isolated staging managed-update channel. The command writes /etc/p2pstream/agent.env, enables p2pstream-agent.service, and restarts it. Use More → Reinstall / repair to reuse the existing host token and include managed-update enrollment. Rotate token instead generates a credential-only command that preserves the installed software and settings, then restarts the connection. All setup actions share an editable Management URL; a remote server advertising localhost defaults to the saved environment address.

If management requires agent client certificates, configure:

AGENT_TLS_CERT_FILE=/etc/p2pstream/agent.crt.pem
AGENT_TLS_KEY_FILE=/etc/p2pstream/agent.key.pem

Common Mistakes

• Reusing an old token after rotating it in management instead of applying the generated token-change command on the agent host.
• Setting MANAGEMENT_URL to a public listener instead of management.
• Putting management behind a reverse proxy that blocks HTTP/1.1 upgrade streaming for p2pstream-yamux or closes idle upgraded connections too aggressively.
• Forgetting CA material when management uses the auto-generated local CA.
• Deleting the management agent record and expecting files to be removed from the remote host.

Related Links

• Expose a home lab app
• Build a multi-agent target
• Systemd uninstall

The Fleet tab puts agents needing attention first and keeps investigation and editing visible while less frequent lifecycle actions remain in the row menu.

The agent drawer separates user labels used by route targets from reserved system labels such as the exact-agent selector.