Expose a Home Lab App Through an Agent

Expose a service from a private network by installing an agent that connects outbound to the p2pstream management server.

Use This When

Use an agent target when the upstream service is reachable from a home lab or remote host, but not from the public p2pstream server.

Example:

Role	Value
p2pstream management	https://proxy.example.com:8081
Home lab service	http://homeassistant.local:8123
Public URL	https://ha.example.com

Prerequisites

• The p2pstream server is reachable by the agent over management HTTPS/TLS and /agent/tunnel.
• MANAGEMENT_PUBLIC_URL is set to the external management URL.
• The home lab host can reach the upstream service.
• Public DNS for ha.example.com points to the p2pstream server.

Steps

1. Open Agents -> Fleet and select Add agent. Enter the agent in the Add agent drawer, then select Create agent.

   Field	Value
   Name	home-lab
   Enabled	On

   After creation, the Install agent modal shows the generated AGENT_ID and one-time AGENT_TOKEN.

   

   The Agent Setup modal shows the one-time token and generated installer snippets. Copy the command before selecting Done because the token is not shown again.

2. Select Linux install, copy the generated command, and paste it into a terminal on the agent host. The command already includes the agent token and, when enabled, the updater enrollment token. It downloads the installer and binary for the selected release and host architecture, then verifies their SHA-256 checksums before installation. No local file paths or separate token entry are required.

   The installer creates /usr/local/bin/p2pstream, /etc/p2pstream/agent.env, and p2pstream-agent.service, then restarts the agent service. For an existing host, use More → Reinstall / repair to keep its token and enable managed updates. After explicit token rotation, run the separate token-change command. Independently verified local files can still be selected under Advanced setup options.

3. Check the agent service:

   sudo systemctl status p2pstream-agent
   sudo journalctl -u p2pstream-agent -f

4. Select Edit for the agent and add a label in the Edit agent drawer, for example:

   Key	Value
   site	home-lab

   Labels under p2pstream.io/ are system-owned and read-only. The exact-agent selector label is p2pstream.io/agent-id=<agent public ID>. Empty label values are allowed, but should be used only when you intentionally want to match an empty value.

   

   Agent labels are the bridge between connected workers and agent route targets. User labels are editable; system labels are read-only and can be copied for exact-agent targeting.

5. Open Proxy -> Sites and create a draft site for ha.example.com, assigned to public-https. Inside the open site, select Add first route and add an agent proxy target in the nested route drawer:

   Origin resolution

   The origin URL is resolved from the agent host, not from the p2pstream server. Set it to whatever the agent host can reach — localhost, a LAN hostname, or an internal IP are all valid here.

   Field	Value
   Name	homeassistant
   Type	Proxy
   Transport	Agent
   URL	http://homeassistant.local:8123
   Agent selector	site=home-lab
   Priority group	0
   Weight	100
   Enabled	On

   

   The agent target section selects agents by label and keeps the origin URL relative to the selected agent host, not the p2pstream server.

   New agent targets use round-robin selection among matching agents by default. The public configuration API supports additional agent-selection policies; the redesigned route drawer retains an existing policy but does not currently expose a control to change it.

6. Configure the route's path match and save it to return to the site. Hostnames and listeners come from the site:

   Field	Value
   Path prefix	/

7. Use the site readiness summary, or TLS -> Add Certificate, to create an ACME certificate mapping for ha.example.com on public-https. Review readiness and select Publish in the site workspace.

Verification

Run:

curl -I https://ha.example.com

Agents -> Fleet should show the agent connected, and Monitor -> Traffic tracing should show the selected route target and agent.

Troubleshooting

Symptom	Check
Agent offline	Confirm MANAGEMENT_URL, CA material, token, and outbound firewall access.
Target fails	Test http://homeassistant.local:8123 from the agent host.
Health check unhealthy	Health checks run from each matching connected agent.
Need to remove the agent	On Agents, select More -> Show uninstall command, or use Systemd uninstall.

Agent selectors require at least one label, and all selector labels must match the same agent. If no label-matched agent is connected, requests to this target fail until an enabled matching agent reconnects.

Next Steps

• Build a multi-agent target
• Agents
• Systemd operations