Add a server

Connect a Linux machine to agentry so your harness can build apps on it.

One server vs many

You can connect:

• Just your laptop (simplest; sandboxes and deploys live on the same machine you develop from).
• A dedicated server (more durable; sandboxes survive your laptop sleeping).
• Several servers (prototype on one, production on another). See Multiple servers.

For first-time setup, your laptop is the fastest path.

Requirements

The machine needs:

• Linux (or macOS, or Windows with WSL2).
• Docker installed and running.
• Outbound HTTPS to bridge.agentry.run and app.agentry.run (no inbound needed).
• ~2 GB of free disk for the agentry runtime image.

That's it. No public IP, no DNS, no firewall configuration.

Add a machine through the dashboard

1. Open the dashboard at app.agentry.run/clusters.
2. Click Add this machine.
3. (Optional) Type the name you want in the panel — homelab, production, laptop. Defaults to the machine's hostname.
4. Copy the one-line command the panel shows.
5. Paste it on the machine you want to add (your laptop, an SSH'd remote box, anything).
6. Wait ~10 seconds. The dashboard flips the new server to connected.

That single command:

• Pulls the agentry runtime image from GHCR (~500 MB, one-time)
• Starts a container that opens an outbound tunnel to bridge.agentry.run
• Mints a unique cryptographic identity for this server and persists it on the host

Adding a remote server

The same command works whether the target is your laptop, an EC2 instance, or a bare-metal box. Run it under SSH on the remote machine. The runtime dials out to agentry — no inbound port on the server.

Set the current server

If you only added one, the CLI uses it automatically. With more than one:

agentry server ls          # see all your servers
agentry server use homelab # set current
agentry server current     # confirm

The current server is what agentry mcp and the CLI's other one-shot commands target by default.

Provider notes

Hetzner

Hetzner Cloud is the recommended low-cost provider for a dedicated agentry server.

• CX22 (4 vCPU, 8 GB RAM) handles light prototyping for €4.50/mo.
• CX32 (8 vCPU, 16 GB RAM) is comfortable for production deploys and parallel sandboxes.

Ubuntu 24.04 LTS image. Install Docker, then run the Add this machine command from the dashboard. Done.

AWS / GCP / Azure

Any Linux VM works. EC2 t3.medium or equivalent is the lower bound; bigger is fine.

You'll spend more than Hetzner for similar resources, but the integration with the rest of your cloud (IAM, VPC peering, secret managers) may be worth it.

Bare metal / homelab

Anything that runs Docker works. NAS boxes, repurposed laptops, Raspberry Pis (4 or 5 with adequate RAM) — all fine. Just confirm you can docker run hello-world before adding agentry.

ARM vs amd64

The agentry runtime image is multi-arch (amd64 + arm64). Raspberry Pi 5 works. Older ARM SBCs may not have enough RAM for parallel sandboxes — budget 2 GB per active sandbox.

Local Docker Desktop (macOS / Windows)

Works fine. Docker Desktop handles the VM layer transparently. The runtime image is pulled into the Docker Desktop VM, not directly to your host.

Be aware that Docker Desktop's resource limits cap how much your sandboxes can use. Bump them in Docker Desktop → Settings → Resources if sandboxes feel slow.

When the connection drops

agentry servers auto-reconnect when their tunnel drops. The dashboard shows disconnected briefly, then flips back to connected when the tunnel re-establishes.

If a server stays disconnected for more than ~30 seconds:

• Check that the Docker container is running: docker ps | grep agentry-runtime
• Check the container's logs: docker logs agentry-runtime
• Common cause: network policy or proxy blocking outbound bridge.agentry.run:443.

See Connection + tunnel troubleshooting for more.

Removing a server

In the dashboard, click the server → Disconnect. This revokes the server's identity — existing sandboxes / deploys on that machine stop being routable. The runtime container keeps running locally; clean it up with docker stop agentry-runtime if you want.

Next

• Multiple servers — prototype on one, deploy on another.
• Bindings — wire services to this server.
• Wire up your harness — now point your AI tool at this server.