# Hosts — bring your own server

> Deploy to the managed PrimDB co-host by default, or enroll a server of your own with one command and deploy to it from the same dashboard and agent API. Discover and adopt containers already running on your host.

Every account starts on the managed **PrimDB** host — a shared co-host that PrimDB runs and maintains. You never configure it; you just deploy. When you want your deploys to land on hardware you control, enroll your own server and pin services to it. One control plane drives both, so the dashboard, the CLI, and the MCP API work the same wherever the container ends up running.

> **Honest note.** The shared PrimDB host is managed for you and cannot be edited or removed. Bringing your own server is optional — the platform host stays the default for every new app.

## Enroll a server

On the **Servers** page, add a host and give it a name. PrimDB returns a one-time install command with an enrollment token. Run it on your server (Docker required). The command starts a small PrimDB agent that connects back over an outbound WebSocket — no inbound ports to open. Once it reports in, the host flips to **active** and services can deploy to it.

```bash
# Shown once when you enroll a host. Run it on your server:
curl -fsSL https://relay.primdb.com/install/agent.sh | \
  PRIMDB_HOST_TOKEN=pdh_… sh
```

- The enrollment token is shown once. Only its hash is stored — treat it like a password.
- The agent detects and reports its own public IP, so it is a reliable target for a domain A-record.
- The agent connects outbound; you do not expose Docker or any port to the internet.
- Remove a host any time from the Servers page. Its services fall back to needing a new host on the next deploy.

## The fleet view

The Servers page is a fleet view: every host you have — the shared PrimDB co-host plus each server you enrolled — with the services that deploy to it. You see which server runs what at a glance, along with each host status and public IP.

## Pin a service to a host

A service deploys to the shared PrimDB host unless you pin it elsewhere. Set a deploy host when you create an app, or change it later from the service settings. The change takes effect on the next build. Routing is host-local: the agent on that host manages its own reverse proxy, so a service is reachable through the host it runs on.

## Discover what is already running

Enrolled a server that already runs containers? Discovery gives you a read-only inventory of the containers on that host that PrimDB does not manage. It only lists — it never starts, stops, or touches anything. Containers managed by another tool (Coolify, Docker Compose, Swarm) are flagged so you know before you act.

> **Honest note.** Discovery is blocked on the shared PrimDB host, since its containers belong to other tenants. It runs only on servers you enrolled.

## Adopt a container

Adopting a discovered container records it in PrimDB as an **observe-only** app pinned to that host. PrimDB gives you a handle to see it but never builds, deploys, or re-routes it — whatever runs the container today keeps running it. This is deliberately safe for containers another orchestrator manages: adopting one will not make two managers fight over it. An adopted service has no repo, so it cannot be deployed.

## Drive it over MCP

Every host action is also an account-level MCP tool, so an agent manages your fleet the same way you do from the dashboard. See [MCP](https://primdb.com/docs/mcp).

| Tool | What it does |
| --- | --- |
| `add_host` | Enroll a server and get the one-time install command. |
| `list_hosts` | List your hosts (shared platform host + your own) with status. |
| `set_service_host` | Pin a service to a host, or reset it to the platform default. |
| `discover_workloads` | Read-only inventory of non-PrimDB containers on one of your hosts. |
| `adopt_workload` | Adopt a discovered container as an observe-only app. |
| `remove_host` | Remove one of your hosts (the platform host cannot be removed). |

---

Source: https://primdb.com/docs/hosts