Multiple servers

Common setup once you outgrow one machine: a laptop or dev VM for prototyping, plus a sturdier box for production deploys.

Why have more than one

• Speed: prototype on a fast local machine; deploy on a steady remote one.
• Cost: small laptop SSD for dev work; pay for bigger storage only on the prod box.
• Isolation: a misbehaving sandbox can't take down production if prod is a separate machine.
• Geography: pick a prod server close to your users.

Add a second server

Same flow as adding the first — open the dashboard at app.agentry.run/clusters, click Add this machine, copy the one-line command, paste it on the new machine. Type the name you want (production, homelab, whatever) in the dashboard's Name field before copying the command — the name flows through the runtime identity.

Both servers now appear under Clusters in the dashboard.

Which server am I working on?

agentry server ls

Shows every server with a marker next to the current one:

* laptop         (connected, 3 sandboxes)
  production     (connected, 1 sandbox)
  homelab        (disconnected, 0 sandboxes)

The * marks the current — every CLI command and every new MCP session uses that one unless you say otherwise.

Switch:

agentry server use production

Now sandboxes you create go on production. Existing sandboxes on laptop keep working; you can still address them by ID.

Pin per-harness

If you want one harness session pinned to one server regardless of current, pass --server in the MCP config:

{
  "mcpServers": {
    "agentry-laptop": {
      "command": "agentry",
      "args": ["mcp", "--server", "laptop"]
    },
    "agentry-prod": {
      "command": "agentry",
      "args": ["mcp", "--server", "production"]
    }
  }
}

Now your harness sees agentry-laptop and agentry-prod as separate MCP servers. Useful when you want a single Cursor window to talk to both, or one Claude Code chat to be cleanly scoped to dev while another is scoped to prod.

Sandboxes are server-scoped

A sandbox lives on exactly one server. You can't move a sandbox across servers; if you want to recreate work elsewhere:

Read the source files in sandbox prototype and scaffold the same project structure in a new sandbox on the production server.

(Or use git — push from one sandbox, pull on the other.)

Deployments

You pick the deployment target at Deploy time. The form's Server dropdown lists every server in your org. Common pattern:

• Prototype + iterate on laptop.
• When ready, click Deploy → pick production → ship.

The deployment runs on the chosen server only. If laptop goes to sleep, deployments on production keep serving.

Bindings are per-server

If you bind MongoDB to laptop, production doesn't inherit the binding. A bind always targets your current server, so switch first, then bind — which also lets each environment use a different URL:

agentry server use production
agentry service bind mongodb        # prompts for the production URL

Repeat per server. Bindings are intentionally not auto-synced — different environments often want different credentials and endpoints.

A typical day

1. agentry server use laptop (or already current).
2. Prompt your harness to build something on the laptop.
3. Iterate in the sandbox preview.
4. When happy: the build → confirmed clean.
5. Open the dashboard. Pick the sandbox. Click Deploy. Pick production as the server. Click Deploy.
6. Share the production URL.

Total time: a couple of hours for a real app, minutes for a landing page.

Next

• Add a server — for adding the first or third.
• Ship an app — the deploy flow.
• Bindings — services live at the server level.