feat(scheduling): multi-node service placement + remote lifecycle (#54)

* feat(scheduling): multi-node service placement + remote container lifecycle

services.node_id pins a service to a node agent: explicit id, "auto"
(least-loaded online node), or "local"/empty for the local Docker host.

- DeploymentEngine gains a NodeRunner seam; ReconcileService routes
  pinned services to the agent's command queue (create_container with
  image/env/command/ports/volumes/labels/resource limits), tracked in
  container_instances with deterministic per-replica ids.
- Stop/start/restart/delete fan out to the pinned node — no more leaked
  remote containers on service delete.
- Agent create_container is idempotent (rm -f first) and honors restart
  policy, labels, memory/cpus, published+ephemeral ports, volumes, env.
- GET /nodes/options exposes id/name/status to authed users; full agent
  management stays admin-only.
- CLI services create/update --node, MCP node_id docs, OpenAPI
  node_id/node_name + /nodes/options, service-detail Placement section.

Ceilings: remote nodes run registry-pulled images only — git builds,
Traefik domains, and remote sleep detection stay local until
build-on-node and per-node ingress land.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* feat(scheduling): node cordon/drain + schedulable gate

- node_agents.schedulable column; "auto" placement and explicit pins skip
  cordoned nodes; already-pinned services keep running (reconcile is
  unaffected — cordon is not eviction).
- POST /agents/:id/cordon|uncordon|drain (admin). Drain cordons, removes
  every service container via the agent queue, and clears the services'
  pins so they redeploy on the local host. Requires the node online —
  an offline node can't acknowledge removals.
- CLI nodes cordon|uncordon|drain (drain confirm-gated), MCP
  containr_nodes_cordon|uncordon|drain, OpenAPI paths + schedulable
  field, node-detail page cordon badge + drain/cordon controls.
- Fix: re-registering an agent no longer resets auto_prune.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* feat(scheduling): remote registry pulls + post-run health check

- Dispatch payload carries the project owner's registry credentials for
  the image host; the agent docker-logins for the pull and logs out
  after, so private images deploy to remote nodes.
- Completed command payloads get their registry password scrubbed —
  secrets don't linger in agent_commands rows.
- Agent verifies the container is still running ~1.5s after docker run;
  crash-loops now fail the deployment with the container's last log
  lines instead of reporting "running" optimistically.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

ROADMAP2.md

@@ -252,24 +252,56 @@ and wired refs, one click or one CLI call.
 
 ## 7. Phase F — Nodes & infrastructure
 
-- [ ] **SSH bootstrap install** — `containr nodes add --ssh user@host` +
-  UI flow: one SSH session runs agent install (binary + systemd +
-  enroll token), SSH closed forever. dflow onboarding UX, agent-model
-  security.
-- [ ] **Mesh awareness** — agent detects + reports tailscale0/netbird0/
-  zt0 IPs at register; backend stores + displays. Optional
-  `TAILSCALE_AUTH_KEY` enroll-at-provision later.
-- [ ] **Node detail page** — placed services, telemetry history, agent
-  version + self-upgrade, **drain/cordon**, remove.
-- [ ] **Node housekeeping** — agent `prune` command (docker system
-  prune, bounded) + optional schedule (`setServerAutoCleanup` analog —
-  disk pressure is the #1 small-VPS killer).
-- [ ] **Multi-node scheduling** — wire `scheduling_rules` (table exists):
-  pin/spread/affinity, prefer-lowest-usage; deploy engine routes to
-  `services.node_id` via agent commands (agent already runs containers).
-- [ ] **Build-on-node** — agents currently `docker run` prebuilt images
-  only; extend agent to pull registry images (build stays central) —
-  private registry creds flow through Phase C.
+- [x] **SSH bootstrap install** — `containr nodes add <user@host>` mints an
+  enroll token, SSHes once (agent/key/default keys), runs
+  `GET /api/agents/install.sh | bash` remotely, closes the session.
+  `--print` emits the one-liner for manual runs; the Usage page shows the
+  same command. Agent binaries ship in the image under `/agents` and are
+  served at `/api/agents/download/{linux-amd64,linux-arm64}` (install
+  script falls back to GH releases). `cli/commands/nodes_add.go`,
+  `api/assets/install-agent.sh`, `agents.go:ServeInstallScript`/`ServeAgentBinary`.
+- [x] **Mesh awareness** — agent reports tailscale/netbird/wireguard/
+  zerotier interface IPs at register (`mesh` field, authoritative on
+  re-register), stored in `node_agents.metadata.mesh`, shown on the node
+  detail page. `TAILSCALE_AUTH_KEY` enroll-at-provision still open.
+- [x] **Node detail page** — `/nodes/:id` (admin): heartbeat telemetry
+  (cpu/mem sparklines over 1h/24h/7d via `GET /agents/:id/metrics`),
+  containers, command history, rename, auto-prune toggle, prune-now,
+  remove. Drain/cordon and self-upgrade deferred — they need
+  `services.node_id` routing which lands with multi-node scheduling.
+- [x] **Node housekeeping** — agent `prune` + `system_df` commands
+  (`docker system prune -af`, volumes excluded unless requested, optional
+  `--until`). `node_agents.auto_prune` + the health sweep enqueue a prune
+  at most once per 24h per node. Surfaces: `POST /agents/:id/prune`,
+  `nodes update --auto-prune` / `nodes prune [--volumes --until]` /
+  `nodes commands`, MCP `containr_nodes_update|prune|commands`
+  (confirm-gated), Usage-page per-node Prune button + auto toggle.
+  `cmd/agent/main.go`, `notification_producers.go:scheduleAutoPrune`.
+- [🟡] **Multi-node scheduling** — phase 1 shipped: `services.node_id`
+  pin (explicit / `auto` = least-loaded online / `local` = clear),
+  `NodeRunner` seam in the deploy engine routes reconcile to the agent's
+  command queue (`create_container` with image/env/cmd/ports/volumes/
+  labels/limits), `container_instances` inventory per (agent, service,
+  replica), remote stop/start/restart/delete fan-out, `GET
+  /nodes/options`, `--node` on services create/update + MCP + OpenAPI +
+  service-detail Placement section. Drain/cordon shipped:
+  `node_agents.schedulable`, `POST /agents/:id/cordon|uncordon|drain`
+  (drain evicts remote containers via the agent queue + unpins services
+  so they redeploy locally), `nodes cordon|uncordon|drain` CLI +
+  MCP (drain confirm-gated) + node-detail page controls; `auto` and
+  explicit pins skip cordoned nodes. Remote nodes run registry-pulled
+  images only — git builds, Traefik domains, and remote sleep are
+  documented ceilings. Remaining: `scheduling_rules` spread/affinity
+  policies, deployment status reported back from agent
+  results, per-node resource-aware `auto` (currently count-based).
+- [🟡] **Build-on-node** — private registry pulls shipped: the dispatch
+  payload carries the project owner's `registries` credentials for the
+  image host; the agent `docker login`s for the pull and logs out after,
+  and command payloads are scrubbed of passwords on completion. Agent
+  also verifies the container is still running ~1.5s after `run` so
+  crash-loops fail the deploy instead of reporting healthy. Remaining:
+  real builds on the node (source checkout + build daemon) — pulls
+  already work.
 - [ ] **IaC provisioning (ROADMAP §2.2, unchanged)** — Terraform/
   OpenTofu, `infra_connections`, Proxmox + AWS modules, + Hetzner module
   (dflow's second provider), cloud-init → auto-enroll.
@@ -380,12 +412,17 @@ and wired refs, one click or one CLI call.
 
 ## 9. Phase H — Migration & ecosystem
 
-- [ ] **Railway migrator** — `containr migrate railway --token --project
-  --dry-run`: Railway GraphQL → services/vars/domains → recreate via
-  PAT. Landing-page pitch: "off Railway in one command."
-- [ ] **dflow importer** — `containr migrate dflow` via Payload REST
-  export or Mongo dump: servers→nodes, projects, services(+vars/
-  domains/volumes), databases, templates. Onboards dflow refugees.
+- [x] **Railway migrator** — `containr migrate railway --token --project
+  --environment --into --dry-run`: Railway GraphQL (backboard) →
+  services (git-repo/image + command + replicas), variables, custom +
+  service domains → recreates via the Containr API. Project tokens and
+  account tokens both supported. `cli/commands/migrate.go`.
+- [x] **dflow importer** — `containr migrate dflow --url --api-key
+  --project --into --dry-run`: pages the Payload REST collections
+  (users API-Key auth) → services (app→git/web, docker→image,
+  database→typed image + DATABASE_URL for external providers),
+  variables (empty encrypted values flagged), bind volumes, domains.
+  Soft-deleted services excluded. `cli/commands/migrate_dflow.go`.
 - [x] **`containr import compose`** — `POST /projects/:id/import-compose`
   deploys a compose file straight into a project; CLI `import compose`,
   MCP tool, workspace import modal; project delete cascades to

app/backend/Dockerfile

@@ -13,6 +13,10 @@ ARG VERSION=dev
 RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo \
     -ldflags "-X containr/internal/api.Version=${VERSION}" -o main cmd/server/main.go
 
+# Node-agent binaries served by the API for SSH/bootstrap installs.
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /agents/containr-agent-linux-amd64 ./cmd/agent && \
+    CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o /agents/containr-agent-linux-arm64 ./cmd/agent
+
 # Build embedded Better Auth runtime dependencies
 FROM node:22-alpine AS auth-builder
 
@@ -35,6 +39,7 @@ WORKDIR /app
 
 COPY --from=go-builder /app/main ./main
 COPY --from=go-builder /app/migrations_goose ./migrations_goose
+COPY --from=go-builder /agents /agents
 COPY --from=auth-builder /auth ./auth
 
 RUN chown -R appuser:appgroup /app

app/backend/cmd/agent/main.go

@@ -167,6 +167,8 @@ func register(ctx context.Context, client *http.Client, cfg agentConfig) (string
 		"ip_address":   cfg.IP,
 		"port":         cfg.Port,
 		"capabilities": detectCapabilities(),
+		// Always send mesh so a removed interface clears stored state.
+		"mesh": detectMeshInterfaces(),
 	}
 	var response registerResponse
 	if err := postJSON(ctx, client, cfg, "/api/agents/register", payload, &response); err != nil {
@@ -246,11 +248,29 @@ func executeCommand(item command) (string, error) {
 		return runDocker("restart", commandTarget(item.Payload))
 	case "remove_container":
 		return runDocker("rm", "-f", commandTarget(item.Payload))
+	case "prune":
+		return dockerPrune(item.Payload)
+	case "system_df":
+		return runDocker("system", "df", "--format", "json")
 	default:
 		return "", fmt.Errorf("unsupported command type %q", item.Type)
 	}
 }
 
+// dockerPrune runs a bounded docker system prune. Volumes are excluded
+// unless the payload explicitly opts in — a stray volume prune destroys
+// database data.
+func dockerPrune(payload map[string]interface{}) (string, error) {
+	args := []string{"system", "prune", "-af"}
+	if boolValue(payload["volumes"]) {
+		args = append(args, "--volumes")
+	}
+	if until := stringValue(payload["until"]); until != "" {
+		args = append(args, "--filter", fmt.Sprintf("until=%s", until))
+	}
+	return runDocker(args...)
+}
+
 func createContainer(payload map[string]interface{}) (string, error) {
 	container, ok := payload["container"].(map[string]interface{})
 	if !ok {
@@ -263,7 +283,38 @@ func createContainer(payload map[string]interface{}) (string, error) {
 		return "", errors.New("container name and image are required")
 	}
 
-	args := []string{"run", "-d", "--name", name, "--restart", "unless-stopped"}
+	// Private registry: log in for the pull, then log back out so the
+	// credential doesn't linger in the node's docker config.
+	if reg, ok := container["registry"].(map[string]interface{}); ok {
+		if user := stringValue(reg["username"]); user != "" {
+			server := firstString(stringValue(reg["server"]), registryHostOf(image))
+			login := exec.Command("docker", "login", server, "-u", user, "--password-stdin")
+			login.Stdin = strings.NewReader(stringValue(reg["password"]))
+			if out, err := login.CombinedOutput(); err != nil {
+				return "", fmt.Errorf("registry login %s: %s", server, strings.TrimSpace(string(out)))
+			}
+			defer func() { _, _ = runDocker("logout", server) }()
+		}
+	}
+
+	// Redeploys reuse the deterministic name — clear the stale container
+	// first so `run` never fails on a name conflict.
+	_, _ = runDocker("rm", "-f", name)
+
+	args := []string{"run", "-d", "--name", name}
+	restart := firstString(stringValue(container["restart_policy"]), "unless-stopped")
+	args = append(args, "--restart", restart)
+	if labels, ok := container["labels"].(map[string]interface{}); ok {
+		for key, value := range labels {
+			args = append(args, "--label", fmt.Sprintf("%s=%v", key, value))
+		}
+	}
+	if mem := int64Value(container["memory"]); mem > 0 {
+		args = append(args, "--memory", fmt.Sprintf("%d", mem))
+	}
+	if cpus := floatValue(container["cpus"]); cpus > 0 {
+		args = append(args, "--cpus", fmt.Sprintf("%g", cpus))
+	}
 	if env, ok := container["environment"].(map[string]interface{}); ok {
 		for key, value := range env {
 			args = append(args, "-e", fmt.Sprintf("%s=%v", key, value))
@@ -278,8 +329,14 @@ func createContainer(payload map[string]interface{}) (string, error) {
 			hostPort := intValue(port["host_port"])
 			containerPort := intValue(port["container_port"])
 			protocol := firstString(stringValue(port["protocol"]), "tcp")
-			if hostPort > 0 && containerPort > 0 {
+			if containerPort <= 0 {
+				continue
+			}
+			if hostPort > 0 {
 				args = append(args, "-p", fmt.Sprintf("%d:%d/%s", hostPort, containerPort, protocol))
+			} else {
+				// Ephemeral host port — docker picks the binding.
+				args = append(args, "-p", fmt.Sprintf("%d/%s", containerPort, protocol))
 			}
 		}
 	}
@@ -301,7 +358,33 @@ func createContainer(payload map[string]interface{}) (string, error) {
 		}
 	}
 	args = append(args, image)
-	return runDocker(args...)
+	if cmd, ok := container["command"].([]interface{}); ok {
+		for _, arg := range cmd {
+			args = append(args, stringValue(arg))
+		}
+	}
+	if _, err := runDocker(args...); err != nil {
+		return "", err
+	}
+	// docker run -d returns before the entrypoint fails — a crash-looping
+	// service would be reported healthy. Give it a moment, then verify.
+	time.Sleep(1500 * time.Millisecond)
+	state, _ := runDocker("inspect", "-f", "{{.State.Status}}", name)
+	if state != "running" {
+		logs, _ := runDocker("logs", "--tail", "5", name)
+		return "", fmt.Errorf("container %s is %q after start: %s", name, state, logs)
+	}
+	return name, nil
+}
+
+// registryHostOf mirrors the server's registryHost: first path segment with
+// a "." or ":" is a registry host; bare names mean Docker Hub.
+func registryHostOf(imageRef string) string {
+	parts := strings.Split(imageRef, "/")
+	if len(parts) > 1 && (strings.Contains(parts[0], ".") || strings.Contains(parts[0], ":")) {
+		return parts[0]
+	}
+	return "docker.io"
 }
 
 func commandTarget(payload map[string]interface{}) string {
@@ -354,6 +437,42 @@ func detectCapabilities() capabilities {
 	}
 }
 
+// detectMeshInterfaces reports overlay-network interface IPs (tailscale,
+// netbird, zerotier, wireguard) so the backend can display reachable
+// mesh addresses alongside the primary IP.
+func detectMeshInterfaces() map[string]string {
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		return nil
+	}
+	mesh := map[string]string{}
+	for _, iface := range ifaces {
+		name := strings.ToLower(iface.Name)
+		isMesh := strings.HasPrefix(name, "tailscale") || strings.HasPrefix(name, "ts.") ||
+			strings.HasPrefix(name, "netbird") || strings.HasPrefix(name, "wt") ||
+			strings.HasPrefix(name, "zt") || strings.HasPrefix(name, "wg")
+		if !isMesh || iface.Flags&net.FlagUp == 0 {
+			continue
+		}
+		addrs, err := iface.Addrs()
+		if err != nil {
+			continue
+		}
+		for _, addr := range addrs {
+			ip, _, err := net.ParseCIDR(addr.String())
+			if err != nil || ip.IsLoopback() {
+				continue
+			}
+			if v4 := ip.To4(); v4 != nil {
+				mesh[iface.Name] = v4.String()
+			} else if _, exists := mesh[iface.Name]; !exists {
+				mesh[iface.Name] = ip.String()
+			}
+		}
+	}
+	return mesh
+}
+
 func collectResources(ip string) nodeResources {
 	mem := readMemory()
 	storage := readStorage("/")
@@ -564,3 +683,35 @@ func boolValue(value interface{}) bool {
 	typed, _ := value.(bool)
 	return typed
 }
+
+func int64Value(value interface{}) int64 {
+	switch typed := value.(type) {
+	case int64:
+		return typed
+	case int:
+		return int64(typed)
+	case float64:
+		return int64(typed)
+	case json.Number:
+		out, _ := typed.Int64()
+		return out
+	default:
+		return 0
+	}
+}
+
+func floatValue(value interface{}) float64 {
+	switch typed := value.(type) {
+	case float64:
+		return typed
+	case int:
+		return float64(typed)
+	case int64:
+		return float64(typed)
+	case json.Number:
+		out, _ := typed.Float64()
+		return out
+	default:
+		return 0
+	}
+}

app/backend/internal/api/agents.go

@@ -6,13 +6,16 @@ import (
 	"crypto/sha256"
 	"crypto/subtle"
 	"database/sql"
+	_ "embed"
 	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"log"
 	"math"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -36,6 +39,8 @@ type NodeAgent struct {
 	Capabilities  AgentCapabilities      `json:"capabilities"`
 	Resources     NodeResources          `json:"resources"`
 	LastHeartbeat time.Time              `json:"last_heartbeat"`
+	AutoPrune     bool                   `json:"auto_prune"`
+	Schedulable   bool                   `json:"schedulable"`
 	CreatedAt     time.Time              `json:"created_at"`
 	UpdatedAt     time.Time              `json:"updated_at"`
 	Metadata      map[string]interface{} `json:"metadata"`
@@ -225,16 +230,38 @@ func unmarshalRaw(raw pqtype.NullRawMessage, dst interface{}) {
 	}
 }
 
+// ListNodeOptions returns the minimal id/name/status list used by the service
+// placement picker — available to any authenticated user (no hostnames, IPs,
+// or telemetry).
+func (h *NodeAgentHandler) ListNodeOptions(c *gin.Context) {
+	rows, err := h.q.ListAgents(c.Request.Context())
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to list nodes"})
+		return
+	}
+	options := make([]gin.H, 0, len(rows))
+	for _, row := range rows {
+		options = append(options, gin.H{
+			"id":     row.ID,
+			"name":   row.Name,
+			"status": row.Status.String,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"nodes": options})
+}
+
 func agentFromRow(row sqlcdb.NodeAgent) NodeAgent {
 	agent := NodeAgent{
-		ID:        row.ID,
-		Name:      row.Name,
-		Hostname:  row.Hostname,
-		IPAddress: row.IpAddress,
-		Port:      int(row.Port),
-		Status:    row.Status.String,
-		Version:   row.Version.String,
-		Metadata:  map[string]interface{}{},
+		ID:          row.ID,
+		Name:        row.Name,
+		Hostname:    row.Hostname,
+		IPAddress:   row.IpAddress,
+		Port:        int(row.Port),
+		Status:      row.Status.String,
+		Version:     row.Version.String,
+		AutoPrune:   row.AutoPrune,
+		Schedulable: row.Schedulable,
+		Metadata:    map[string]interface{}{},
 	}
 	if row.LastHeartbeat.Valid {
 		agent.LastHeartbeat = row.LastHeartbeat.Time
@@ -327,6 +354,7 @@ func (h *NodeAgentHandler) RegisterAgent(c *gin.Context) {
 		Port         int               `json:"port" binding:"required"`
 		Capabilities AgentCapabilities `json:"capabilities" binding:"required"`
 		AuthToken    string            `json:"auth_token"`
+		Mesh         map[string]string `json:"mesh"`
 	}
 
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -341,12 +369,28 @@ func (h *NodeAgentHandler) RegisterAgent(c *gin.Context) {
 	}
 
 	ctx := c.Request.Context()
+	metadata := map[string]interface{}{}
+	// req.Mesh is authoritative when present (newer agents always send it,
+	// possibly empty); nil means an older agent — keep any stored value.
+	if req.Mesh != nil {
+		metadata["mesh"] = req.Mesh
+	}
 
 	// Re-registering an existing host updates it in place.
 	if existing, err := h.q.GetAgentByHostAndIP(ctx, sqlcdb.GetAgentByHostAndIPParams{
 		Hostname:  req.Hostname,
 		IpAddress: req.IPAddress,
 	}); err == nil {
+		if existing.Metadata.Valid && len(existing.Metadata.RawMessage) > 0 {
+			var prev map[string]interface{}
+			if err := json.Unmarshal(existing.Metadata.RawMessage, &prev); err == nil {
+				for k, v := range prev {
+					if _, ok := metadata[k]; !ok {
+						metadata[k] = v
+					}
+				}
+			}
+		}
 		updated, err := h.q.UpdateAgent(ctx, sqlcdb.UpdateAgentParams{
 			ID:            existing.ID,
 			Name:          req.Name,
@@ -358,7 +402,9 @@ func (h *NodeAgentHandler) RegisterAgent(c *gin.Context) {
 			Capabilities:  rawJSON(req.Capabilities),
 			Resources:     existing.Resources,
 			LastHeartbeat: sql.NullTime{Time: time.Now(), Valid: true},
-			Metadata:      existing.Metadata,
+			Metadata:      rawJSON(metadata),
+			AutoPrune:     existing.AutoPrune,
+			Schedulable:   existing.Schedulable,
 		})
 		if err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to update agent"})
@@ -408,7 +454,7 @@ func (h *NodeAgentHandler) RegisterAgent(c *gin.Context) {
 		Capabilities:  rawJSON(req.Capabilities),
 		Resources:     rawJSON(resources),
 		LastHeartbeat: sql.NullTime{Time: time.Now(), Valid: true},
-		Metadata:      rawJSON(map[string]interface{}{}),
+		Metadata:      rawJSON(metadata),
 	})
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create agent"})
@@ -489,6 +535,8 @@ func (h *NodeAgentHandler) UpdateAgent(c *gin.Context) {
 		Resources:     rawJSON(agent.Resources),
 		LastHeartbeat: sql.NullTime{Time: agent.LastHeartbeat, Valid: !agent.LastHeartbeat.IsZero()},
 		Metadata:      rawJSON(agent.Metadata),
+		AutoPrune:     agent.AutoPrune,
+		Schedulable:   agent.Schedulable,
 	})
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to update agent"})
@@ -516,6 +564,8 @@ func applyAgentUpdates(agent *NodeAgent, updates map[string]interface{}) {
 	remarshal("capabilities", &agent.Capabilities)
 	remarshal("resources", &agent.Resources)
 	remarshal("metadata", &agent.Metadata)
+	remarshal("auto_prune", &agent.AutoPrune)
+	remarshal("schedulable", &agent.Schedulable)
 }
 
 // DeleteAgent removes an agent
@@ -650,9 +700,40 @@ func (h *NodeAgentHandler) CompleteCommand(c *gin.Context) {
 		h.updateContainerStatusAfterCommand(ctx, out)
 	}
 
+	// Command payloads can carry registry credentials — scrub them once the
+	// command is settled so secrets don't linger in the queue rows.
+	scrubCommandSecrets(ctx, h.q, commandID, command.Payload)
+
 	c.JSON(http.StatusOK, gin.H{"command": out})
 }
 
+// scrubCommandSecrets rewrites a completed command's payload with any
+// registry password blanked. Best-effort — a failed scrub leaves the row.
+func scrubCommandSecrets(ctx context.Context, q *sqlcdb.Queries, commandID string, payload pqtype.NullRawMessage) {
+	if !payload.Valid || len(payload.RawMessage) == 0 {
+		return
+	}
+	var doc map[string]interface{}
+	if err := json.Unmarshal(payload.RawMessage, &doc); err != nil {
+		return
+	}
+	container, ok := doc["container"].(map[string]interface{})
+	if !ok {
+		return
+	}
+	reg, ok := container["registry"].(map[string]interface{})
+	if !ok || reg["password"] == nil {
+		return
+	}
+	reg["password"] = "***"
+	if err := q.ScrubCommandPayload(ctx, sqlcdb.ScrubCommandPayloadParams{
+		ID:      commandID,
+		Payload: rawJSON(doc),
+	}); err != nil {
+		log.Printf("agents: scrub command %s payload: %v", commandID, err)
+	}
+}
+
 func (h *NodeAgentHandler) updateContainerStatusAfterCommand(ctx context.Context, command AgentCommand) {
 	row, err := h.q.GetContainer(ctx, *command.ContainerID)
 	if err != nil {
@@ -803,6 +884,33 @@ func (h *NodeAgentHandler) CreateContainer(c *gin.Context) {
 	c.JSON(http.StatusCreated, gin.H{"container": container})
 }
 
+// PruneAgent enqueues a bounded `docker system prune -af` command. Volumes
+// stay unless the caller explicitly opts in.
+func (h *NodeAgentHandler) PruneAgent(c *gin.Context) {
+	agentID := c.Param("id")
+	if _, err := h.q.GetAgent(c.Request.Context(), agentID); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Agent not found"})
+		return
+	}
+	var req struct {
+		Until   string `json:"until"`   // e.g. "168h" — only prune objects older than this
+		Volumes bool   `json:"volumes"` // destructive — off by default
+	}
+	_ = c.ShouldBindJSON(&req)
+
+	command, err := h.q.CreateCommand(c.Request.Context(), sqlcdb.CreateCommandParams{
+		ID:          uuid.New().String(),
+		Type:        "prune",
+		NodeAgentID: agentID,
+		Payload:     rawJSON(map[string]interface{}{"until": req.Until, "volumes": req.Volumes}),
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to enqueue prune"})
+		return
+	}
+	c.JSON(http.StatusAccepted, gin.H{"command": command})
+}
+
 // ExecuteCommand executes a command on an agent
 func (h *NodeAgentHandler) ExecuteCommand(c *gin.Context) {
 	agentID := c.Param("id")
@@ -1214,9 +1322,45 @@ func (h *NodeAgentHandler) SetupPublicRoutes(router *gin.RouterGroup) {
 		agents.POST("/heartbeat", h.SendHeartbeat)
 		agents.GET("/:id/commands", h.GetPendingCommandsForAgent)
 		agents.POST("/:id/commands/:commandId/result", h.CompleteCommand)
+
+		// Bootstrap surface — the install script and agent binaries are
+		// public; the enroll token is the actual secret.
+		agents.GET("/install.sh", h.ServeInstallScript)
+		agents.GET("/download/:platform", h.ServeAgentBinary)
 	}
 }
 
+//go:embed assets/install-agent.sh
+var agentInstallScript string
+
+// ServeInstallScript returns the agent bootstrap script. The script
+// downloads the binary from this instance first, GH releases second.
+func (h *NodeAgentHandler) ServeInstallScript(c *gin.Context) {
+	c.Data(http.StatusOK, "text/x-sh", []byte(agentInstallScript))
+}
+
+// ServeAgentBinary streams a bundled agent binary. Images ship the
+// linux binaries under CONTAINR_AGENT_BIN_DIR (default /agents).
+func (h *NodeAgentHandler) ServeAgentBinary(c *gin.Context) {
+	platform := c.Param("platform")
+	if platform != "linux-amd64" && platform != "linux-arm64" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "unsupported platform"})
+		return
+	}
+	dir := os.Getenv("CONTAINR_AGENT_BIN_DIR")
+	if dir == "" {
+		dir = "/agents"
+	}
+	path := filepath.Join(dir, "containr-agent-"+platform)
+	info, err := os.Stat(path)
+	if err != nil || info.IsDir() {
+		c.JSON(http.StatusNotFound, gin.H{"error": "no bundled binary for " + platform})
+		return
+	}
+	c.Header("Content-Disposition", `attachment; filename="containr-agent"`)
+	c.File(path)
+}
+
 // SetupAdminRoutes registers dashboard/control agent routes. Command
 // history and container details can leak sensitive output, so these stay
 // admin-only rather than joining the public read group.
@@ -1243,8 +1387,94 @@ func (h *NodeAgentHandler) SetupAdminRoutes(router *gin.RouterGroup) {
 		agents.DELETE("/:id/containers/:containerId", h.ContainerAction)
 
 		agents.GET("/:id/metrics", h.GetAgentMetrics)
+		agents.POST("/:id/cordon", h.CordonAgent)
+		agents.POST("/:id/uncordon", h.UncordonAgent)
+		agents.POST("/:id/drain", h.DrainAgent)
+		agents.POST("/:id/prune", h.PruneAgent)
 		agents.POST("/:id/commands", h.ExecuteCommand)
 		agents.GET("/:id/commands", h.GetAgentCommands)
 		agents.GET("/:id/commands/:commandId", h.GetCommandStatus)
 	}
 }
+
+// setSchedulable flips the node's scheduling gate. Cordoned nodes keep
+// running their placed replicas but take no new pins or `auto` placements.
+func (h *NodeAgentHandler) setSchedulable(c *gin.Context, schedulable bool) {
+	id := c.Param("id")
+	if _, err := h.q.GetAgent(c.Request.Context(), id); err != nil {
+		respondError(c, http.StatusNotFound, "NOT_FOUND", "Agent not found")
+		return
+	}
+	if err := h.q.SetAgentSchedulable(c.Request.Context(), sqlcdb.SetAgentSchedulableParams{
+		ID: id, Schedulable: schedulable,
+	}); err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL", "failed to update node")
+		return
+	}
+	LogAuditWithRequest(c, "node", id, map[bool]string{true: "uncordon", false: "cordon"}[schedulable], nil)
+	c.JSON(http.StatusOK, gin.H{"id": id, "schedulable": schedulable})
+}
+
+// CordonAgent blocks new placements on the node (explicit pins and `auto`).
+func (h *NodeAgentHandler) CordonAgent(c *gin.Context) { h.setSchedulable(c, false) }
+
+// UncordonAgent re-opens the node for placement.
+func (h *NodeAgentHandler) UncordonAgent(c *gin.Context) { h.setSchedulable(c, true) }
+
+// DrainAgent cordons the node, removes every service container via the agent
+// command queue, and clears the affected services' pins — they fall back to
+// the local host on next deploy and can be re-pinned to another node.
+// Requires the node to be online; an offline node can't acknowledge the
+// removals.
+func (h *NodeAgentHandler) DrainAgent(c *gin.Context) {
+	ctx := c.Request.Context()
+	id := c.Param("id")
+	agent, err := h.q.GetAgent(ctx, id)
+	if err != nil {
+		respondError(c, http.StatusNotFound, "NOT_FOUND", "Agent not found")
+		return
+	}
+	if agent.Status.String != "online" {
+		respondError(c, http.StatusConflict, "NODE_OFFLINE",
+			"node is not online — reconnect it, or remove the containers manually")
+		return
+	}
+	if err := h.q.SetAgentSchedulable(ctx, sqlcdb.SetAgentSchedulableParams{
+		ID: id, Schedulable: false,
+	}); err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL", "failed to cordon node")
+		return
+	}
+
+	runner := &agentNodeRunner{q: h.q}
+	rows, err := h.q.ListContainersForAgent(ctx, id)
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL", "failed to list node containers")
+		return
+	}
+	services := map[string]bool{}
+	for _, row := range rows {
+		services[row.ServiceID] = true
+	}
+	var drained int
+	var firstErr error
+	for serviceID := range services {
+		if err := runner.RemoveService(ctx, serviceID, id); err != nil {
+			if firstErr == nil {
+				firstErr = err
+			}
+			continue
+		}
+		drained += 1
+	}
+	unpinned, _ := h.q.ClearServiceNodePins(ctx, sql.NullString{String: id, Valid: true})
+	if firstErr != nil {
+		respondError(c, http.StatusBadGateway, "DRAIN_PARTIAL",
+			fmt.Sprintf("drained %d service(s), unpinned %d — one failed: %v", drained, unpinned, firstErr))
+		return
+	}
+	LogAuditWithRequest(c, "node", id, "drain", map[string]interface{}{
+		"services": drained, "unpinned": unpinned,
+	})
+	c.JSON(http.StatusOK, gin.H{"id": id, "schedulable": false, "services_drained": drained, "services_unpinned": unpinned})
+}

app/backend/internal/api/assets/install-agent.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Containr node agent installer.
+#   curl -fsSL <api>/api/agents/install.sh | bash -s -- --url <api> --token <enroll-token>
+#
+# One-shot: downloads the agent binary from the Containr instance (or GH
+# releases as fallback), writes a systemd unit, starts it. SSH is never
+# needed again — the agent heartbeats and polls commands outbound.
+set -euo pipefail
+
+API_URL=""
+TOKEN=""
+AGENT_NAME=""
+VERSION=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --url) API_URL="$2"; shift 2 ;;
+    --token) TOKEN="$2"; shift 2 ;;
+    --name) AGENT_NAME="$2"; shift 2 ;;
+    --version) VERSION="$2"; shift 2 ;;
+    *) echo "unknown flag: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$API_URL" ] || { echo "--url is required" >&2; exit 2; }
+[ -n "$TOKEN" ] || { echo "--token is required (create one: containr nodes tokens create)" >&2; exit 2; }
+API_URL="${API_URL%/}"
+API_URL="${API_URL%/api/v1}"
+API_URL="${API_URL%/api}"
+
+info() { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
+err()  { printf '\033[1;31mError:\033[0m %s\n' "$*" >&2; }
+
+[ "$(id -u)" = "0" ] || { err "run as root (sudo bash -s -- --url … --token …)"; exit 1; }
+command -v docker >/dev/null 2>&1 || { err "docker not found"; exit 1; }
+command -v curl >/dev/null 2>&1 || { err "curl not found"; exit 1; }
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64|amd64) ARCH=amd64 ;;
+  aarch64|arm64) ARCH=arm64 ;;
+  *) err "unsupported architecture: $ARCH"; exit 1 ;;
+esac
+
+BIN=/usr/local/bin/containr-agent
+info "downloading containr-agent (linux/$ARCH)"
+if ! curl -fsSL "$API_URL/api/agents/download/linux-$ARCH" -o "$BIN" 2>/dev/null; then
+  info "instance has no bundled binary — trying GitHub releases"
+  REF="${VERSION:-latest}"
+  if [ "$REF" = "latest" ]; then
+    DL="https://github.com/Dvorinka/Containr/releases/latest/download/containr-agent-linux-$ARCH"
+  else
+    DL="https://github.com/Dvorinka/Containr/releases/download/$REF/containr-agent-linux-$ARCH"
+  fi
+  curl -fsSL "$DL" -o "$BIN" || { err "agent download failed"; exit 1; }
+fi
+chmod +x "$BIN"
+
+UNIT=/etc/systemd/system/containr-agent.service
+info "writing systemd unit"
+cat > "$UNIT" <<UNIT
+[Unit]
+Description=Containr node agent
+After=docker.service network-online.target
+Wants=network-online.target
+Requires=docker.service
+
+[Service]
+Environment=CONTAINR_API_URL=$API_URL
+Environment=CONTAINR_AGENT_AUTH_TOKEN=$TOKEN
+Environment=CONTAINR_AGENT_NAME=${AGENT_NAME:-$(hostname)}
+Restart=always
+RestartSec=5
+ExecStart=$BIN
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+
+systemctl daemon-reload
+systemctl enable --now containr-agent
+info "agent installed and started — it should appear in Containr within ~15s"

app/backend/internal/api/deployments.go

@@ -421,6 +421,20 @@ func runDeploymentAndSyncWithImage(
 		maintURL = maintenanceURL(db)
 	}
 
+	// Node-pinned services dispatch to the agent's command queue. Builds run
+	// on the local host, so remote placement only works for registry-pulled
+	// images — git-sourced and rollback deploys fail fast with that message.
+	nodeID := serviceNodeID(db, service.ID)
+	if nodeID != "" && (service.GitRepo != "" || imageOverride != "") {
+		failedAt := time.Now()
+		msg := "service is pinned to a remote node but remote nodes only run registry-pulled images (git builds and rollbacks stay local — build-on-node is not yet supported)"
+		_, _ = db.Exec(
+			`UPDATE deployments SET status = 'failed', error = $1, completed_at = $2, updated_at = $2 WHERE id = $3`,
+			msg, failedAt, dbDeployment.ID,
+		)
+		return
+	}
+
 	deployReq := &deployment.DeploymentRequest{
 		ProjectID:   service.ProjectID.String(),
 		ServiceID:   service.ID.String(),
@@ -447,6 +461,7 @@ func runDeploymentAndSyncWithImage(
 			Maintenance:    maintenanceMode,
 			MaintenanceURL: maintURL,
 			BasicAuthUsers: basicAuthUsers,
+			NodeID:         nodeID,
 		},
 		Trigger: deployment.TriggerConfig{
 			Type:      req.Trigger,

app/backend/internal/api/noderunner.go

@@ -0,0 +1,304 @@
+package api
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+
+	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
+	"containr/internal/deployment"
+)
+
+// agentNodeRunner implements deployment.NodeRunner by dispatching container
+// lifecycle commands to a node agent's command queue and waiting for the
+// reported result. Remote nodes have no Traefik — domains stay local-only
+// until per-node ingress lands.
+type agentNodeRunner struct {
+	q  *sqlcdb.Queries
+	db *database.DB
+}
+
+func newAgentNodeRunner(db *database.DB) *agentNodeRunner {
+	return &agentNodeRunner{q: sqlcdb.New(db.DB), db: db}
+}
+
+// remoteContainerID is deterministic per (agent, service, replica) so redeploys
+// update the same inventory row instead of accumulating stale ones.
+func remoteContainerID(agentID, serviceID string, replica int) string {
+	sum := sha256.Sum256([]byte(agentID + "|" + serviceID + "|" + fmt.Sprint(replica)))
+	return fmt.Sprintf("%x-%x-%x-%x-%x", sum[0:4], sum[4:6], sum[6:8], sum[8:10], sum[10:16])
+}
+
+func remoteContainerName(serviceID string, replica int) string {
+	return fmt.Sprintf("containr-%s-%d", serviceID, replica)
+}
+
+func (r *agentNodeRunner) ReconcileOnNode(ctx context.Context, spec deployment.RuntimeSpec) (*deployment.RuntimeState, error) {
+	agent, err := r.q.GetAgent(ctx, spec.NodeID)
+	if err != nil {
+		return nil, fmt.Errorf("node %s not found", spec.NodeID)
+	}
+	if !agent.Status.Valid || agent.Status.String != "online" {
+		return nil, fmt.Errorf("node %s is %s — heartbeats resume scheduling when it reconnects", agent.Name, agent.Status.String)
+	}
+	if len(spec.Domains) > 0 || spec.Domain != "" {
+		return nil, fmt.Errorf("domains are routed by the local Traefik — remove the service's domains or run it on the local node")
+	}
+
+	replicas := spec.Replicas
+	if replicas < 1 {
+		replicas = 1
+	}
+
+	// Retire replicas above the desired count using inventory rows.
+	prefix := fmt.Sprintf("containr-%s-", spec.ServiceID)
+	existing, _ := r.q.ListContainersForAgent(ctx, spec.NodeID)
+	for _, row := range existing {
+		if row.ServiceID != spec.ServiceID || !strings.HasPrefix(row.Name, prefix) {
+			continue
+		}
+		replica, err := strconv.Atoi(strings.TrimPrefix(row.Name, prefix))
+		if err == nil && replica >= replicas {
+			if cmdErr := r.enqueueAndWait(ctx, spec.NodeID, "", "remove_container",
+				map[string]interface{}{"container_name": row.Name}); cmdErr != nil {
+				return nil, fmt.Errorf("remove stale replica %s: %w", row.Name, cmdErr)
+			}
+			_ = r.q.UpdateContainerStatus(ctx, sqlcdb.UpdateContainerStatusParams{
+				ID:     row.ID,
+				Status: rawJSON(map[string]interface{}{"state": "removed"}),
+			})
+		}
+	}
+
+	state := &deployment.RuntimeState{Desired: replicas, Status: "running"}
+	for i := 0; i < replicas; i++ {
+		name := remoteContainerName(spec.ServiceID, i)
+		containerID := remoteContainerID(spec.NodeID, spec.ServiceID, i)
+
+		ports := []interface{}{}
+		if spec.Port > 0 {
+			hostPort := spec.PublishedPort // 0 → ephemeral on the node
+			if i > 0 {
+				hostPort = 0 // only replica 0 claims the preferred host port
+			}
+			ports = append(ports, map[string]interface{}{
+				"published":      true,
+				"host_port":      hostPort,
+				"container_port": spec.Port,
+				"protocol":       "tcp",
+			})
+		}
+		volumes := make([]interface{}, 0, len(spec.Volumes))
+		for _, v := range spec.Volumes {
+			volumes = append(volumes, map[string]interface{}{
+				"source": v.Source, "target": v.Destination, "read_only": v.ReadOnly,
+			})
+		}
+		env := map[string]interface{}{}
+		for k, v := range spec.Env {
+			env[k] = v
+		}
+		restart := spec.RestartPolicy
+		if restart == "" {
+			restart = "unless-stopped"
+		}
+		cmd := make([]interface{}, 0, len(spec.Command))
+		for _, arg := range spec.Command {
+			cmd = append(cmd, arg)
+		}
+		container := map[string]interface{}{
+			"name":           name,
+			"image":          spec.Image,
+			"command":        cmd,
+			"environment":    env,
+			"registry":       r.pullCredentials(spec.ProjectID, spec.Image),
+			"ports":          ports,
+			"volumes":        volumes,
+			"restart_policy": restart,
+			"memory":         spec.MemoryBytes,
+			"cpus":           float64(spec.NanoCPUs) / 1e9,
+			"labels": map[string]interface{}{
+				"containr.managed": "true",
+				"containr.project": spec.ProjectID,
+				"containr.service": spec.ServiceID,
+				"containr.replica": fmt.Sprint(i),
+				"containr.node":    spec.NodeID,
+			},
+		}
+
+		_ = r.q.UpsertServiceContainer(ctx, sqlcdb.UpsertServiceContainerParams{
+			ID:            containerID,
+			Name:          name,
+			Image:         spec.Image,
+			ProjectID:     spec.ProjectID,
+			ServiceID:     spec.ServiceID,
+			NodeAgentID:   spec.NodeID,
+			Status:        rawJSON(map[string]interface{}{"state": "created", "health": "none"}),
+			Resources:     rawJSON(map[string]interface{}{"memory": spec.MemoryBytes, "cpus": float64(spec.NanoCPUs) / 1e9}),
+			Ports:         rawJSON(ports),
+			Environment:   rawJSON(env),
+			Volumes:       rawJSON(volumes),
+			Networks:      rawJSON([]string{}),
+			RestartPolicy: rawJSON(map[string]interface{}{"name": restart}),
+			HealthCheck:   rawJSON(map[string]interface{}{"path": spec.HealthPath}),
+		})
+
+		if err := r.enqueueAndWait(ctx, spec.NodeID, containerID, "create_container",
+			map[string]interface{}{"container": container}); err != nil {
+			return nil, fmt.Errorf("replica %d on %s: %w", i, agent.Name, err)
+		}
+		_ = r.q.UpdateContainerStatus(ctx, sqlcdb.UpdateContainerStatusParams{
+			ID:     containerID,
+			Status: rawJSON(map[string]interface{}{"state": "running", "health": "none"}),
+		})
+		state.Containers = append(state.Containers, deployment.RuntimeContainer{
+			ID: containerID, Name: name, State: "running", Replica: i,
+		})
+	}
+	return state, nil
+}
+
+// pullCredentials resolves the project owner's registry auth for the image
+// host so private images pull on remote nodes. Empty map → anonymous pull.
+func (r *agentNodeRunner) pullCredentials(projectID, imageRef string) map[string]interface{} {
+	var ownerID string
+	if err := r.db.QueryRow(
+		`SELECT owner_id FROM projects WHERE id = $1`, projectID,
+	).Scan(&ownerID); err != nil {
+		return map[string]interface{}{}
+	}
+	auth := registryAuthFor(r.db, ownerID, imageRef)
+	if auth.Username == "" {
+		return map[string]interface{}{}
+	}
+	return map[string]interface{}{
+		"server":   auth.ServerAddress,
+		"username": auth.Username,
+		"password": auth.Password,
+	}
+}
+
+// ControlService fans a lifecycle action out to every replica row the
+// service has on the agent. Actions map onto the agent's container commands;
+// "remove" also tombstones the inventory row.
+func (r *agentNodeRunner) ControlService(ctx context.Context, serviceID, agentID, action string) error {
+	cmdType := map[string]string{
+		"start":   "start_container",
+		"stop":    "stop_container",
+		"restart": "restart_container",
+		"remove":  "remove_container",
+	}[action]
+	if cmdType == "" {
+		return fmt.Errorf("unsupported action %q", action)
+	}
+	rows, err := r.q.ListContainersForAgent(ctx, agentID)
+	if err != nil {
+		return err
+	}
+	removed := map[string]interface{}{"state": "removed"}
+	for _, row := range rows {
+		if row.ServiceID != serviceID {
+			continue
+		}
+		if err := r.enqueueAndWait(ctx, agentID, row.ID, cmdType,
+			map[string]interface{}{"container_name": row.Name}); err != nil {
+			return fmt.Errorf("%s %s on node: %w", action, row.Name, err)
+		}
+		if action == "remove" {
+			_ = r.q.UpdateContainerStatus(ctx, sqlcdb.UpdateContainerStatusParams{
+				ID: row.ID, Status: rawJSON(removed)})
+		}
+	}
+	return nil
+}
+
+// RemoveService tears down every replica of the service on the agent and
+// clears the inventory rows.
+func (r *agentNodeRunner) RemoveService(ctx context.Context, serviceID, agentID string) error {
+	if err := r.ControlService(ctx, serviceID, agentID, "remove"); err != nil {
+		return err
+	}
+	return r.q.DeleteServiceContainersOnAgent(ctx, sqlcdb.DeleteServiceContainersOnAgentParams{
+		NodeAgentID: agentID,
+		ServiceID:   serviceID,
+	})
+}
+
+// enqueueAndWait pushes a command to the agent's queue and polls for the
+// reported result. Agents poll on their own interval (≥5s), so this blocks —
+// it runs inside the deploy queue worker, never on a request path.
+func (r *agentNodeRunner) enqueueAndWait(ctx context.Context, agentID, containerID, cmdType string, payload map[string]interface{}) error {
+	var cid sql.NullString
+	if containerID != "" {
+		cid = sql.NullString{String: containerID, Valid: true}
+	}
+	cmd, err := r.q.CreateCommand(ctx, sqlcdb.CreateCommandParams{
+		ID:          uuid.New().String(),
+		Type:        cmdType,
+		NodeAgentID: agentID,
+		ContainerID: cid,
+		Payload:     rawJSON(payload),
+	})
+	if err != nil {
+		return err
+	}
+
+	deadline := time.Now().Add(8 * time.Minute) // image pulls on a cold node
+	for {
+		row, err := r.q.GetCommandForAgent(ctx, sqlcdb.GetCommandForAgentParams{
+			ID:          cmd.ID,
+			NodeAgentID: agentID,
+		})
+		if err == nil {
+			switch row.Status.String {
+			case "completed":
+				return nil
+			case "failed":
+				if row.Error.Valid && row.Error.String != "" {
+					return fmt.Errorf("agent: %s", row.Error.String)
+				}
+				return fmt.Errorf("agent reported failure")
+			}
+		}
+		if time.Now().After(deadline) {
+			return fmt.Errorf("command %s timed out waiting for the agent", cmdType)
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(2 * time.Second):
+		}
+	}
+}
+
+// resolveNodePin validates or resolves a node_id request value. "auto" picks
+// the least-loaded online agent; "" / "local" clears the pin.
+func resolveNodePin(ctx context.Context, db *database.DB, requested string) (string, error) {
+	requested = strings.TrimSpace(requested)
+	if requested == "" || requested == "local" {
+		return "", nil
+	}
+	q := sqlcdb.New(db.DB)
+	if requested == "auto" {
+		id, err := q.PickLeastLoadedAgent(ctx)
+		if err != nil {
+			return "", fmt.Errorf("no online nodes available")
+		}
+		return id, nil
+	}
+	agent, err := q.GetAgent(ctx, requested)
+	if err != nil {
+		return "", fmt.Errorf("node not found")
+	}
+	if !agent.Schedulable {
+		return "", fmt.Errorf("node %s is cordoned — uncordon it before pinning", agent.Name)
+	}
+	return requested, nil
+}

app/backend/internal/api/notification_producers.go

@@ -7,6 +7,7 @@ package api
 
 import (
 	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
 	"context"
 	"encoding/json"
 	"fmt"
@@ -61,26 +62,28 @@ func StartAgentHealthSweep(ctx context.Context, db *database.DB) {
 	}()
 }
 
+type agentHealthRow struct {
+	id        string
+	name      string
+	status    string
+	stale     bool
+	autoPrune bool
+}
+
 func reconcileAgentHealth(db *database.DB, staleAfter time.Duration) {
 	cutoff := time.Now().Add(-staleAfter)
-	type agentRow struct {
-		id     string
-		name   string
-		status string
-		stale  bool
-	}
-	var agents []agentRow
+	var agents []agentHealthRow
 	rows, err := db.Query(
 		`SELECT id, COALESCE(name, hostname, id::text), COALESCE(status, ''),
-		        COALESCE(last_heartbeat < $1, TRUE)
+		        COALESCE(last_heartbeat < $1, TRUE), auto_prune
 		 FROM node_agents`, cutoff)
 	if err != nil {
 		log.Printf("containr: agent health sweep: %v", err)
 		return
 	}
 	for rows.Next() {
-		var a agentRow
-		if err := rows.Scan(&a.id, &a.name, &a.status, &a.stale); err == nil {
+		var a agentHealthRow
+		if err := rows.Scan(&a.id, &a.name, &a.status, &a.stale, &a.autoPrune); err == nil {
 			agents = append(agents, a)
 		}
 	}
@@ -104,6 +107,32 @@ func reconcileAgentHealth(db *database.DB, staleAfter time.Duration) {
 				fmt.Sprintf("Agent %s resumed heartbeating.", a.name), "agent", a.id)
 		}
 	}
+
+	scheduleAutoPrune(db, agents)
+}
+
+// scheduleAutoPrune enqueues a `prune` command once per day for agents
+// with auto_prune enabled. Disk pressure is the most common small-VPS
+// failure — this is the dflow setServerAutoCleanup analog.
+func scheduleAutoPrune(db *database.DB, agents []agentHealthRow) {
+	q := sqlcdb.New(db.DB)
+	for _, a := range agents {
+		if !a.autoPrune || a.stale {
+			continue
+		}
+		last, err := q.GetLastAgentCommandByType(context.Background(),
+			sqlcdb.GetLastAgentCommandByTypeParams{NodeAgentID: a.id, Type: "prune"})
+		if err == nil && last.CreatedAt.Valid && time.Since(last.CreatedAt.Time) < 24*time.Hour {
+			continue
+		}
+		if _, err := q.CreateCommand(context.Background(), sqlcdb.CreateCommandParams{
+			ID:          uuid.New().String(),
+			Type:        "prune",
+			NodeAgentID: a.id,
+		}); err != nil {
+			log.Printf("containr: auto-prune enqueue failed for agent %s: %v", a.id, err)
+		}
+	}
 }
 
 // StartUpgradeCheck polls GitHub for the latest release once a day and

app/backend/internal/api/routes.go

@@ -43,6 +43,9 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 		dockerClient = client
 		buildManager = build.NewBuildManager("/tmp/containr-builds", dockerClient)
 		deploymentEngine = deployment.NewDeploymentEngine(buildManager, dockerClient)
+		// Node-pinned services dispatch container lifecycle to the agent's
+		// command queue instead of the local Docker socket.
+		deploymentEngine.SetNodeRunner(newAgentNodeRunner(db))
 		// Restore managed sidecars (e.g. cloudflared) from saved settings.
 		syncManagedContainers(dockerClient, db)
 	}
@@ -355,6 +358,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 
 			// Cross-cutting ops view — active/queued/failed work
 			authed.GET("/operations", handleGetOperations)
+			authed.GET("/nodes/options", agentHandler.ListNodeOptions)
 			authed.GET("/activity", handleGetActivity)
 			authed.GET("/projects/:id/activity", handleGetProjectActivity)
 

app/backend/internal/api/runtime.go

@@ -18,6 +18,38 @@ import (
 	"github.com/google/uuid"
 )
 
+// serviceLifecycle routes a start/stop/restart action to the node agent when
+// the service is pinned, or to the local Docker engine otherwise. Remote
+// actions block on the agent's poll loop; that matches the synchronous
+// behavior the local path already has.
+func serviceLifecycle(ctx context.Context, db *database.DB, engine *deployment.DeploymentEngine, serviceID uuid.UUID, action string) error {
+	if nodeID := serviceNodeID(db, serviceID); nodeID != "" {
+		return engine.ControlServiceOnNode(ctx, serviceID.String(), nodeID, action)
+	}
+	switch action {
+	case "start":
+		return engine.StartService(ctx, serviceID.String())
+	case "stop":
+		return engine.StopService(ctx, serviceID.String())
+	case "restart":
+		if err := engine.StopService(ctx, serviceID.String()); err != nil {
+			return err
+		}
+		return engine.StartService(ctx, serviceID.String())
+	}
+	return fmt.Errorf("unsupported lifecycle action %q", action)
+}
+
+// removeServiceRuntime tears down replicas wherever they run — remote node
+// when pinned, local Docker otherwise.
+func removeServiceRuntime(ctx context.Context, db *database.DB, engine *deployment.DeploymentEngine, serviceID uuid.UUID) {
+	if nodeID := serviceNodeID(db, serviceID); nodeID != "" {
+		_ = engine.RemoveServiceContainersOnNode(ctx, serviceID.String(), nodeID)
+		return
+	}
+	_ = engine.RemoveServiceContainers(ctx, serviceID.String())
+}
+
 // serviceRuntimeSpec builds the container spec for a service: stored env vars
 // merged with ${{Service.KEY}} references resolved across the project.
 func serviceRuntimeSpec(db *database.DB, service Service) (deployment.RuntimeSpec, error) {
@@ -37,6 +69,7 @@ func serviceRuntimeSpec(db *database.DB, service Service) (deployment.RuntimeSpe
 		Domain:        service.Domain,
 		HealthPath:    service.HealthCheckPath,
 		RestartPolicy: service.RestartPolicy,
+		NodeID:        serviceNodeID(db, service.ID),
 	}
 	// Best effort: reuse the host port from the last live deployment so the
 	// public URL survives restarts. Column exists post-migration; older DBs
@@ -384,7 +417,7 @@ func handleServiceStart(c *gin.Context) {
 	if !ok {
 		return
 	}
-	if err := engine.StartService(c.Request.Context(), service.ID.String()); err != nil {
+	if err := serviceLifecycle(c.Request.Context(), db, engine, service.ID, "start"); err != nil {
 		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
 		return
 	}
@@ -402,7 +435,7 @@ func handleServiceStop(c *gin.Context) {
 	if !ok {
 		return
 	}
-	if err := engine.StopService(c.Request.Context(), service.ID.String()); err != nil {
+	if err := serviceLifecycle(c.Request.Context(), db, engine, service.ID, "stop"); err != nil {
 		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
 		return
 	}
@@ -421,11 +454,7 @@ func handleServiceRestart(c *gin.Context) {
 		return
 	}
 	ctx := c.Request.Context()
-	if err := engine.StopService(ctx, service.ID.String()); err != nil {
-		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
-		return
-	}
-	if err := engine.StartService(ctx, service.ID.String()); err != nil {
+	if err := serviceLifecycle(ctx, db, engine, service.ID, "restart"); err != nil {
 		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
 		return
 	}

app/backend/internal/api/services.go

@@ -5,6 +5,7 @@ import (
 	"containr/internal/deployment"
 	"containr/internal/deployqueue"
 	"context"
+	"database/sql"
 	"encoding/json"
 	"fmt"
 	"net/http"
@@ -48,8 +49,12 @@ type Service struct {
 	StaticDir        string          `json:"static_dir,omitempty" db:"static_dir"`
 	SleepEnabled     bool            `json:"sleep_enabled" db:"-"`
 	SleepIdleMinutes int             `json:"sleep_idle_minutes" db:"-"`
-	CreatedAt        time.Time       `json:"created_at" db:"created_at"`
-	UpdatedAt        time.Time       `json:"updated_at" db:"updated_at"`
+	// NodeID pins the service to a node agent ("" = local Docker host,
+	// resolved "auto" picks the least-loaded online agent at write time).
+	NodeID    string    `json:"node_id,omitempty" db:"-"`
+	NodeName  string    `json:"node_name,omitempty" db:"-"`
+	CreatedAt time.Time `json:"created_at" db:"created_at"`
+	UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
 }
 
 // loadServiceSleep fills the sleep-mode columns, which live outside the
@@ -64,6 +69,28 @@ func loadServiceSleep(db *database.DB, s *Service) {
 	}
 }
 
+// serviceNodeID reads the pin column directly — kept out of the wide service
+// SELECTs so pre-migration schemas keep working.
+func serviceNodeID(db *database.DB, serviceID uuid.UUID) string {
+	var id sql.NullString
+	if err := db.QueryRow(`SELECT node_id FROM services WHERE id = $1`, serviceID).Scan(&id); err == nil {
+		return id.String
+	}
+	return ""
+}
+
+// loadServiceNode fills the pin + the agent's display name for responses.
+func loadServiceNode(db *database.DB, s *Service) {
+	var name sql.NullString
+	s.NodeID = serviceNodeID(db, s.ID)
+	if s.NodeID == "" {
+		return
+	}
+	if err := db.QueryRow(`SELECT name FROM node_agents WHERE id = $1`, s.NodeID).Scan(&name); err == nil {
+		s.NodeName = name.String
+	}
+}
+
 // ServiceVolume is a volume/bind mount applied to every replica.
 type ServiceVolume struct {
 	Type     string `json:"type"`   // volume | bind (empty = volume)
@@ -141,6 +168,9 @@ type CreateServiceRequest struct {
 	MemoryReserve   string          `json:"memory_reserve"`
 	StaticBuildCmd  string          `json:"static_build_cmd"`
 	StaticDir       string          `json:"static_dir"`
+	// NodeID pins placement to a node agent; "auto" picks the least-loaded
+	// online agent, "local"/"" runs on the Containr host.
+	NodeID string `json:"node_id"`
 }
 
 // UpdateServiceRequest represents a request to update a service
@@ -170,6 +200,8 @@ type UpdateServiceRequest struct {
 	StaticDir        *string          `json:"static_dir"`
 	SleepEnabled     *bool            `json:"sleep_enabled"`
 	SleepIdleMinutes *int             `json:"sleep_idle_minutes"`
+	// NodeID pins placement; pointer so "local"/"" explicitly clears the pin.
+	NodeID *string `json:"node_id"`
 }
 
 // handleGetServices retrieves all services for a project
@@ -253,6 +285,7 @@ func handleGetServices(c *gin.Context) {
 	// Reconcile stored status with live container state (no-op without Docker).
 	for i := range services {
 		liveServiceStatus(c, db.(*database.DB), &services[i])
+		loadServiceNode(db.(*database.DB), &services[i])
 	}
 
 	c.JSON(http.StatusOK, gin.H{"services": services})
@@ -409,6 +442,15 @@ func handleCreateService(c *gin.Context) {
 
 	sourceType := inferServiceSourceType(service)
 
+	if req.NodeID != "" {
+		nodeID, nodeErr := resolveNodePin(c.Request.Context(), db.(*database.DB), req.NodeID)
+		if nodeErr != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": nodeErr.Error(), "code": "VALIDATION"})
+			return
+		}
+		service.NodeID = nodeID
+	}
+
 	// Insert service into database
 	_, err = db.(*database.DB).Exec(
 		`INSERT INTO services
@@ -417,16 +459,18 @@ func handleCreateService(c *gin.Context) {
 				 git_repo, git_branch, build_path, cpu, memory, replicas, port, domain,
 				 healthcheck_path, restart_policy, volumes,
 				 builder, cpu_reserve, memory_reserve, static_build_cmd, static_dir,
-				 created_at, updated_at)
+				 node_id, created_at, updated_at)
 			VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18, $19, $20, $21, $22, $23, $24, $25, $26,
-					$27, $28, $29, $30, $31, $32, $33)`,
+					$27, $28, $29, $30, $31, $32, $33, $34)`,
 		service.ID, service.ProjectID, service.Name, environmentID, service.Type,
 		sourceType, firstNonEmpty(service.GitRepo, service.Image), service.Image,
 		"", service.Command, service.Type, service.Status, service.Image, service.Command,
 		service.Environment, service.GitRepo, service.GitBranch, service.BuildPath, service.CPU, service.Memory,
 		service.Replicas, service.Port, service.Domain, service.HealthCheckPath, service.RestartPolicy,
 		volumesJSON, service.Builder, service.CPUReserve, service.MemoryReserve,
-		service.StaticBuildCmd, service.StaticDir, service.CreatedAt, service.UpdatedAt,
+		service.StaticBuildCmd, service.StaticDir,
+		sql.NullString{String: service.NodeID, Valid: service.NodeID != ""},
+		service.CreatedAt, service.UpdatedAt,
 	)
 
 	if err != nil {
@@ -456,7 +500,9 @@ func handleCreateService(c *gin.Context) {
 
 	LogAuditWithRequest(c, "service", service.ID.String(), "create", map[string]interface{}{
 		"name": service.Name, "type": service.Type, "project_id": service.ProjectID,
+		"node_id": service.NodeID,
 	})
+	loadServiceNode(db.(*database.DB), &service)
 
 	c.JSON(http.StatusCreated, gin.H{"service": service})
 }
@@ -547,6 +593,7 @@ func handleGetService(c *gin.Context) {
 	}
 	service.Domains = loadServiceDomains(db.(*database.DB), service.ID)
 	loadServiceSleep(db.(*database.DB), &service)
+	loadServiceNode(db.(*database.DB), &service)
 	maintenance, basicAuth := serviceAccess(db.(*database.DB), service.ID)
 	service.MaintenanceMode = maintenance
 	service.BasicAuth = basicAuthUsernames(basicAuth)
@@ -725,6 +772,17 @@ func handleUpdateService(c *gin.Context) {
 		volumesArg = volumesJSON
 	}
 
+	if req.NodeID != nil {
+		nodeID, nodeErr := resolveNodePin(c.Request.Context(), db.(*database.DB), *req.NodeID)
+		if nodeErr != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": nodeErr.Error(), "code": "VALIDATION"})
+			return
+		}
+		existingService.NodeID = nodeID
+	} else {
+		existingService.NodeID = serviceNodeID(db.(*database.DB), serviceID)
+	}
+
 	existingService.UpdatedAt = time.Now()
 
 	// Update service in database
@@ -736,7 +794,7 @@ func handleUpdateService(c *gin.Context) {
 				restart_policy = $15, volumes = COALESCE($17::jsonb, volumes), updated_at = $16,
 				builder = $19, cpu_reserve = $20, memory_reserve = $21,
 				static_build_cmd = $22, static_dir = $23,
-				sleep_enabled = $24, sleep_idle_minutes = $25
+				sleep_enabled = $24, sleep_idle_minutes = $25, node_id = $26
 			WHERE id = $18`,
 		existingService.Name, existingService.Type, existingService.Image, existingService.Command,
 		existingService.Environment, existingService.GitRepo, existingService.GitBranch,
@@ -747,6 +805,7 @@ func handleUpdateService(c *gin.Context) {
 		existingService.Builder, existingService.CPUReserve, existingService.MemoryReserve,
 		existingService.StaticBuildCmd, existingService.StaticDir,
 		existingService.SleepEnabled, existingService.SleepIdleMinutes,
+		sql.NullString{String: existingService.NodeID, Valid: existingService.NodeID != ""},
 	)
 
 	if err != nil {
@@ -816,6 +875,7 @@ func handleUpdateService(c *gin.Context) {
 		}
 	}
 
+	loadServiceNode(db.(*database.DB), &existingService)
 	c.JSON(http.StatusOK, gin.H{"service": existingService})
 }
 
@@ -865,7 +925,7 @@ func handleDeleteService(c *gin.Context) {
 	// Remove runtime containers before dropping the row.
 	if engineValue, exists := c.Get("deployment_engine"); exists && engineValue != nil {
 		if engine, ok := engineValue.(*deployment.DeploymentEngine); ok {
-			_ = engine.RemoveServiceContainers(c.Request.Context(), serviceID.String())
+			removeServiceRuntime(c.Request.Context(), db.(*database.DB), engine, serviceID)
 		}
 	}
 

app/backend/internal/api/templategraph.go

@@ -637,7 +637,7 @@ func deployTemplateGraph(
 	cleanup := func() {
 		for _, sid := range createdServiceIDs {
 			if engine != nil {
-				_ = engine.RemoveServiceContainers(context.Background(), sid.String())
+				removeServiceRuntime(context.Background(), db, engine, sid)
 			}
 			_, _ = db.Exec(`DELETE FROM environment_variables WHERE service_id = $1`, sid)
 			_, _ = db.Exec(`DELETE FROM services WHERE id = $1`, sid)

app/backend/internal/cli/commands/exec.go

@@ -4,9 +4,7 @@ import (
 	"fmt"
 	"net/http"
 	"os"
-	"os/signal"
 	"strings"
-	"syscall"
 	"time"
 
 	"github.com/gorilla/websocket"
@@ -44,20 +42,13 @@ var ShellCmd = &cobra.Command{
 			if err == nil {
 				defer term.Restore(fd, oldState)
 			}
-			if w, h, err := term.GetSize(fd); err == nil {
-				_ = conn.WriteJSON(map[string]interface{}{"type": "resize", "cols": w, "rows": h})
-			}
-			// Forward SIGWINCH resizes.
-			sigCh := make(chan os.Signal, 1)
-			signal.Notify(sigCh, syscall.SIGWINCH)
-			defer signal.Stop(sigCh)
-			go func() {
-				for range sigCh {
-					if w, h, err := term.GetSize(fd); err == nil {
-						_ = conn.WriteJSON(map[string]interface{}{"type": "resize", "cols": w, "rows": h})
-					}
+			sendSize := func() {
+				if w, h, err := term.GetSize(fd); err == nil {
+					_ = conn.WriteJSON(map[string]interface{}{"type": "resize", "cols": w, "rows": h})
 				}
-			}()
+			}
+			sendSize()
+			defer watchResize(sendSize)()
 		}
 
 		done := make(chan struct{})

app/backend/internal/cli/commands/exec_resize_unix.go

@@ -0,0 +1,30 @@
+//go:build !windows
+
+package commands
+
+import (
+	"os"
+	"os/signal"
+	"syscall"
+)
+
+// watchResize forwards SIGWINCH events to send. Returns a stop func.
+func watchResize(send func()) func() {
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGWINCH)
+	done := make(chan struct{})
+	go func() {
+		for {
+			select {
+			case <-sigCh:
+				send()
+			case <-done:
+				return
+			}
+		}
+	}()
+	return func() {
+		signal.Stop(sigCh)
+		close(done)
+	}
+}

app/backend/internal/cli/commands/exec_resize_windows.go

@@ -0,0 +1,8 @@
+//go:build windows
+
+package commands
+
+// watchResize is a no-op on Windows — console resize events don't map to a
+// signal. The initial size is still sent, and Windows Terminal resize is rare
+// enough to accept stale dimensions for now.
+func watchResize(send func()) func() { return func() {} }

app/backend/internal/cli/commands/migrate.go

@@ -0,0 +1,374 @@
+package commands
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+const railwayAPI = "https://backboard.railway.com/graphql/v2"
+
+// railwaySource mirrors the Railway serviceInstance.source union.
+type railwaySource struct {
+	Repo  string `json:"repo"`
+	Image string `json:"image"`
+}
+
+type railwayServicePlan struct {
+	ID        string
+	Name      string
+	Source    railwaySource
+	Command   string
+	Replicas  int
+	Domains   []string
+	Variables map[string]string
+}
+
+// MigrateCmd imports workloads from other platforms.
+var MigrateCmd = &cobra.Command{
+	Use:   "migrate",
+	Short: "Import workloads from other platforms",
+}
+
+var migrateRailwayCmd = &cobra.Command{
+	Use:   "railway",
+	Short: "Migrate a Railway project into Containr",
+	Long: `Pulls a Railway project's services, variables, and domains via the
+public GraphQL API and recreates them in Containr.
+
+  containr migrate railway --token <railway-token> --project <id> --dry-run
+  containr migrate railway --token <railway-token> --project <id> --into <project-id>
+
+Token: account/workspace token (Authorization: Bearer) or a project token.
+--into defaults to creating a project named after the Railway project.`,
+	Args: cobra.NoArgs,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		token, _ := cmd.Flags().GetString("token")
+		if token == "" {
+			token = os.Getenv("RAILWAY_TOKEN")
+		}
+		if token == "" {
+			return &APIError{Message: "pass --token or set RAILWAY_TOKEN", ExitCode: ExitError}
+		}
+		projectID, _ := cmd.Flags().GetString("project")
+		envName, _ := cmd.Flags().GetString("environment")
+		into, _ := cmd.Flags().GetString("into")
+		dryRun, _ := cmd.Flags().GetBool("dry-run")
+
+		projectName, envID, services, err := railwayProject(projectID, envName, token)
+		if err != nil {
+			return err
+		}
+		if len(services) == 0 {
+			return &APIError{Message: "no services found in that Railway project/environment", ExitCode: ExitError}
+		}
+
+		plans := make([]railwayServicePlan, 0, len(services))
+		for _, svc := range services {
+			plan, err := railwayServiceDetail(svc, envID, token)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "warning: %s: %v — skipping\n", svc["name"], err)
+				continue
+			}
+			plans = append(plans, plan)
+		}
+		if len(plans) == 0 {
+			return &APIError{Message: "no migratable services", ExitCode: ExitError}
+		}
+
+		fmt.Printf("Railway project %q → %d service(s)\n", projectName, len(plans))
+		for _, p := range plans {
+			src := p.Source.Image
+			if src == "" {
+				src = railwayRepoURL(p.Source.Repo)
+			}
+			fmt.Printf("  %s  src=%s replicas=%d vars=%d domains=%d\n",
+				p.Name, src, max(p.Replicas, 1), len(p.Variables), len(p.Domains))
+		}
+
+		if dryRun {
+			fmt.Println("\nDry run — pass without --dry-run to create these resources.")
+			return nil
+		}
+
+		c, err := client()
+		if err != nil {
+			return err
+		}
+
+		target := into
+		if target == "" {
+			data, err := c.Do("POST", "/projects", map[string]interface{}{
+				"name":        projectName,
+				"description": "Imported from Railway",
+			})
+			if err != nil {
+				return err
+			}
+			p, _ := unwrapObject(data, "project")
+			target = str(p, "id")
+			if target == "" || target == "-" {
+				return &APIError{Message: "project created but id missing from response", ExitCode: ExitError}
+			}
+			fmt.Printf("Created project %s (%s)\n", projectName, target)
+		}
+
+		for _, p := range plans {
+			body := map[string]interface{}{
+				"name":        p.Name,
+				"type":        "web",
+				"environment": "production",
+			}
+			if p.Source.Image != "" {
+				body["image"] = p.Source.Image
+			} else if repo := railwayRepoURL(p.Source.Repo); repo != "" {
+				body["git_repo"] = repo
+			} else {
+				fmt.Fprintf(os.Stderr, "warning: %s has no source — skipping\n", p.Name)
+				continue
+			}
+			if p.Command != "" {
+				body["command"] = p.Command
+			}
+			if p.Replicas > 1 {
+				body["replicas"] = p.Replicas
+			}
+			data, err := c.Do("POST", "/projects/"+target+"/services", body)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "error: create %s: %v\n", p.Name, err)
+				continue
+			}
+			svc, _ := unwrapObject(data, "service")
+			svcID := str(svc, "id")
+			fmt.Printf("  created service %s (%s)\n", p.Name, svcID)
+
+			if len(p.Variables) > 0 && svcID != "" && svcID != "-" {
+				vars := make([]map[string]interface{}, 0, len(p.Variables))
+				for k, v := range p.Variables {
+					vars = append(vars, map[string]interface{}{"key": k, "value": v, "is_secret": false})
+				}
+				if _, err := c.Do("PUT", "/services/"+svcID+"/variables",
+					map[string]interface{}{"variables": vars}); err != nil {
+					fmt.Fprintf(os.Stderr, "  warning: variables for %s: %v\n", p.Name, err)
+				}
+			}
+			for _, domain := range p.Domains {
+				if svcID == "" || svcID == "-" {
+					break
+				}
+				if _, err := c.Do("POST", "/services/"+svcID+"/domains",
+					map[string]interface{}{"domain": domain}); err != nil {
+					fmt.Fprintf(os.Stderr, "  warning: domain %s: %v\n", domain, err)
+				}
+			}
+		}
+		fmt.Println("Done. Railway deploy triggers are not migrated — redeploy each service when ready.")
+		return nil
+	},
+}
+
+// railwayGraphQL posts a query; Railway returns 200 with an errors array on
+// partial failures — treat errors as fatal, the migration needs clean data.
+func railwayGraphQL(token, query string, variables map[string]interface{}) (map[string]interface{}, error) {
+	body, _ := json.Marshal(map[string]interface{}{"query": query, "variables": variables})
+	req, err := http.NewRequest(http.MethodPost, railwayAPI, bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	// Project tokens use a dedicated header; account/workspace tokens use Bearer.
+	if strings.HasPrefix(token, "rw_pat") || strings.HasPrefix(token, "rw_pt") {
+		req.Header.Set("Project-Access-Token", token)
+	} else {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+	var out struct {
+		Data   map[string]interface{} `json:"data"`
+		Errors []struct {
+			Message string `json:"message"`
+		} `json:"errors"`
+	}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("railway response not JSON (status %d)", resp.StatusCode)
+	}
+	if len(out.Errors) > 0 {
+		return nil, fmt.Errorf("railway: %s", out.Errors[0].Message)
+	}
+	if resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("railway status %d", resp.StatusCode)
+	}
+	return out.Data, nil
+}
+
+// railwayProject resolves the project (by id, or sole accessible project) and
+// returns its name, the target environment id, and its services.
+func railwayProject(projectID, envName, token string) (string, string, []map[string]interface{}, error) {
+	if projectID == "" {
+		data, err := railwayGraphQL(token,
+			`query { projects(first: 100) { edges { node { id name } } } }`, nil)
+		if err != nil {
+			return "", "", nil, err
+		}
+		projects := edgesOf(data, "projects")
+		if len(projects) == 1 {
+			projectID = str(projects[0], "id")
+		} else {
+			for _, p := range projects {
+				fmt.Fprintf(os.Stderr, "  %s  %s\n", str(p, "id"), str(p, "name"))
+			}
+			return "", "", nil, &APIError{
+				Message:  "multiple projects — pass --project <id> (listed above)",
+				ExitCode: ExitError,
+			}
+		}
+	}
+
+	data, err := railwayGraphQL(token, `query ($id: String!) {
+		project(id: $id) {
+			name
+			environments { edges { node { id name } } }
+			services { edges { node { id name } } }
+		}
+	}`, map[string]interface{}{"id": projectID})
+	if err != nil {
+		return "", "", nil, err
+	}
+	project, _ := data["project"].(map[string]interface{})
+	if project == nil {
+		return "", "", nil, &APIError{Message: "railway project not found", ExitCode: ExitNotFound}
+	}
+	envs := edgesOf(project, "environments")
+	envID := ""
+	for _, e := range envs {
+		if str(e, "name") == envName {
+			envID = str(e, "id")
+			break
+		}
+	}
+	if envID == "" && len(envs) == 1 {
+		envID = str(envs[0], "id")
+	}
+	if envID == "" {
+		names := make([]string, 0, len(envs))
+		for _, e := range envs {
+			names = append(names, str(e, "name"))
+		}
+		return "", "", nil, &APIError{
+			Message:  fmt.Sprintf("environment %q not found (have: %s)", envName, strings.Join(names, ", ")),
+			ExitCode: ExitError,
+		}
+	}
+	return str(project, "name"), envID, edgesOf(project, "services"), nil
+}
+
+// railwayServiceDetail pulls source, command, replicas, domains, and
+// variables for one service in the target environment.
+func railwayServiceDetail(svc map[string]interface{}, envID, token string) (railwayServicePlan, error) {
+	plan := railwayServicePlan{
+		ID:   str(svc, "id"),
+		Name: str(svc, "name"),
+	}
+	data, err := railwayGraphQL(token, `query ($sid: String!, $eid: String!) {
+		serviceInstance(serviceId: $sid, environmentId: $eid) {
+			startCommand
+			numReplicas
+			source { repo image }
+			domains { serviceDomains { domain } customDomains { domain } }
+		}
+	}`, map[string]interface{}{"sid": plan.ID, "eid": envID})
+	if err != nil {
+		return plan, err
+	}
+	inst, _ := data["serviceInstance"].(map[string]interface{})
+	if inst == nil {
+		return plan, fmt.Errorf("no service instance in this environment")
+	}
+	if src, ok := inst["source"].(map[string]interface{}); ok {
+		plan.Source = railwaySource{Repo: str(src, "repo"), Image: str(src, "image")}
+	}
+	if cmd, ok := inst["startCommand"].(string); ok {
+		plan.Command = cmd
+	}
+	if n, ok := inst["numReplicas"].(float64); ok {
+		plan.Replicas = int(n)
+	}
+	if domains, ok := inst["domains"].(map[string]interface{}); ok {
+		for _, group := range []string{"serviceDomains", "customDomains"} {
+			if list, ok := domains[group].([]interface{}); ok {
+				for _, d := range list {
+					if m, ok := d.(map[string]interface{}); ok {
+						if dom := str(m, "domain"); dom != "" && dom != "-" {
+							plan.Domains = append(plan.Domains, dom)
+						}
+					}
+				}
+			}
+		}
+	}
+
+	vdata, err := railwayGraphQL(token, `query ($sid: String!, $eid: String!) {
+		variables(serviceId: $sid, environmentId: $eid)
+	}`, map[string]interface{}{"sid": plan.ID, "eid": envID})
+	if err == nil {
+		if vars, ok := vdata["variables"].(map[string]interface{}); ok {
+			plan.Variables = map[string]string{}
+			for k, v := range vars {
+				if s, ok := v.(string); ok {
+					// Railway reference variables (${{…}}) resolve at deploy
+					// time — carry them literally so they stay visible.
+					plan.Variables[k] = s
+				}
+			}
+		}
+	}
+	return plan, nil
+}
+
+// railwayRepoURL normalizes Railway's "owner/repo" to a cloneable https URL.
+func railwayRepoURL(repo string) string {
+	repo = strings.TrimSpace(repo)
+	if repo == "" || repo == "-" {
+		return ""
+	}
+	if strings.Contains(repo, "://") || strings.HasPrefix(repo, "git@") {
+		return repo
+	}
+	return "https://github.com/" + repo
+}
+
+func edgesOf(obj map[string]interface{}, key string) []map[string]interface{} {
+	conn, _ := obj[key].(map[string]interface{})
+	edges, _ := conn["edges"].([]interface{})
+	out := make([]map[string]interface{}, 0, len(edges))
+	for _, e := range edges {
+		if m, ok := e.(map[string]interface{}); ok {
+			if node, ok := m["node"].(map[string]interface{}); ok {
+				out = append(out, node)
+			}
+		}
+	}
+	return out
+}
+
+func init() {
+	migrateRailwayCmd.Flags().String("token", "", "Railway API token (or RAILWAY_TOKEN env)")
+	migrateRailwayCmd.Flags().String("project", "", "Railway project id (lists yours when omitted and >1 exists)")
+	migrateRailwayCmd.Flags().String("environment", "production", "Railway environment name")
+	migrateRailwayCmd.Flags().String("into", "", "existing Containr project id (default: create one)")
+	migrateRailwayCmd.Flags().Bool("dry-run", false, "print the plan without creating anything")
+	MigrateCmd.AddCommand(migrateRailwayCmd)
+}

app/backend/internal/cli/commands/migrate_dflow.go

@@ -0,0 +1,441 @@
+package commands
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+)
+
+// dflow runs on Payload CMS — every collection is a plain REST resource under
+// /api/<slug> returning {docs, page, totalPages, hasNextPage}. Auth is a
+// Payload API key on the users collection: "Authorization: users API-Key <k>".
+
+type dflowServicePlan struct {
+	ID          string
+	Name        string
+	Description string
+	Type        string // web | database
+	Image       string
+	GitRepo     string
+	GitBranch   string
+	BuildPath   string
+	Port        int
+	Variables   map[string]string
+	Domains     []string
+	Volumes     []map[string]string
+}
+
+var migrateDflowCmd = &cobra.Command{
+	Use:   "dflow",
+	Short: "Migrate a dflow (Payload CMS) project into Containr",
+	Long: `Pulls a dflow project's services, variables, volumes, and domains via the
+Payload REST API and recreates them in Containr.
+
+  containr migrate dflow --url https://dflow.example.com --api-key <key> --dry-run
+  containr migrate dflow --url https://dflow.example.com --api-key <key> --project <id>
+
+Auth: a Payload API key from a dflow admin user (users API-Key). Encrypted
+fields (variables, git tokens) only come back decrypted if the API key belongs
+to a user with access — empty values are flagged so nothing is silently lost.`,
+	Args: cobra.NoArgs,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		base, _ := cmd.Flags().GetString("url")
+		if base == "" {
+			base = os.Getenv("DFLOW_URL")
+		}
+		if base == "" {
+			return &APIError{Message: "pass --url or set DFLOW_URL", ExitCode: ExitError}
+		}
+		base = strings.TrimSuffix(base, "/")
+		key, _ := cmd.Flags().GetString("api-key")
+		if key == "" {
+			key = os.Getenv("DFLOW_API_KEY")
+		}
+		if key == "" {
+			return &APIError{Message: "pass --api-key or set DFLOW_API_KEY", ExitCode: ExitError}
+		}
+		projectID, _ := cmd.Flags().GetString("project")
+		into, _ := cmd.Flags().GetString("into")
+		dryRun, _ := cmd.Flags().GetBool("dry-run")
+
+		projectName, services, err := dflowProject(base, key, projectID)
+		if err != nil {
+			return err
+		}
+		if len(services) == 0 {
+			return &APIError{Message: "no services found in that dflow project", ExitCode: ExitError}
+		}
+
+		plans := make([]dflowServicePlan, 0, len(services))
+		for _, svc := range services {
+			plan, warn := dflowServicePlanOf(svc)
+			for _, w := range warn {
+				fmt.Fprintf(os.Stderr, "  warning: %s: %s\n", plan.Name, w)
+			}
+			plans = append(plans, plan)
+		}
+
+		fmt.Printf("dflow project %q → %d service(s)\n", projectName, len(plans))
+		for _, p := range plans {
+			src := p.Image
+			if src == "" {
+				src = p.GitRepo
+			}
+			fmt.Printf("  %s  type=%s src=%s vars=%d domains=%d volumes=%d\n",
+				p.Name, p.Type, src, len(p.Variables), len(p.Domains), len(p.Volumes))
+		}
+
+		if dryRun {
+			fmt.Println("\nDry run — pass without --dry-run to create these resources.")
+			return nil
+		}
+
+		c, err := client()
+		if err != nil {
+			return err
+		}
+
+		target := into
+		if target == "" {
+			data, err := c.Do("POST", "/projects", map[string]interface{}{
+				"name":        projectName,
+				"description": "Imported from dflow",
+			})
+			if err != nil {
+				return err
+			}
+			p, _ := unwrapObject(data, "project")
+			target = str(p, "id")
+			if target == "" || target == "-" {
+				return &APIError{Message: "project created but id missing from response", ExitCode: ExitError}
+			}
+			fmt.Printf("Created project %s (%s)\n", projectName, target)
+		}
+
+		for _, p := range plans {
+			body := map[string]interface{}{
+				"name":        p.Name,
+				"type":        p.Type,
+				"environment": "production",
+			}
+			if p.Image != "" {
+				body["image"] = p.Image
+			}
+			if p.GitRepo != "" {
+				body["git_repo"] = p.GitRepo
+			}
+			if p.GitBranch != "" {
+				body["git_branch"] = p.GitBranch
+			}
+			if p.BuildPath != "" {
+				body["build_path"] = p.BuildPath
+			}
+			if p.Port > 0 {
+				body["port"] = p.Port
+			}
+			if len(p.Volumes) > 0 {
+				vols := make([]map[string]interface{}, 0, len(p.Volumes))
+				for _, v := range p.Volumes {
+					vols = append(vols, map[string]interface{}{
+						"type": "bind", "source": v["source"], "target": v["target"],
+					})
+				}
+				body["volumes"] = vols
+			}
+			data, err := c.Do("POST", "/projects/"+target+"/services", body)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "error: create %s: %v\n", p.Name, err)
+				continue
+			}
+			svc, _ := unwrapObject(data, "service")
+			svcID := str(svc, "id")
+			fmt.Printf("  created service %s (%s)\n", p.Name, svcID)
+
+			if len(p.Variables) > 0 && svcID != "" && svcID != "-" {
+				vars := make([]map[string]interface{}, 0, len(p.Variables))
+				for k, v := range p.Variables {
+					vars = append(vars, map[string]interface{}{"key": k, "value": v, "is_secret": false})
+				}
+				if _, err := c.Do("PUT", "/services/"+svcID+"/variables",
+					map[string]interface{}{"variables": vars}); err != nil {
+					fmt.Fprintf(os.Stderr, "  warning: variables for %s: %v\n", p.Name, err)
+				}
+			}
+			for _, domain := range p.Domains {
+				if svcID == "" || svcID == "-" {
+					break
+				}
+				if _, err := c.Do("POST", "/services/"+svcID+"/domains",
+					map[string]interface{}{"domain": domain}); err != nil {
+					fmt.Fprintf(os.Stderr, "  warning: domain %s: %v\n", domain, err)
+				}
+			}
+		}
+		fmt.Println("Done. Git credentials, deployment history, and server topology are not migrated — reconnect repos and redeploy each service when ready.")
+		return nil
+	},
+}
+
+// dflowGet performs an authenticated Payload REST call.
+func dflowGet(base, apiKey, path string, q url.Values) (map[string]interface{}, error) {
+	u := base + "/api/" + path
+	if len(q) > 0 {
+		u += "?" + q.Encode()
+	}
+	req, err := http.NewRequest(http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "users API-Key "+apiKey)
+	req.Header.Set("Accept", "application/json")
+	client := &http.Client{Timeout: 30 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(io.LimitReader(resp.Body, 16<<20))
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		return nil, &APIError{Message: "dflow rejected the API key — needs an admin user's users API-Key", ExitCode: ExitAuth}
+	}
+	var out map[string]interface{}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("dflow response not JSON (status %d)", resp.StatusCode)
+	}
+	if resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("dflow status %d", resp.StatusCode)
+	}
+	return out, nil
+}
+
+// dflowCollection pages through a Payload collection.
+func dflowCollection(base, apiKey, collection string, q url.Values) ([]map[string]interface{}, error) {
+	var docs []map[string]interface{}
+	for page := 1; ; page++ {
+		params := url.Values{}
+		for k, v := range q {
+			params[k] = v
+		}
+		params.Set("limit", "100")
+		params.Set("depth", "0")
+		params.Set("page", fmt.Sprint(page))
+		data, err := dflowGet(base, apiKey, collection, params)
+		if err != nil {
+			return nil, err
+		}
+		list, _ := data["docs"].([]interface{})
+		for _, d := range list {
+			if m, ok := d.(map[string]interface{}); ok {
+				docs = append(docs, m)
+			}
+		}
+		next, _ := data["hasNextPage"].(bool)
+		if !next {
+			return docs, nil
+		}
+	}
+}
+
+// dflowProject resolves the project (by id, or sole project) and returns its
+// name plus its services.
+func dflowProject(base, apiKey, projectID string) (string, []map[string]interface{}, error) {
+	if projectID == "" {
+		projects, err := dflowCollection(base, apiKey, "projects", nil)
+		if err != nil {
+			return "", nil, err
+		}
+		if len(projects) == 1 {
+			projectID = str(projects[0], "id")
+		} else {
+			for _, p := range projects {
+				fmt.Fprintf(os.Stderr, "  %s  %s\n", str(p, "id"), str(p, "name"))
+			}
+			return "", nil, &APIError{
+				Message:  "multiple projects — pass --project <id> (listed above)",
+				ExitCode: ExitError,
+			}
+		}
+	}
+
+	projects, err := dflowCollection(base, apiKey, "projects",
+		url.Values{"where[id][equals]": {projectID}})
+	if err != nil {
+		return "", nil, err
+	}
+	if len(projects) == 0 {
+		return "", nil, &APIError{Message: "dflow project not found", ExitCode: ExitNotFound}
+	}
+	name := str(projects[0], "name")
+
+	q := url.Values{
+		"where[project][equals]":     {projectID},
+		"where[deletedAt][exists]":   {"false"},
+		"where[_status][not_equals]": {"draft"},
+	}
+	services, err := dflowCollection(base, apiKey, "services", q)
+	if err != nil {
+		return "", nil, err
+	}
+	return name, services, nil
+}
+
+// dflowServicePlanOf maps a Payload service doc onto a Containr create plan.
+func dflowServicePlanOf(svc map[string]interface{}) (dflowServicePlan, []string) {
+	var warn []string
+	plan := dflowServicePlan{
+		ID:          str(svc, "id"),
+		Name:        str(svc, "name"),
+		Description: str(svc, "description"),
+		Variables:   map[string]string{},
+	}
+	switch str(svc, "type") {
+	case "app":
+		plan.Type = "web"
+		settings := dflowProviderSettings(svc)
+		plan.GitRepo = dflowRepoURL(str(svc, "providerType"), str(settings, "owner"), str(settings, "repository"))
+		plan.GitBranch = str(settings, "branch")
+		plan.BuildPath = str(settings, "buildPath")
+		plan.Port = int(num(settings, "port"))
+		if plan.GitRepo == "" {
+			warn = append(warn, "no repository settings — importing with no source")
+		}
+	case "docker":
+		plan.Type = "web"
+		d, _ := svc["dockerDetails"].(map[string]interface{})
+		plan.Image = normalizeDockerImage(str(d, "url"))
+		for _, p := range listOf(d, "ports") {
+			if plan.Port == 0 {
+				plan.Port = int(num(p, "containerPort"))
+			}
+		}
+		if plan.Image == "" {
+			warn = append(warn, "no docker image url — importing with no source")
+		}
+	case "database":
+		plan.Type = "database"
+		d, _ := svc["databaseDetails"].(map[string]interface{})
+		dbType := str(d, "type")
+		version := str(d, "version")
+		if dbType != "" {
+			plan.Image = dbType + ":" + firstOf(version, "latest")
+		}
+		if str(d, "provider") == "external" {
+			if conn := str(d, "connectionUrl"); conn != "" {
+				plan.Variables["DATABASE_URL"] = conn
+			} else if str(d, "host") != "" {
+				warn = append(warn, "external database has host but no connectionUrl — set DATABASE_URL manually")
+			}
+		}
+	default:
+		plan.Type = "web"
+		warn = append(warn, fmt.Sprintf("unknown type %q — imported as web", str(svc, "type")))
+	}
+
+	for _, v := range listOf(svc, "variables") {
+		k, val := str(v, "key"), str(v, "value")
+		if k == "" {
+			continue
+		}
+		if val == "" {
+			warn = append(warn, fmt.Sprintf("variable %s came back empty (encrypted field?)", k))
+		}
+		plan.Variables[k] = val
+	}
+	for _, d := range listOf(svc, "domains") {
+		if dom := str(d, "domain"); dom != "" && dom != "-" {
+			plan.Domains = append(plan.Domains, dom)
+		}
+	}
+	for _, v := range listOf(svc, "volumes") {
+		host, container := str(v, "hostPath"), str(v, "containerPath")
+		if host != "" && container != "" {
+			plan.Volumes = append(plan.Volumes, map[string]string{"source": host, "target": container})
+		}
+	}
+	return plan, warn
+}
+
+// dflowProviderSettings picks the populated <provider>Settings group.
+func dflowProviderSettings(svc map[string]interface{}) map[string]interface{} {
+	for _, key := range []string{"githubSettings", "gitlabSettings", "bitbucketSettings", "giteaSettings", "azureSettings"} {
+		if g, ok := svc[key].(map[string]interface{}); ok && str(g, "repository") != "" {
+			return g
+		}
+	}
+	return nil
+}
+
+// dflowRepoURL builds a cloneable https URL for the known git providers.
+func dflowRepoURL(providerType, owner, repo string) string {
+	repo = strings.TrimSuffix(strings.TrimSpace(repo), ".git")
+	owner = strings.TrimSpace(owner)
+	if repo == "" {
+		return ""
+	}
+	if strings.Contains(repo, "://") || strings.HasPrefix(repo, "git@") {
+		return repo
+	}
+	switch providerType {
+	case "gitlab":
+		return "https://gitlab.com/" + owner + "/" + repo
+	case "bitbucket":
+		return "https://bitbucket.org/" + owner + "/" + repo
+	case "azureDevOps":
+		return "https://dev.azure.com/" + owner + "/_git/" + repo
+	case "gitea":
+		return "" // host unknown — user must reconnect the repo
+	default:
+		if owner == "" {
+			return ""
+		}
+		return "https://github.com/" + owner + "/" + repo
+	}
+}
+
+// normalizeDockerImage fixes common dflow registry URL typos (ghrc://).
+func normalizeDockerImage(image string) string {
+	image = strings.TrimSpace(image)
+	if strings.HasPrefix(image, "ghrc://") {
+		return "ghcr.io/" + strings.TrimPrefix(image, "ghrc://")
+	}
+	return image
+}
+
+func listOf(m map[string]interface{}, key string) []map[string]interface{} {
+	raw, _ := m[key].([]interface{})
+	out := make([]map[string]interface{}, 0, len(raw))
+	for _, item := range raw {
+		if v, ok := item.(map[string]interface{}); ok {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+func num(m map[string]interface{}, key string) float64 {
+	v, _ := m[key].(float64)
+	return v
+}
+
+func firstOf(v, fallback string) string {
+	if v == "" {
+		return fallback
+	}
+	return v
+}
+
+func init() {
+	migrateDflowCmd.Flags().String("url", "", "dflow base URL (or DFLOW_URL env)")
+	migrateDflowCmd.Flags().String("api-key", "", "dflow admin API key (or DFLOW_API_KEY env)")
+	migrateDflowCmd.Flags().String("project", "", "dflow project id (lists yours when omitted and >1 exists)")
+	migrateDflowCmd.Flags().String("into", "", "existing Containr project id (default: create one)")
+	migrateDflowCmd.Flags().Bool("dry-run", false, "print the plan without creating anything")
+	MigrateCmd.AddCommand(migrateDflowCmd)
+}

app/backend/internal/cli/commands/migrate_test.go

@@ -0,0 +1,122 @@
+package commands
+
+import "testing"
+
+func TestRailwayRepoURL(t *testing.T) {
+	cases := map[string]string{
+		"owner/repo":             "https://github.com/owner/repo",
+		"https://gitlab.com/a/b": "https://gitlab.com/a/b",
+		"[email protected]:a/b.git": "[email protected]:a/b.git",
+		"":                       "",
+		"-":                      "",
+		"  spaced/x  ":           "https://github.com/spaced/x",
+	}
+	for in, want := range cases {
+		if got := railwayRepoURL(in); got != want {
+			t.Errorf("railwayRepoURL(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestEdgesOf(t *testing.T) {
+	obj := map[string]interface{}{
+		"services": map[string]interface{}{
+			"edges": []interface{}{
+				map[string]interface{}{"node": map[string]interface{}{"id": "a", "name": "web"}},
+				map[string]interface{}{"node": map[string]interface{}{"id": "b", "name": "api"}},
+			},
+		},
+	}
+	nodes := edgesOf(obj, "services")
+	if len(nodes) != 2 || str(nodes[0], "name") != "web" {
+		t.Fatalf("edgesOf returned %+v", nodes)
+	}
+	if got := edgesOf(obj, "missing"); len(got) != 0 {
+		t.Fatalf("edgesOf(missing) = %+v, want empty", got)
+	}
+	if got := edgesOf(map[string]interface{}{"services": nil}, "services"); len(got) != 0 {
+		t.Fatalf("edgesOf(nil conn) = %+v, want empty", got)
+	}
+}
+
+func TestDflowServicePlanOf(t *testing.T) {
+	appSvc := map[string]interface{}{
+		"id":           "s1",
+		"name":         "api",
+		"type":         "app",
+		"providerType": "github",
+		"githubSettings": map[string]interface{}{
+			"owner": "acme", "repository": "api", "branch": "main",
+			"buildPath": "/", "port": float64(8080),
+		},
+		"variables": []interface{}{
+			map[string]interface{}{"key": "FOO", "value": "bar"},
+			map[string]interface{}{"key": "EMPTY", "value": ""},
+		},
+		"domains": []interface{}{
+			map[string]interface{}{"domain": "api.example.com"},
+		},
+		"volumes": []interface{}{
+			map[string]interface{}{"hostPath": "/data", "containerPath": "/app/data"},
+		},
+	}
+	plan, warn := dflowServicePlanOf(appSvc)
+	if plan.Type != "web" || plan.GitRepo != "https://github.com/acme/api" || plan.Port != 8080 {
+		t.Fatalf("app plan = %+v", plan)
+	}
+	if plan.Variables["FOO"] != "bar" || len(plan.Domains) != 1 || len(plan.Volumes) != 1 {
+		t.Fatalf("plan detail = %+v", plan)
+	}
+	if len(warn) != 1 { // EMPTY value flagged
+		t.Fatalf("warnings = %v", warn)
+	}
+
+	dbSvc := map[string]interface{}{
+		"id": "s2", "name": "pg", "type": "database",
+		"databaseDetails": map[string]interface{}{
+			"type": "postgres", "version": "16", "provider": "external",
+			"connectionUrl": "postgres://u:p@h:5432/db",
+		},
+	}
+	dplan, _ := dflowServicePlanOf(dbSvc)
+	if dplan.Type != "database" || dplan.Image != "postgres:16" {
+		t.Fatalf("db plan = %+v", dplan)
+	}
+	if dplan.Variables["DATABASE_URL"] != "postgres://u:p@h:5432/db" {
+		t.Fatalf("db vars = %+v", dplan.Variables)
+	}
+
+	dockerSvc := map[string]interface{}{
+		"id": "s3", "name": "img", "type": "docker",
+		"dockerDetails": map[string]interface{}{
+			"url": "ghrc://acme/web:v1",
+			"ports": []interface{}{
+				map[string]interface{}{"hostPort": float64(80), "containerPort": float64(3000), "scheme": "http"},
+			},
+		},
+	}
+	iplan, _ := dflowServicePlanOf(dockerSvc)
+	if iplan.Image != "ghcr.io/acme/web:v1" || iplan.Port != 3000 {
+		t.Fatalf("docker plan = %+v", iplan)
+	}
+}
+
+func TestDflowRepoURL(t *testing.T) {
+	cases := []struct {
+		provider, owner, repo, want string
+	}{
+		{"github", "acme", "api", "https://github.com/acme/api"},
+		{"gitlab", "acme", "api", "https://gitlab.com/acme/api"},
+		{"bitbucket", "acme", "api", "https://bitbucket.org/acme/api"},
+		{"gitea", "acme", "api", ""},
+		{"github", "acme", "api.git", "https://github.com/acme/api"},
+		{"github", "", "api", ""},
+		{"github", "acme", "", ""},
+		{"github", "acme", "https://git.example.com/a/b", "https://git.example.com/a/b"},
+	}
+	for _, c := range cases {
+		if got := dflowRepoURL(c.provider, c.owner, c.repo); got != c.want {
+			t.Errorf("dflowRepoURL(%q,%q,%q) = %q, want %q", c.provider, c.owner, c.repo, got, c.want)
+		}
+	}
+}

app/backend/internal/cli/commands/nodes.go

@@ -81,6 +81,133 @@ var nodesDeleteCmd = &cobra.Command{
 	},
 }
 
+var nodesUpdateCmd = &cobra.Command{
+	Use:   "update <id>",
+	Short: "Update a node agent (--name, --auto-prune)",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		body := map[string]interface{}{}
+		if cmd.Flags().Changed("name") {
+			body["name"], _ = cmd.Flags().GetString("name")
+		}
+		if cmd.Flags().Changed("auto-prune") {
+			body["auto_prune"], _ = cmd.Flags().GetBool("auto-prune")
+		}
+		if len(body) == 0 {
+			return &APIError{Message: "nothing to update — pass --name or --auto-prune", ExitCode: ExitError}
+		}
+		data, err := c.Do("PUT", "/agents/"+args[0], body)
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
+var nodesPruneCmd = &cobra.Command{
+	Use:   "prune <id>",
+	Short: "Enqueue a bounded docker system prune on a node",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		volumes, _ := cmd.Flags().GetBool("volumes")
+		if volumes && !Confirm("Prune INCLUDING volumes? This can delete database data.") {
+			return &APIError{Message: "aborted (pass --yes to skip confirmation)", ExitCode: ExitError}
+		}
+		until, _ := cmd.Flags().GetString("until")
+		data, err := c.Do("POST", "/agents/"+args[0]+"/prune",
+			map[string]interface{}{"until": until, "volumes": volumes})
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
+var nodesCordonCmd = &cobra.Command{
+	Use:   "cordon <id>",
+	Short: "Stop new placements on a node (running replicas stay)",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		data, err := c.Do("POST", "/agents/"+args[0]+"/cordon", nil)
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
+var nodesUncordonCmd = &cobra.Command{
+	Use:   "uncordon <id>",
+	Short: "Re-open a node for placement",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		data, err := c.Do("POST", "/agents/"+args[0]+"/uncordon", nil)
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
+var nodesDrainCmd = &cobra.Command{
+	Use:   "drain <id>",
+	Short: "Cordon a node, remove its service containers, unpin affected services",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		if !Confirm(fmt.Sprintf("Drain node %s? Its service containers are removed and services unpinned (they redeploy locally).", args[0])) {
+			return &APIError{Message: "aborted (pass --yes to skip confirmation)", ExitCode: ExitError}
+		}
+		data, err := c.Do("POST", "/agents/"+args[0]+"/drain", nil)
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
+var nodesCommandsCmd = &cobra.Command{
+	Use:   "commands <id>",
+	Short: "List recent commands sent to a node agent",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		data, err := c.Do("GET", "/agents/"+args[0]+"/commands", nil)
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
 // Agent tokens (cagt_) onboard new nodes.
 var nodeTokensCmd = &cobra.Command{
 	Use:   "tokens",
@@ -145,6 +272,10 @@ var nodeTokensRevokeCmd = &cobra.Command{
 }
 
 func init() {
+	nodesUpdateCmd.Flags().String("name", "", "node display name")
+	nodesUpdateCmd.Flags().Bool("auto-prune", false, "enqueue a daily bounded docker prune")
+	nodesPruneCmd.Flags().String("until", "", "only prune objects older than this duration (e.g. 168h)")
+	nodesPruneCmd.Flags().Bool("volumes", false, "also prune volumes (destructive — asks twice)")
 	nodeTokensCmd.AddCommand(nodeTokensIssueCmd, nodeTokensListCmd, nodeTokensRevokeCmd)
-	NodesCmd.AddCommand(nodesListCmd, nodesGetCmd, nodesDeleteCmd, nodeTokensCmd)
+	NodesCmd.AddCommand(nodesListCmd, nodesGetCmd, nodesUpdateCmd, nodesCordonCmd, nodesUncordonCmd, nodesDrainCmd, nodesPruneCmd, nodesCommandsCmd, nodesDeleteCmd, nodeTokensCmd)
 }

app/backend/internal/cli/commands/nodes_add.go

@@ -0,0 +1,214 @@
+package commands
+
+// SSH node bootstrap — one SSH session installs the agent (binary +
+// systemd + enroll token), then SSH is never needed again. SSH keys
+// stay client-side; the server only sees the resulting agent.
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"os/user"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/agent"
+	"golang.org/x/term"
+)
+
+var (
+	nodeSSHKey   string
+	nodeSSHName  string
+	nodeSSHPrint bool
+)
+
+var nodesAddCmd = &cobra.Command{
+	Use:   "add <[user@]host[:port]>",
+	Short: "Bootstrap a node agent over SSH (one session, then closed)",
+	Long: `Installs the containr agent on a remote host:
+
+  1. mints a single-use enroll token via the API
+  2. SSHes in (agent socket, --key, or default key files)
+  3. runs the instance's install script remotely
+  4. closes the session — the agent heartbeats outbound from then on
+
+Use --print to skip SSH and emit the remote one-liner for manual runs.`,
+	Args: cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		c, err := client()
+		if err != nil {
+			return err
+		}
+
+		// Mint the enroll token first — SSH failures then don't leave
+		// partial state on the remote.
+		body := map[string]interface{}{"label": "bootstrap"}
+		if nodeSSHName != "" {
+			body["label"] = "bootstrap:" + nodeSSHName
+		}
+		tokenData, err := c.Do("POST", "/agent-tokens", body)
+		if err != nil {
+			return err
+		}
+		tokenObj, err := unwrapObject(tokenData, "token")
+		if err != nil {
+			return err
+		}
+		token := str(tokenObj, "token")
+		if token == "" {
+			return &APIError{Message: "enroll token missing from response", ExitCode: ExitError}
+		}
+
+		// Agent bootstrap endpoints live at /api/agents (no /v1) — strip
+		// the API version suffix off the client base.
+		apiRoot := strings.TrimSuffix(c.BaseURL, "/api/v1")
+		installCmd := fmt.Sprintf(
+			`curl -fsSL %q | bash -s -- --url %q --token %q --name %q`,
+			apiRoot+"/api/agents/install.sh", apiRoot, token, firstNonEmptyStr(nodeSSHName, nodeSSHTarget(args[0]).host),
+		)
+
+		if nodeSSHPrint {
+			fmt.Println(installCmd)
+			return nil
+		}
+
+		target := nodeSSHTarget(args[0])
+		if err := sshBootstrap(target, installCmd); err != nil {
+			return err
+		}
+		fmt.Printf("agent installing on %s — it should appear in `containr nodes list` within ~15s\n", target.host)
+		return nil
+	},
+}
+
+type sshTarget struct {
+	user string
+	host string
+	port string
+}
+
+func nodeSSHTarget(raw string) sshTarget {
+	t := sshTarget{port: "22"}
+	rest := raw
+	if at := strings.LastIndex(rest, "@"); at >= 0 {
+		t.user = rest[:at]
+		rest = rest[at+1:]
+	}
+	if colon := strings.LastIndex(rest, ":"); colon >= 0 && !strings.Contains(rest, "]") {
+		t.host, t.port = rest[:colon], rest[colon+1:]
+	} else {
+		t.host = rest
+	}
+	if t.user == "" {
+		if u, err := user.Current(); err == nil {
+			t.user = u.Username
+		}
+	}
+	return t
+}
+
+func sshAuthMethods(keyPath string) []ssh.AuthMethod {
+	var methods []ssh.AuthMethod
+
+	// ssh-agent first — matches how people actually manage keys.
+	if sock := os.Getenv("SSH_AUTH_SOCK"); sock != "" {
+		if conn, err := net.Dial("unix", sock); err == nil {
+			defer conn.Close()
+			methods = append(methods, ssh.PublicKeysCallback(agent.NewClient(conn).Signers))
+		}
+	}
+
+	var keyFiles []string
+	if keyPath != "" {
+		keyFiles = []string{keyPath}
+	} else if home, err := os.UserHomeDir(); err == nil {
+		for _, name := range []string{"id_ed25519", "id_rsa", "id_ecdsa"} {
+			p := filepath.Join(home, ".ssh", name)
+			if _, err := os.Stat(p); err == nil {
+				keyFiles = append(keyFiles, p)
+			}
+		}
+	}
+	for _, p := range keyFiles {
+		if signer, err := sshPrivateKey(p); err == nil {
+			methods = append(methods, ssh.PublicKeys(signer))
+		}
+	}
+	return methods
+}
+
+func sshPrivateKey(path string) (ssh.Signer, error) {
+	pem, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	signer, err := ssh.ParsePrivateKey(pem)
+	if err != nil {
+		var missing *ssh.PassphraseMissingError
+		if errors.As(err, &missing) {
+			fmt.Fprintf(os.Stderr, "passphrase for %s: ", path)
+			pass, readErr := term.ReadPassword(int(os.Stdin.Fd()))
+			fmt.Fprintln(os.Stderr)
+			if readErr != nil {
+				return nil, readErr
+			}
+			return ssh.ParsePrivateKeyWithPassphrase(pem, pass)
+		}
+		return nil, err
+	}
+	return signer, nil
+}
+
+func sshBootstrap(t sshTarget, remoteCmd string) error {
+	config := &ssh.ClientConfig{
+		User:            t.user,
+		Auth:            sshAuthMethods(nodeSSHKey),
+		HostKeyCallback: ssh.InsecureIgnoreHostKey(), // jarvis: TOFU would be better; ssh_known_hosts parsing is the upgrade path
+		Timeout:         15 * time.Second,
+	}
+	if len(config.Auth) == 0 {
+		return &APIError{Message: "no SSH auth methods (ssh-agent empty, no usable keys)", ExitCode: ExitError}
+	}
+
+	conn, err := ssh.Dial("tcp", net.JoinHostPort(t.host, t.port), config)
+	if err != nil {
+		return &APIError{Message: fmt.Sprintf("ssh connect: %v", err), ExitCode: ExitError}
+	}
+	defer conn.Close()
+
+	session, err := conn.NewSession()
+	if err != nil {
+		return err
+	}
+	defer session.Close()
+	session.Stdout = os.Stdout
+	session.Stderr = os.Stderr
+
+	// Root shells run directly; otherwise escalate via sudo. NOPASSWD
+	// sudo is assumed — a password prompt here means the operator should
+	// use --print and run the command themselves.
+	if t.user == "root" {
+		return session.Run(remoteCmd)
+	}
+	return session.Run("sudo -n " + remoteCmd)
+}
+
+func firstNonEmptyStr(values ...string) string {
+	for _, v := range values {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func init() {
+	nodesAddCmd.Flags().StringVar(&nodeSSHKey, "key", "", "SSH private key path (defaults: agent, ~/.ssh/id_*)")
+	nodesAddCmd.Flags().StringVar(&nodeSSHName, "name", "", "node display name (defaults to remote hostname)")
+	nodesAddCmd.Flags().BoolVar(&nodeSSHPrint, "print", false, "print the remote install command instead of running SSH")
+	NodesCmd.AddCommand(nodesAddCmd)
+}

app/backend/internal/cli/commands/services.go

@@ -60,7 +60,7 @@ var servicesGetCmd = &cobra.Command{
 			return nil
 		}
 		s, _ := unwrapObject(data, "service")
-		for _, k := range []string{"id", "name", "type", "status", "environment", "image", "git_repo", "git_branch", "domain", "port"} {
+		for _, k := range []string{"id", "name", "type", "status", "environment", "image", "git_repo", "git_branch", "domain", "port", "node_name"} {
 			fmt.Printf("%-14s %s\n", k+":", str(s, k))
 		}
 		return nil
@@ -79,7 +79,7 @@ var servicesCreateCmd = &cobra.Command{
 		body := map[string]interface{}{
 			"name": args[1],
 		}
-		for _, f := range []string{"type", "image", "git-repo", "git-branch", "build-path", "command", "environment", "domain", "restart-policy", "healthcheck-path", "cpu", "memory", "builder", "cpu-reserve", "memory-reserve", "static-cmd", "static-dir"} {
+		for _, f := range []string{"type", "image", "git-repo", "git-branch", "build-path", "command", "environment", "domain", "restart-policy", "healthcheck-path", "cpu", "memory", "builder", "cpu-reserve", "memory-reserve", "static-cmd", "static-dir", "node"} {
 			if v, _ := cmd.Flags().GetString(f); v != "" {
 				key := f
 				// JSON uses snake_case keys matching the API schema.
@@ -102,6 +102,8 @@ var servicesCreateCmd = &cobra.Command{
 					key = "static_build_cmd"
 				case "static-dir":
 					key = "static_dir"
+				case "node":
+					key = "node_id"
 				}
 				body[key] = v
 			}
@@ -159,7 +161,7 @@ var servicesUpdateCmd = &cobra.Command{
 			return err
 		}
 		body := map[string]interface{}{}
-		for _, f := range []string{"name", "image", "command", "domain", "restart-policy", "healthcheck-path", "cpu", "memory", "builder", "cpu-reserve", "memory-reserve", "static-cmd", "static-dir"} {
+		for _, f := range []string{"name", "image", "command", "domain", "restart-policy", "healthcheck-path", "cpu", "memory", "builder", "cpu-reserve", "memory-reserve", "static-cmd", "static-dir", "node"} {
 			if cmd.Flags().Changed(f) {
 				key := f
 				switch f {
@@ -175,6 +177,8 @@ var servicesUpdateCmd = &cobra.Command{
 					key = "static_build_cmd"
 				case "static-dir":
 					key = "static_dir"
+				case "node":
+					key = "node_id"
 				}
 				v, _ := cmd.Flags().GetString(f)
 				body[key] = v
@@ -490,6 +494,7 @@ func init() {
 	f.String("memory-reserve", "", "soft memory reservation (e.g. 128Mi)")
 	f.String("static-cmd", "", "build command for the static builder")
 	f.String("static-dir", "", "output dir for the static builder (default dist)")
+	f.String("node", "", "pin to a node agent id, or 'auto' for least-loaded (image services only)")
 
 	uf := servicesUpdateCmd.Flags()
 	uf.String("name", "", "service name")
@@ -514,6 +519,7 @@ func init() {
 	uf.String("static-dir", "", "output dir for the static builder (empty clears)")
 	uf.Bool("sleep", false, "enable scale-to-zero on idle (sleep mode)")
 	uf.Int("sleep-idle", 0, "idle minutes before sleeping (1-1440)")
+	uf.String("node", "", "pin to a node agent id, 'auto' for least-loaded, 'local' to clear")
 
 	for _, a := range []string{"start", "stop", "restart", "redeploy", "sleep", "wake"} {
 		verb := a

app/backend/internal/cli/root.go

@@ -94,6 +94,7 @@ func init() {
 	rootCmd.AddCommand(commands.BannersCmd)
 	rootCmd.AddCommand(commands.InvitesCmd)
 	rootCmd.AddCommand(commands.UpCmd)
+	rootCmd.AddCommand(commands.MigrateCmd)
 }
 
 func initConfig() {

app/backend/internal/database/sqlcdb/agents.sql.go

@@ -14,6 +14,18 @@ import (
 	"github.com/sqlc-dev/pqtype"
 )
 
+const clearServiceNodePins = `-- name: ClearServiceNodePins :execrows
+UPDATE services SET node_id = NULL, updated_at = NOW() WHERE node_id = $1
+`
+
+func (q *Queries) ClearServiceNodePins(ctx context.Context, nodeID sql.NullString) (int64, error) {
+	result, err := q.db.ExecContext(ctx, clearServiceNodePins, nodeID)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected()
+}
+
 const completeCommand = `-- name: CompleteCommand :one
 UPDATE agent_commands SET
     status = $3,
@@ -63,7 +75,7 @@ INSERT INTO node_agents (
     id, name, hostname, ip_address, port, status, version,
     capabilities, resources, last_heartbeat, metadata
 ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
-RETURNING id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata
+RETURNING id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata, auto_prune, schedulable
 `
 
 type CreateAgentParams struct {
@@ -109,6 +121,8 @@ func (q *Queries) CreateAgent(ctx context.Context, arg CreateAgentParams) (NodeA
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
 	)
 	return i, err
 }
@@ -228,8 +242,22 @@ func (q *Queries) DeleteAgent(ctx context.Context, id string) error {
 	return err
 }
 
+const deleteServiceContainersOnAgent = `-- name: DeleteServiceContainersOnAgent :exec
+DELETE FROM container_instances WHERE node_agent_id = $1 AND service_id = $2
+`
+
+type DeleteServiceContainersOnAgentParams struct {
+	NodeAgentID string `json:"node_agent_id"`
+	ServiceID   string `json:"service_id"`
+}
+
+func (q *Queries) DeleteServiceContainersOnAgent(ctx context.Context, arg DeleteServiceContainersOnAgentParams) error {
+	_, err := q.db.ExecContext(ctx, deleteServiceContainersOnAgent, arg.NodeAgentID, arg.ServiceID)
+	return err
+}
+
 const getAgent = `-- name: GetAgent :one
-SELECT id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata FROM node_agents WHERE id = $1
+SELECT id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata, auto_prune, schedulable FROM node_agents WHERE id = $1
 `
 
 func (q *Queries) GetAgent(ctx context.Context, id string) (NodeAgent, error) {
@@ -249,12 +277,14 @@ func (q *Queries) GetAgent(ctx context.Context, id string) (NodeAgent, error) {
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
 	)
 	return i, err
 }
 
 const getAgentByHostAndIP = `-- name: GetAgentByHostAndIP :one
-SELECT id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata FROM node_agents
+SELECT id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata, auto_prune, schedulable FROM node_agents
 WHERE hostname = $1 AND ip_address = $2
 LIMIT 1
 `
@@ -281,6 +311,8 @@ func (q *Queries) GetAgentByHostAndIP(ctx context.Context, arg GetAgentByHostAnd
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
 	)
 	return i, err
 }
@@ -378,6 +410,36 @@ func (q *Queries) GetContainerForAgent(ctx context.Context, arg GetContainerForA
 	return i, err
 }
 
+const getLastAgentCommandByType = `-- name: GetLastAgentCommandByType :one
+SELECT id, type, node_agent_id, container_id, payload, status, result, error, created_at, updated_at, completed_at FROM agent_commands
+WHERE node_agent_id = $1 AND type = $2
+ORDER BY created_at DESC LIMIT 1
+`
+
+type GetLastAgentCommandByTypeParams struct {
+	NodeAgentID string `json:"node_agent_id"`
+	Type        string `json:"type"`
+}
+
+func (q *Queries) GetLastAgentCommandByType(ctx context.Context, arg GetLastAgentCommandByTypeParams) (AgentCommand, error) {
+	row := q.db.QueryRowContext(ctx, getLastAgentCommandByType, arg.NodeAgentID, arg.Type)
+	var i AgentCommand
+	err := row.Scan(
+		&i.ID,
+		&i.Type,
+		&i.NodeAgentID,
+		&i.ContainerID,
+		&i.Payload,
+		&i.Status,
+		&i.Result,
+		&i.Error,
+		&i.CreatedAt,
+		&i.UpdatedAt,
+		&i.CompletedAt,
+	)
+	return i, err
+}
+
 const insertAgentHeartbeat = `-- name: InsertAgentHeartbeat :exec
 INSERT INTO agent_heartbeats (
     id, node_agent_id, timestamp, status, resources,
@@ -458,7 +520,7 @@ func (q *Queries) ListAgentHeartbeatsSince(ctx context.Context, arg ListAgentHea
 }
 
 const listAgents = `-- name: ListAgents :many
-SELECT id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata FROM node_agents ORDER BY created_at ASC
+SELECT id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata, auto_prune, schedulable FROM node_agents ORDER BY created_at ASC
 `
 
 func (q *Queries) ListAgents(ctx context.Context) ([]NodeAgent, error) {
@@ -484,6 +546,8 @@ func (q *Queries) ListAgents(ctx context.Context) ([]NodeAgent, error) {
 			&i.CreatedAt,
 			&i.UpdatedAt,
 			&i.Metadata,
+			&i.AutoPrune,
+			&i.Schedulable,
 		); err != nil {
 			return nil, err
 		}
@@ -627,6 +691,53 @@ func (q *Queries) ListPendingCommands(ctx context.Context, nodeAgentID string) (
 	return items, nil
 }
 
+const pickLeastLoadedAgent = `-- name: PickLeastLoadedAgent :one
+SELECT a.id FROM node_agents a
+LEFT JOIN LATERAL (
+    SELECT h.container_count FROM agent_heartbeats h
+    WHERE h.node_agent_id = a.id
+    ORDER BY h.timestamp DESC LIMIT 1
+) h ON true
+WHERE a.status = 'online' AND a.schedulable
+ORDER BY COALESCE(h.container_count, 0) ASC, a.created_at ASC
+LIMIT 1
+`
+
+func (q *Queries) PickLeastLoadedAgent(ctx context.Context) (string, error) {
+	row := q.db.QueryRowContext(ctx, pickLeastLoadedAgent)
+	var id string
+	err := row.Scan(&id)
+	return id, err
+}
+
+const scrubCommandPayload = `-- name: ScrubCommandPayload :exec
+UPDATE agent_commands SET payload = $2, updated_at = NOW() WHERE id = $1
+`
+
+type ScrubCommandPayloadParams struct {
+	ID      string                `json:"id"`
+	Payload pqtype.NullRawMessage `json:"payload"`
+}
+
+func (q *Queries) ScrubCommandPayload(ctx context.Context, arg ScrubCommandPayloadParams) error {
+	_, err := q.db.ExecContext(ctx, scrubCommandPayload, arg.ID, arg.Payload)
+	return err
+}
+
+const setAgentSchedulable = `-- name: SetAgentSchedulable :exec
+UPDATE node_agents SET schedulable = $2, updated_at = NOW() WHERE id = $1
+`
+
+type SetAgentSchedulableParams struct {
+	ID          string `json:"id"`
+	Schedulable bool   `json:"schedulable"`
+}
+
+func (q *Queries) SetAgentSchedulable(ctx context.Context, arg SetAgentSchedulableParams) error {
+	_, err := q.db.ExecContext(ctx, setAgentSchedulable, arg.ID, arg.Schedulable)
+	return err
+}
+
 const updateAgent = `-- name: UpdateAgent :one
 UPDATE node_agents SET
     name = $2,
@@ -639,9 +750,11 @@ UPDATE node_agents SET
     resources = $9,
     last_heartbeat = $10,
     metadata = $11,
+    auto_prune = $12,
+    schedulable = $13,
     updated_at = NOW()
 WHERE id = $1
-RETURNING id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata
+RETURNING id, name, hostname, ip_address, port, status, version, capabilities, resources, last_heartbeat, created_at, updated_at, metadata, auto_prune, schedulable
 `
 
 type UpdateAgentParams struct {
@@ -656,6 +769,8 @@ type UpdateAgentParams struct {
 	Resources     pqtype.NullRawMessage `json:"resources"`
 	LastHeartbeat sql.NullTime          `json:"last_heartbeat"`
 	Metadata      pqtype.NullRawMessage `json:"metadata"`
+	AutoPrune     bool                  `json:"auto_prune"`
+	Schedulable   bool                  `json:"schedulable"`
 }
 
 func (q *Queries) UpdateAgent(ctx context.Context, arg UpdateAgentParams) (NodeAgent, error) {
@@ -671,6 +786,8 @@ func (q *Queries) UpdateAgent(ctx context.Context, arg UpdateAgentParams) (NodeA
 		arg.Resources,
 		arg.LastHeartbeat,
 		arg.Metadata,
+		arg.AutoPrune,
+		arg.Schedulable,
 	)
 	var i NodeAgent
 	err := row.Scan(
@@ -687,6 +804,8 @@ func (q *Queries) UpdateAgent(ctx context.Context, arg UpdateAgentParams) (NodeA
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
 	)
 	return i, err
 }
@@ -731,3 +850,52 @@ func (q *Queries) UpdateContainerStatus(ctx context.Context, arg UpdateContainer
 	_, err := q.db.ExecContext(ctx, updateContainerStatus, arg.ID, arg.Status)
 	return err
 }
+
+const upsertServiceContainer = `-- name: UpsertServiceContainer :exec
+INSERT INTO container_instances (
+    id, name, image, project_id, service_id, node_agent_id,
+    status, resources, ports, environment, volumes, networks,
+    restart_policy, health_check
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
+ON CONFLICT (id) DO UPDATE SET
+    image = EXCLUDED.image,
+    status = EXCLUDED.status,
+    updated_at = NOW()
+`
+
+type UpsertServiceContainerParams struct {
+	ID            string                `json:"id"`
+	Name          string                `json:"name"`
+	Image         string                `json:"image"`
+	ProjectID     string                `json:"project_id"`
+	ServiceID     string                `json:"service_id"`
+	NodeAgentID   string                `json:"node_agent_id"`
+	Status        pqtype.NullRawMessage `json:"status"`
+	Resources     pqtype.NullRawMessage `json:"resources"`
+	Ports         pqtype.NullRawMessage `json:"ports"`
+	Environment   pqtype.NullRawMessage `json:"environment"`
+	Volumes       pqtype.NullRawMessage `json:"volumes"`
+	Networks      pqtype.NullRawMessage `json:"networks"`
+	RestartPolicy pqtype.NullRawMessage `json:"restart_policy"`
+	HealthCheck   pqtype.NullRawMessage `json:"health_check"`
+}
+
+func (q *Queries) UpsertServiceContainer(ctx context.Context, arg UpsertServiceContainerParams) error {
+	_, err := q.db.ExecContext(ctx, upsertServiceContainer,
+		arg.ID,
+		arg.Name,
+		arg.Image,
+		arg.ProjectID,
+		arg.ServiceID,
+		arg.NodeAgentID,
+		arg.Status,
+		arg.Resources,
+		arg.Ports,
+		arg.Environment,
+		arg.Volumes,
+		arg.Networks,
+		arg.RestartPolicy,
+		arg.HealthCheck,
+	)
+	return err
+}

app/backend/internal/database/sqlcdb/models.go

@@ -175,6 +175,8 @@ type NodeAgent struct {
 	CreatedAt     sql.NullTime          `json:"created_at"`
 	UpdatedAt     sql.NullTime          `json:"updated_at"`
 	Metadata      pqtype.NullRawMessage `json:"metadata"`
+	AutoPrune     bool                  `json:"auto_prune"`
+	Schedulable   bool                  `json:"schedulable"`
 }
 
 type Notification struct {
@@ -273,6 +275,7 @@ type Service struct {
 	MemoryReserve   string          `json:"memory_reserve"`
 	StaticBuildCmd  string          `json:"static_build_cmd"`
 	StaticDir       string          `json:"static_dir"`
+	NodeID          sql.NullString  `json:"node_id"`
 }
 
 type ServiceDomain struct {

app/backend/internal/database/sqlcdb/querier.go

@@ -12,6 +12,7 @@ import (
 )
 
 type Querier interface {
+	ClearServiceNodePins(ctx context.Context, nodeID sql.NullString) (int64, error)
 	CompleteCommand(ctx context.Context, arg CompleteCommandParams) (AgentCommand, error)
 	CountDatabaseServicesByUserAndName(ctx context.Context, arg CountDatabaseServicesByUserAndNameParams) (int64, error)
 	CountDatabasesUsingBackupTarget(ctx context.Context, targetID sql.NullString) (int64, error)
@@ -43,6 +44,7 @@ type Querier interface {
 	DeleteDatabaseServiceByIDAndUser(ctx context.Context, arg DeleteDatabaseServiceByIDAndUserParams) error
 	DeleteOutboundWebhookByIDAndUser(ctx context.Context, arg DeleteOutboundWebhookByIDAndUserParams) error
 	DeleteProjectByID(ctx context.Context, projectID uuid.UUID) (int64, error)
+	DeleteServiceContainersOnAgent(ctx context.Context, arg DeleteServiceContainersOnAgentParams) error
 	DeleteUserInvite(ctx context.Context, id uuid.UUID) error
 	DeleteUserTemplate(ctx context.Context, arg DeleteUserTemplateParams) (int64, error)
 	GetActiveAgentAuthTokenByHash(ctx context.Context, tokenHash string) (AgentAuthToken, error)
@@ -58,6 +60,7 @@ type Querier interface {
 	GetDatabaseServiceByID(ctx context.Context, id string) (DatabaseService, error)
 	GetDatabaseServiceByIDAndUser(ctx context.Context, arg GetDatabaseServiceByIDAndUserParams) (DatabaseService, error)
 	GetDatabaseServiceOwnerID(ctx context.Context, id string) (string, error)
+	GetLastAgentCommandByType(ctx context.Context, arg GetLastAgentCommandByTypeParams) (AgentCommand, error)
 	GetOutboundWebhookByID(ctx context.Context, id uuid.UUID) (OutboundWebhook, error)
 	GetOutboundWebhookByIDAndUser(ctx context.Context, arg GetOutboundWebhookByIDAndUserParams) (OutboundWebhook, error)
 	GetProjectByIDForUser(ctx context.Context, arg GetProjectByIDForUserParams) (Project, error)
@@ -99,8 +102,11 @@ type Querier interface {
 	MarkAllNotificationsReadByUser(ctx context.Context, arg MarkAllNotificationsReadByUserParams) error
 	MarkNotificationReadByIDAndUser(ctx context.Context, arg MarkNotificationReadByIDAndUserParams) error
 	MarkUserInviteUsed(ctx context.Context, arg MarkUserInviteUsedParams) error
+	PickLeastLoadedAgent(ctx context.Context) (string, error)
 	RevokeAgentAuthToken(ctx context.Context, id uuid.UUID) (AgentAuthToken, error)
 	RevokeUserToken(ctx context.Context, arg RevokeUserTokenParams) (int64, error)
+	ScrubCommandPayload(ctx context.Context, arg ScrubCommandPayloadParams) error
+	SetAgentSchedulable(ctx context.Context, arg SetAgentSchedulableParams) error
 	SetDatabaseBackupRemoteKeyByID(ctx context.Context, arg SetDatabaseBackupRemoteKeyByIDParams) error
 	SetDatabaseBackupScheduleByIDAndUser(ctx context.Context, arg SetDatabaseBackupScheduleByIDAndUserParams) error
 	SetDatabaseBackupStatusByID(ctx context.Context, arg SetDatabaseBackupStatusByIDParams) error
@@ -126,6 +132,7 @@ type Querier interface {
 	UpdateUserTemplate(ctx context.Context, arg UpdateUserTemplateParams) (int64, error)
 	UpdateWebhookDeliveryResult(ctx context.Context, arg UpdateWebhookDeliveryResultParams) error
 	UpsertEnvironmentVariable(ctx context.Context, arg UpsertEnvironmentVariableParams) error
+	UpsertServiceContainer(ctx context.Context, arg UpsertServiceContainerParams) error
 	UpsertServiceTemplate(ctx context.Context, arg UpsertServiceTemplateParams) error
 }
 

app/backend/internal/deployment/engine.go

@@ -11,10 +11,24 @@ import (
 	"containr/internal/types"
 )
 
+// NodeRunner deploys a service's containers onto a remote node agent.
+// Wired at boot; nil means every service runs on the local Docker host.
+type NodeRunner interface {
+	// ReconcileOnNode brings the node's containers in line with the spec and
+	// returns the resulting runtime state.
+	ReconcileOnNode(ctx context.Context, spec RuntimeSpec) (*RuntimeState, error)
+	// ControlService fans a lifecycle action ("start"|"stop"|"restart"|"remove")
+	// out to every replica of the service on the agent.
+	ControlService(ctx context.Context, serviceID, agentID, action string) error
+	// RemoveService tears down every replica of the service on the agent.
+	RemoveService(ctx context.Context, serviceID, agentID string) error
+}
+
 type DeploymentEngine struct {
 	buildManager  *build.BuildManager
 	dockerClient  *docker.Client
 	scheduler     *Scheduler
+	nodeRunner    NodeRunner
 	deployments   map[string]*Deployment
 	deploymentLog chan *DeploymentEvent
 }
@@ -67,6 +81,10 @@ type ServiceConfig struct {
 	// PublishedPort is the host port bound by the previous deployment; replica 0
 	// reuses it so public URLs survive restarts. 0 = pick ephemeral.
 	PublishedPort int32 `json:"published_port,omitempty"`
+	// NodeID pins the service to a registered node agent; "" = local Docker
+	// host. Remote placement requires a registry-pullable image — builds stay
+	// on the local host (build-on-node is not yet supported).
+	NodeID string `json:"node_id,omitempty"`
 }
 
 type PortMapping struct {
@@ -177,6 +195,11 @@ func (de *DeploymentEngine) DockerClient() *docker.Client {
 	return de.dockerClient
 }
 
+// SetNodeRunner wires remote-node dispatch for services pinned to an agent.
+func (de *DeploymentEngine) SetNodeRunner(r NodeRunner) {
+	de.nodeRunner = r
+}
+
 func NewDeploymentEngine(buildManager *build.BuildManager, dockerClient *docker.Client) *DeploymentEngine {
 	return &DeploymentEngine{
 		buildManager:  buildManager,
@@ -352,6 +375,7 @@ func (de *DeploymentEngine) deployService(ctx context.Context, deployment *Deplo
 		Maintenance:    cfg.Maintenance,
 		MaintenanceURL: cfg.MaintenanceURL,
 		BasicAuthUsers: cfg.BasicAuthUsers,
+		NodeID:         cfg.NodeID,
 	}
 	for _, pm := range cfg.PortMappings {
 		if spec.Port == 0 {

app/backend/internal/deployment/runtime.go

@@ -55,6 +55,8 @@ type RuntimeSpec struct {
 	Maintenance    bool          // redirect traffic to MaintenanceURL
 	MaintenanceURL string        // absolute URL; empty = serve empty response
 	BasicAuthUsers string        // htpasswd-format user:hash pairs, comma-separated
+	// NodeID pins the service to a node agent; "" runs on the local host.
+	NodeID string
 }
 
 // RuntimeContainer describes one live replica.
@@ -151,8 +153,15 @@ func (de *DeploymentEngine) ListServiceContainers(ctx context.Context, serviceID
 
 // ReconcileService brings live containers in line with the spec. When the
 // spec hash changed (image/env/ports/etc.) all replicas are recreated;
-// otherwise only the replica delta is applied.
+// otherwise only the replica delta is applied. A pinned NodeID routes the
+// whole reconcile to that agent's command queue instead of local Docker.
 func (de *DeploymentEngine) ReconcileService(ctx context.Context, spec RuntimeSpec) (*RuntimeState, error) {
+	if spec.NodeID != "" {
+		if de.nodeRunner == nil {
+			return nil, fmt.Errorf("service is pinned to node %s but remote dispatch is unavailable", spec.NodeID)
+		}
+		return de.nodeRunner.ReconcileOnNode(ctx, spec)
+	}
 	if spec.Replicas < 1 {
 		spec.Replicas = 1
 	}
@@ -498,6 +507,25 @@ func (de *DeploymentEngine) RemoveServiceContainers(ctx context.Context, service
 	return nil
 }
 
+// ControlServiceOnNode fans a lifecycle action out to the service's replicas
+// on a remote node agent. Callers resolve the pin; nil runner means the
+// platform was booted without node support.
+func (de *DeploymentEngine) ControlServiceOnNode(ctx context.Context, serviceID, nodeID, action string) error {
+	if de.nodeRunner == nil {
+		return fmt.Errorf("remote node control is not configured")
+	}
+	return de.nodeRunner.ControlService(ctx, serviceID, nodeID, action)
+}
+
+// RemoveServiceContainersOnNode tears down the service's replicas on a remote
+// node agent.
+func (de *DeploymentEngine) RemoveServiceContainersOnNode(ctx context.Context, serviceID, nodeID string) error {
+	if de.nodeRunner == nil {
+		return fmt.Errorf("remote node control is not configured")
+	}
+	return de.nodeRunner.RemoveService(ctx, serviceID, nodeID)
+}
+
 // RemoveProjectContainers deletes every managed container in a project.
 func (de *DeploymentEngine) RemoveProjectContainers(ctx context.Context, projectID string) error {
 	containers, err := de.dockerClient.ListContainersFiltered(ctx, filters.NewArgs(

app/backend/internal/mcpserver/server.go

@@ -53,7 +53,7 @@ func init() {
 	// Services
 	register(spec{"containr_services_list", "List services in a project", "GET", "/projects/{project_id}/services", []string{"project_id"}, nil, false})
 	register(spec{"containr_services_get", "Get a service by id", "GET", "/services/{id}", []string{"id"}, nil, false})
-	register(spec{"containr_services_create", "Create a service in a project. Args: name (required), type, image, git_repo, git_branch, environment, port, domain, replicas, volumes = [{type: volume|bind, source, target, read_only}], builder = auto|railpack|nixpacks|dockerfile|static, cpu, memory, cpu_reserve, memory_reserve, static_build_cmd, static_dir.", "POST", "/projects/{project_id}/services", []string{"project_id"}, nil, false})
+	register(spec{"containr_services_create", "Create a service in a project. Args: name (required), type, image, git_repo, git_branch, environment, port, domain, replicas, volumes = [{type: volume|bind, source, target, read_only}], builder = auto|railpack|nixpacks|dockerfile|static, cpu, memory, cpu_reserve, memory_reserve, static_build_cmd, static_dir, node_id (agent id | 'auto' = least-loaded online node; image services only — remote nodes can't run git builds).", "POST", "/projects/{project_id}/services", []string{"project_id"}, nil, false})
 	register(spec{"containr_services_delete", "Delete a service. Requires confirm:true.", "DELETE", "/services/{id}", []string{"id"}, nil, true})
 	register(spec{"containr_services_start", "Start a service", "POST", "/services/{id}/start", []string{"id"}, nil, false})
 	register(spec{"containr_services_stop", "Stop a service", "POST", "/services/{id}/stop", []string{"id"}, nil, false})
@@ -66,7 +66,7 @@ func init() {
 	register(spec{"containr_services_move", "Move a service to another project the caller owns. Args: id, project_id (required).", "POST", "/services/{id}/move", []string{"id"}, []string{"project_id"}, false})
 	register(spec{"containr_services_logs", "Get service runtime logs. Args: id, tail (default 100).", "GET", "/services/{id}/logs", []string{"id"}, nil, false})
 	register(spec{"containr_services_exec", "Run a one-off command in the service container (30s ceiling). Args: id, command (required).", "POST", "/services/{id}/exec", []string{"id"}, []string{"command"}, false})
-	register(spec{"containr_services_update", "Update a service. Args: id, name, image, command, domain, restart_policy, healthcheck_path, cpu, memory, replicas, port, volumes = [{type: volume|bind, source, target, read_only}] — volumes replaces the whole mount list; pass [] to clear. maintenance_mode (bool), basic_auth = [{username, password}] — replaces all creds; [] clears. builder = auto|railpack|nixpacks|dockerfile|static, cpu_reserve, memory_reserve, static_build_cmd, static_dir (empty string clears reserves/static fields). sleep_enabled (bool) + sleep_idle_minutes (1-1440) enable scale-to-zero on idle; a wake placeholder answers traffic while the service resumes.", "PUT", "/services/{id}", []string{"id"}, nil, false})
+	register(spec{"containr_services_update", "Update a service. Args: id, name, image, command, domain, restart_policy, healthcheck_path, cpu, memory, replicas, port, volumes = [{type: volume|bind, source, target, read_only}] — volumes replaces the whole mount list; pass [] to clear. maintenance_mode (bool), basic_auth = [{username, password}] — replaces all creds; [] clears. builder = auto|railpack|nixpacks|dockerfile|static, cpu_reserve, memory_reserve, static_build_cmd, static_dir (empty string clears reserves/static fields). sleep_enabled (bool) + sleep_idle_minutes (1-1440) enable scale-to-zero on idle; a wake placeholder answers traffic while the service resumes. node_id pins placement to a node agent ('auto' = least-loaded, 'local' = run on the Containr host).", "PUT", "/services/{id}", []string{"id"}, nil, false})
 
 	// Domains
 	register(spec{"containr_domains_list", "List domains attached to a service", "GET", "/services/{id}/domains", []string{"id"}, nil, false})
@@ -173,6 +173,12 @@ func init() {
 	register(spec{"containr_nodes_get", "Get a node agent (admin)", "GET", "/agents/{id}", []string{"id"}, nil, false})
 	register(spec{"containr_agent_tokens_issue", "Issue an agent onboarding token (admin). Args: label.", "POST", "/agent-tokens", nil, []string{"label"}, false})
 	register(spec{"containr_agent_tokens_list", "List agent onboarding tokens (admin)", "GET", "/agent-tokens", nil, nil, false})
+	register(spec{"containr_nodes_update", "Update a node agent (admin). Args: id; optional auto_prune, name.", "PUT", "/agents/{id}", []string{"id"}, []string{"auto_prune", "name"}, false})
+	register(spec{"containr_nodes_cordon", "Cordon a node: blocks new pins and 'auto' placements; running replicas stay (admin). Args: id.", "POST", "/agents/{id}/cordon", []string{"id"}, nil, false})
+	register(spec{"containr_nodes_uncordon", "Re-open a node for placement (admin). Args: id.", "POST", "/agents/{id}/uncordon", []string{"id"}, nil, false})
+	register(spec{"containr_nodes_drain", "Drain a node: cordon + remove all service containers via the agent + unpin affected services so they redeploy locally. Requires the node online (admin). Args: id.", "POST", "/agents/{id}/drain", []string{"id"}, nil, true})
+	register(spec{"containr_nodes_prune", "Enqueue a bounded docker system prune on a node (admin). Args: id; optional until (e.g. 168h), volumes (danger, off by default).", "POST", "/agents/{id}/prune", []string{"id"}, []string{"until", "volumes"}, true})
+	register(spec{"containr_nodes_commands", "List recent commands sent to a node agent (admin). Args: id.", "GET", "/agents/{id}/commands", []string{"id"}, nil, false})
 
 	// Scaling / HA / security
 	register(spec{"containr_scaling_status", "Autoscaler status", "GET", "/scaling/status", nil, nil, false})

app/backend/migrations_goose/20261107000000_agent_housekeeping.sql

@@ -0,0 +1,5 @@
+-- +goose Up
+ALTER TABLE node_agents ADD COLUMN IF NOT EXISTS auto_prune BOOLEAN NOT NULL DEFAULT false;
+
+-- +goose Down
+ALTER TABLE node_agents DROP COLUMN IF EXISTS auto_prune;

app/backend/migrations_goose/20261108000000_service_node_pin.sql

@@ -0,0 +1,19 @@
+-- +goose Up
+ALTER TABLE services ADD COLUMN IF NOT EXISTS node_id VARCHAR(255);
+
+-- +goose StatementBegin
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'services_node_id_fkey') THEN
+        ALTER TABLE services
+            ADD CONSTRAINT services_node_id_fkey
+            FOREIGN KEY (node_id) REFERENCES node_agents(id) ON DELETE SET NULL;
+    END IF;
+END $$;
+-- +goose StatementEnd
+
+CREATE INDEX IF NOT EXISTS idx_services_node_id ON services (node_id) WHERE node_id IS NOT NULL;
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_services_node_id;
+ALTER TABLE services DROP COLUMN IF EXISTS node_id;

app/backend/migrations_goose/20261109000000_node_schedulable.sql

@@ -0,0 +1,7 @@
+-- +goose Up
+ALTER TABLE node_agents ADD COLUMN IF NOT EXISTS schedulable BOOLEAN NOT NULL DEFAULT true;
+CREATE INDEX IF NOT EXISTS idx_node_agents_schedulable ON node_agents(schedulable) WHERE NOT schedulable;
+
+-- +goose Down
+DROP INDEX IF EXISTS idx_node_agents_schedulable;
+ALTER TABLE node_agents DROP COLUMN IF EXISTS schedulable;

app/backend/sqlc/queries/agents.sql

@@ -28,6 +28,8 @@ UPDATE node_agents SET
     resources = $9,
     last_heartbeat = $10,
     metadata = $11,
+    auto_prune = $12,
+    schedulable = $13,
     updated_at = NOW()
 WHERE id = $1
 RETURNING *;
@@ -107,3 +109,42 @@ RETURNING *;
 -- name: UpdateContainerStatus :exec
 UPDATE container_instances SET status = $2, updated_at = NOW()
 WHERE id = $1;
+
+-- name: GetLastAgentCommandByType :one
+SELECT * FROM agent_commands
+WHERE node_agent_id = $1 AND type = $2
+ORDER BY created_at DESC LIMIT 1;
+
+-- name: PickLeastLoadedAgent :one
+SELECT a.id FROM node_agents a
+LEFT JOIN LATERAL (
+    SELECT h.container_count FROM agent_heartbeats h
+    WHERE h.node_agent_id = a.id
+    ORDER BY h.timestamp DESC LIMIT 1
+) h ON true
+WHERE a.status = 'online' AND a.schedulable
+ORDER BY COALESCE(h.container_count, 0) ASC, a.created_at ASC
+LIMIT 1;
+
+-- name: SetAgentSchedulable :exec
+UPDATE node_agents SET schedulable = $2, updated_at = NOW() WHERE id = $1;
+
+-- name: ClearServiceNodePins :execrows
+UPDATE services SET node_id = NULL, updated_at = NOW() WHERE node_id = $1;
+
+-- name: UpsertServiceContainer :exec
+INSERT INTO container_instances (
+    id, name, image, project_id, service_id, node_agent_id,
+    status, resources, ports, environment, volumes, networks,
+    restart_policy, health_check
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
+ON CONFLICT (id) DO UPDATE SET
+    image = EXCLUDED.image,
+    status = EXCLUDED.status,
+    updated_at = NOW();
+
+-- name: DeleteServiceContainersOnAgent :exec
+DELETE FROM container_instances WHERE node_agent_id = $1 AND service_id = $2;
+
+-- name: ScrubCommandPayload :exec
+UPDATE agent_commands SET payload = $2, updated_at = NOW() WHERE id = $1;

app/backend/sqlc/schema.sql

@@ -66,7 +66,8 @@ CREATE TABLE services (
     cpu_reserve VARCHAR(20) NOT NULL DEFAULT '',
     memory_reserve VARCHAR(20) NOT NULL DEFAULT '',
     static_build_cmd VARCHAR(255) NOT NULL DEFAULT '',
-    static_dir VARCHAR(255) NOT NULL DEFAULT ''
+    static_dir VARCHAR(255) NOT NULL DEFAULT '',
+    node_id VARCHAR(255)
 );
 
 CREATE TABLE registries (
@@ -192,7 +193,9 @@ CREATE TABLE node_agents (
     last_heartbeat TIMESTAMP WITH TIME ZONE,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
     updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-    metadata JSONB
+    metadata JSONB,
+    auto_prune BOOLEAN NOT NULL DEFAULT false,
+    schedulable BOOLEAN NOT NULL DEFAULT true
 );
 
 CREATE TABLE container_instances (

app/frontend/src/app/App.tsx

@@ -26,6 +26,7 @@ import {
   ComponentShowcase,
   GitHubAppCallbackPage,
 } from '@/features/secondary/pages';
+import { NodeDetailPage } from '@/features/nodes/NodeDetailPage';
 import { AcceptInvitePage, SignInPage, SignUpPage } from '@/features/auth/pages';
 import { useAuthSession } from '@/lib/use-auth-session';
 import { useDemoMode } from '@/lib/demo-mode';
@@ -168,6 +169,7 @@ export default function App() {
           {/* Platform owner only */}
           <Route element={<AdminRequired />}>
             <Route path="/admin" element={<AdminPage />} />
+            <Route path="/nodes/:id" element={<NodeDetailPage />} />
           </Route>
 
           <Route path="*" element={<NotFoundPage />} />

app/frontend/src/features/nodes/NodeDetailPage.tsx

@@ -0,0 +1,440 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useMemo, useState } from 'react';
+import { Link, useNavigate, useParams } from 'react-router-dom';
+import {
+  cordonAgent,
+  deleteAgent,
+  drainAgent,
+  getAgent,
+  getAgentMetrics,
+  listAgentCommands,
+  listAgentContainers,
+  pruneAgent,
+  updateAgent,
+  type AgentMetricPoint,
+} from '@/lib/api-client';
+import { getCurrentUserProfile } from '@/lib/api-client';
+import { useAuthSession } from '@/lib/use-auth-session';
+import { useDemoMode } from '@/lib/demo-mode';
+import { formatBytes, formatRelative } from '@/lib/time';
+import { DemoRestricted } from '@/shared/components';
+import {
+  ArrowLeft, CheckCircle2, ChevronRight, Loader2, Pencil, XCircle,
+} from 'lucide-react';
+
+const TIME_RANGES = [
+  { label: '1h', value: '1h' },
+  { label: '24h', value: '24h' },
+  { label: '7d', value: '168h' },
+];
+
+export function NodeDetailPage() {
+  const { id = '' } = useParams();
+  const navigate = useNavigate();
+  const queryClient = useQueryClient();
+  const isDemoMode = useDemoMode();
+  const sessionQuery = useAuthSession({ enabled: !isDemoMode });
+  const profileQuery = useQuery({
+    queryKey: ['user-profile'],
+    queryFn: getCurrentUserProfile,
+    enabled: !isDemoMode && Boolean(sessionQuery.data),
+    retry: false,
+  });
+  const isAdmin = !isDemoMode && Boolean(profileQuery.data?.isAdmin);
+  const [timeRange, setTimeRange] = useState('24h');
+  const [rename, setRename] = useState<string | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [confirmVolumes, setConfirmVolumes] = useState(false);
+  const [confirmDrain, setConfirmDrain] = useState(false);
+
+  const agentQuery = useQuery({
+    queryKey: ['node-agent', id],
+    queryFn: () => getAgent(id),
+    enabled: !isDemoMode && id !== '',
+    refetchInterval: 15000,
+  });
+  const metricsQuery = useQuery({
+    queryKey: ['node-metrics', id, timeRange],
+    queryFn: () => getAgentMetrics(id, timeRange),
+    enabled: !isDemoMode && id !== '',
+    refetchInterval: 30000,
+  });
+  const containersQuery = useQuery({
+    queryKey: ['node-containers', id],
+    queryFn: () => listAgentContainers(id),
+    enabled: !isDemoMode && id !== '',
+    refetchInterval: 15000,
+  });
+  const commandsQuery = useQuery({
+    queryKey: ['node-commands', id],
+    queryFn: () => listAgentCommands(id),
+    enabled: !isDemoMode && id !== '',
+    refetchInterval: 15000,
+  });
+
+  const invalidate = () => {
+    queryClient.invalidateQueries({ queryKey: ['node-agent', id] });
+    queryClient.invalidateQueries({ queryKey: ['node-commands', id] });
+    queryClient.invalidateQueries({ queryKey: ['usage-agents'] });
+  };
+  const updateMutation = useMutation({
+    mutationFn: (body: { name?: string; auto_prune?: boolean }) => updateAgent(id, body),
+    onSuccess: () => { setRename(null); invalidate(); },
+  });
+  const pruneMutation = useMutation({
+    mutationFn: (volumes: boolean) => pruneAgent(id, { volumes }),
+    onSuccess: () => { setConfirmVolumes(false); invalidate(); },
+  });
+  const deleteMutation = useMutation({
+    mutationFn: () => deleteAgent(id),
+    onSuccess: () => navigate('/usage'),
+  });
+  const cordonMutation = useMutation({
+    mutationFn: (cordoned: boolean) => cordonAgent(id, cordoned),
+    onSuccess: invalidate,
+  });
+  const drainMutation = useMutation({
+    mutationFn: () => drainAgent(id),
+    onSuccess: () => { setConfirmDrain(false); invalidate(); },
+  });
+
+  const agent = agentQuery.data;
+  const metrics = useMemo(() => metricsQuery.data ?? [], [metricsQuery.data]);
+  const latest = metrics.length > 0 ? metrics[metrics.length - 1] : null;
+  const containers = containersQuery.data ?? [];
+  const commands = commandsQuery.data ?? [];
+
+  if (isDemoMode) return <DemoRestricted feature="Nodes" />;
+
+  if (agentQuery.isLoading) {
+    return <div className="px-8 py-10 text-xs text-[var(--text-muted)]">Loading node…</div>;
+  }
+  if (!agent) {
+    return (
+      <div className="px-8 py-10">
+        <p className="text-sm text-[var(--text-secondary)]">Node not found.</p>
+        <Link to="/usage" className="v-mono text-[11px] text-[var(--accent-primary)] hover:underline">← back to usage</Link>
+      </div>
+    );
+  }
+
+  const online = agent.status === 'online' || agent.status === 'connecting';
+
+  return (
+    <div className="min-h-screen">
+      <div className="border-b border-[var(--border-subtle)]">
+        <div className="w-full px-8 py-5">
+          <div className="flex items-center gap-2 v-mono text-[11px] text-[var(--text-tertiary)] mb-2">
+            <Link to="/usage" className="hover:text-[var(--text-primary)] flex items-center gap-1">
+              <ArrowLeft size={12} /> usage
+            </Link>
+            <ChevronRight size={10} />
+            <span className="text-[var(--text-primary)]">{agent.name}</span>
+          </div>
+          <div className="flex items-center justify-between gap-4 flex-wrap">
+            <div>
+              <h1 className="v-title">
+                {rename === null ? agent.name : rename}
+                {isAdmin && rename === null && (
+                  <button
+                    onClick={() => setRename(agent.name)}
+                    className="ml-2 inline-block align-middle text-[var(--text-muted)] hover:text-[var(--text-primary)]"
+                    title="Rename node"
+                  >
+                    <Pencil size={14} />
+                  </button>
+                )}
+                <span className="v-cursor">_</span>
+              </h1>
+              {rename !== null && (
+                <div className="mt-2 flex items-center gap-2">
+                  <input
+                    value={rename}
+                    onChange={(e) => setRename(e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter') updateMutation.mutate({ name: rename });
+                      if (e.key === 'Escape') setRename(null);
+                    }}
+                    autoFocus
+                    className="rounded-md border border-[var(--border-subtle)] bg-[var(--bg-tertiary)] px-2 py-1 text-sm text-[var(--text-primary)]"
+                  />
+                  <button onClick={() => updateMutation.mutate({ name: rename })} className="v-mono text-[11px] text-[var(--accent-primary)] hover:underline">save</button>
+                  <button onClick={() => setRename(null)} className="v-mono text-[11px] text-[var(--text-muted)] hover:underline">cancel</button>
+                </div>
+              )}
+              <p className="v-mono mt-1.5 text-[11px] text-[var(--text-tertiary)]">
+                {agent.hostname} · {agent.ipAddress}:{agent.port}
+                {agent.version ? ` · v${agent.version}` : ''}
+                {agent.lastHeartbeat ? ` · heartbeat ${formatRelative(agent.lastHeartbeat)}` : ''}
+              </p>
+              {meshAddresses(agent).length > 0 && (
+                <p className="v-mono mt-1 text-[11px] text-[var(--text-tertiary)]">
+                  mesh: {meshAddresses(agent).map(([iface, ip]) => `${iface}=${ip}`).join(' · ')}
+                </p>
+              )}
+            </div>
+            <div className="flex items-center gap-3">
+              <span className={`v-mono text-[11px] px-2 py-1 rounded-md border ${online
+                ? 'border-[var(--success)]/40 text-[var(--success)]'
+                : 'border-[var(--error)]/40 text-[var(--error)]'}`}>
+                {agent.status}
+              </span>
+              {!agent.schedulable && (
+                <span className="v-mono text-[11px] px-2 py-1 rounded-md border border-[var(--warning)]/40 text-[var(--warning)]">
+                  cordoned
+                </span>
+              )}
+              {isAdmin && (
+                <>
+                  <label className="flex items-center gap-1.5 v-mono text-[11px] text-[var(--text-tertiary)] cursor-pointer" title="Daily automatic docker prune">
+                    <input
+                      type="checkbox"
+                      checked={agent.autoPrune}
+                      onChange={(e) => updateMutation.mutate({ auto_prune: e.target.checked })}
+                      className="accent-[var(--accent-primary)]"
+                    />
+                    auto-prune
+                  </label>
+                  <button
+                    onClick={() => cordonMutation.mutate(agent.schedulable)}
+                    disabled={cordonMutation.isPending}
+                    title={agent.schedulable
+                      ? 'Block new placements — running replicas stay'
+                      : 'Re-open for placement'}
+                    className="v-mono text-[11px] px-3 py-1.5 rounded-md border border-[var(--border-subtle)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] disabled:opacity-50"
+                  >
+                    {agent.schedulable ? 'cordon' : 'uncordon'}
+                  </button>
+                  <button
+                    onClick={() => setConfirmDrain(true)}
+                    disabled={drainMutation.isPending || !online}
+                    title={online
+                      ? 'Cordon + remove all service containers + unpin services (they redeploy locally)'
+                      : 'Node must be online to drain'}
+                    className="v-mono text-[11px] px-3 py-1.5 rounded-md border border-[var(--warning)]/40 text-[var(--warning)] hover:bg-[var(--warning)]/10 disabled:opacity-50"
+                  >
+                    drain
+                  </button>
+                  <button
+                    onClick={() => setConfirmVolumes(true)}
+                    disabled={pruneMutation.isPending}
+                    className="v-mono text-[11px] px-3 py-1.5 rounded-md border border-[var(--border-subtle)] text-[var(--text-secondary)] hover:text-[var(--text-primary)] disabled:opacity-50"
+                  >
+                    prune now
+                  </button>
+                  <button
+                    onClick={() => setConfirmDelete(true)}
+                    className="v-mono text-[11px] px-3 py-1.5 rounded-md border border-[var(--error)]/40 text-[var(--error)] hover:bg-[var(--error)]/10"
+                  >
+                    remove
+                  </button>
+                </>
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className="px-8 py-6 space-y-6">
+        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+          <Stat label="cpu" value={latest ? `${latest.cpu.usage_percent.toFixed(0)}%` : '—'} sub={latest ? `${latest.cpu.cores} cores` : ''} />
+          <Stat label="memory" value={latest ? `${latest.memory.usage_percent.toFixed(0)}%` : '—'} sub={latest ? `${formatBytes(latest.memory.available)} free of ${formatBytes(latest.memory.limit)}` : ''} />
+          <Stat label="load 1m" value={latest ? latest.system_load.load_1m.toFixed(2) : '—'} sub={latest ? `5m ${latest.system_load.load_5m.toFixed(2)} · 15m ${latest.system_load.load_15m.toFixed(2)}` : ''} />
+          <Stat label="containers" value={latest ? String(latest.container_count) : String(containers.length)} sub="reported by agent" />
+        </div>
+
+        <section className="panel p-5">
+          <div className="flex items-center justify-between mb-4">
+            <h2 className="v-mono text-[11px] uppercase tracking-wider text-[var(--text-tertiary)]">telemetry</h2>
+            <div className="flex gap-1">
+              {TIME_RANGES.map((r) => (
+                <button
+                  key={r.value}
+                  onClick={() => setTimeRange(r.value)}
+                  className={`v-mono text-[11px] px-2.5 py-1 rounded-md border ${timeRange === r.value
+                    ? 'border-[var(--accent-primary)]/50 text-[var(--accent-primary)]'
+                    : 'border-[var(--border-subtle)] text-[var(--text-muted)] hover:text-[var(--text-primary)]'}`}
+                >
+                  {r.label}
+                </button>
+              ))}
+            </div>
+          </div>
+          {metricsQuery.isLoading ? (
+            <p className="text-xs text-[var(--text-muted)]">Loading metrics…</p>
+          ) : metrics.length < 2 ? (
+            <p className="text-xs text-[var(--text-muted)]">Not enough heartbeat history yet — the agent reports every few seconds once connected.</p>
+          ) : (
+            <div className="grid gap-6 md:grid-cols-2">
+              <Sparkline label="cpu %" points={metrics} value={(m) => m.cpu.usage_percent} />
+              <Sparkline label="memory %" points={metrics} value={(m) => m.memory.usage_percent} />
+            </div>
+          )}
+        </section>
+
+        <div className="grid gap-6 lg:grid-cols-2">
+          <section className="panel p-0">
+            <h2 className="v-mono text-[11px] uppercase tracking-wider text-[var(--text-tertiary)] px-5 pt-4 pb-3">containers</h2>
+            <div className="divide-y divide-[var(--border-subtle)] border-t border-[var(--border-subtle)]">
+              {containers.length === 0 && (
+                <p className="px-5 py-6 text-xs text-[var(--text-muted)]">No containers reported on this node.</p>
+              )}
+              {containers.map((c) => (
+                <div key={c.id} className="flex items-center justify-between gap-3 px-5 py-3">
+                  <div className="min-w-0">
+                    <p className="truncate text-sm text-[var(--text-primary)]">{c.name ?? c.id}</p>
+                    <p className="truncate v-mono text-[11px] text-[var(--text-tertiary)]">{c.image}</p>
+                  </div>
+                  <span className="v-mono text-[11px] text-[var(--text-secondary)]">{c.status ?? '—'}</span>
+                </div>
+              ))}
+            </div>
+          </section>
+
+          <section className="panel p-0">
+            <h2 className="v-mono text-[11px] uppercase tracking-wider text-[var(--text-tertiary)] px-5 pt-4 pb-3">command history</h2>
+            <div className="divide-y divide-[var(--border-subtle)] border-t border-[var(--border-subtle)]">
+              {commands.length === 0 && (
+                <p className="px-5 py-6 text-xs text-[var(--text-muted)]">No commands sent to this node yet.</p>
+              )}
+              {commands.slice(0, 15).map((cmd) => (
+                <div key={cmd.id} className="flex items-center justify-between gap-3 px-5 py-3">
+                  <div className="flex items-center gap-2 min-w-0">
+                    {cmd.status === 'completed'
+                      ? <CheckCircle2 size={13} className="text-[var(--success)] shrink-0" />
+                      : cmd.status === 'failed'
+                        ? <XCircle size={13} className="text-[var(--error)] shrink-0" />
+                        : <Loader2 size={13} className="text-[var(--text-muted)] animate-spin shrink-0" />}
+                    <span className="v-mono text-[11px] text-[var(--text-primary)]">{cmd.type}</span>
+                    {cmd.error && <span className="truncate text-[11px] text-[var(--error)]">{cmd.error}</span>}
+                  </div>
+                  <span className="v-mono text-[11px] text-[var(--text-muted)] whitespace-nowrap">
+                    {cmd.created_at ? formatRelative(cmd.created_at) : ''}
+                  </span>
+                </div>
+              ))}
+            </div>
+          </section>
+        </div>
+      </div>
+
+      {confirmVolumes && (
+        <ConfirmModal
+          title="Prune this node?"
+          body={`Runs a bounded docker system prune on ${agent.name}. Unused images, stopped containers, and networks are removed.`}
+          confirmLabel="prune"
+          danger={false}
+          extra={
+            <label className="flex items-center gap-2 text-xs text-[var(--text-secondary)] cursor-pointer">
+              <input type="checkbox" id="prune-volumes" className="accent-[var(--error)]" />
+              also prune volumes (can delete database data)
+            </label>
+          }
+          onCancel={() => setConfirmVolumes(false)}
+          onConfirm={() => {
+            const volumes = (document.getElementById('prune-volumes') as HTMLInputElement | null)?.checked ?? false;
+            pruneMutation.mutate(volumes);
+          }}
+          pending={pruneMutation.isPending}
+        />
+      )}
+      {confirmDrain && (
+        <ConfirmModal
+          title={`Drain ${agent.name}?`}
+          body="Every service container on this node is removed and the affected services are unpinned — they redeploy on the local host until re-pinned elsewhere. The node stays cordoned."
+          confirmLabel="drain node"
+          danger
+          onCancel={() => setConfirmDrain(false)}
+          onConfirm={() => drainMutation.mutate()}
+          pending={drainMutation.isPending}
+        />
+      )}
+      {confirmDelete && (
+        <ConfirmModal
+          title={`Remove ${agent.name}?`}
+          body="The agent record and its history are deleted. Containers running on the host are not stopped — uninstall the agent there separately."
+          confirmLabel="remove node"
+          danger
+          onCancel={() => setConfirmDelete(false)}
+          onConfirm={() => deleteMutation.mutate()}
+          pending={deleteMutation.isPending}
+        />
+      )}
+    </div>
+  );
+}
+
+function meshAddresses(agent: { metadata: Record<string, unknown> }): [string, string][] {
+  const mesh = agent.metadata?.mesh;
+  if (!mesh || typeof mesh !== 'object' || Array.isArray(mesh)) return [];
+  return Object.entries(mesh as Record<string, unknown>)
+    .filter((entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1] !== '');
+}
+
+function Stat({ label, value, sub }: { label: string; value: string; sub?: string }) {
+  return (
+    <div className="panel p-4">
+      <p className="v-mono text-[10px] uppercase tracking-wider text-[var(--text-tertiary)]">{label}</p>
+      <p className="mt-1 text-xl font-semibold text-[var(--text-primary)]">{value}</p>
+      {sub && <p className="mt-0.5 v-mono text-[11px] text-[var(--text-muted)]">{sub}</p>}
+    </div>
+  );
+}
+
+function Sparkline({ label, points, value }: {
+  label: string;
+  points: AgentMetricPoint[];
+  value: (m: AgentMetricPoint) => number;
+}) {
+  const w = 560;
+  const h = 90;
+  const vals = points.map(value);
+  const max = Math.max(100, ...vals);
+  const step = w / Math.max(points.length - 1, 1);
+  const polyline = vals.map((v, i) => `${(i * step).toFixed(1)},${(h - (v / max) * (h - 6)).toFixed(1)}`).join(' ');
+  return (
+    <div>
+      <p className="v-mono text-[10px] uppercase tracking-wider text-[var(--text-tertiary)] mb-2">
+        {label} — now {vals[vals.length - 1].toFixed(0)}% / peak {Math.max(...vals).toFixed(0)}%
+      </p>
+      <svg viewBox={`0 0 ${w} ${h}`} className="w-full h-24 rounded-md border border-[var(--border-subtle)] bg-[var(--bg-secondary)]">
+        <polyline points={polyline} fill="none" stroke="var(--accent-primary)" strokeWidth="1.5" />
+      </svg>
+    </div>
+  );
+}
+
+function ConfirmModal({ title, body, confirmLabel, danger, extra, onCancel, onConfirm, pending }: {
+  title: string;
+  body: string;
+  confirmLabel: string;
+  danger: boolean;
+  extra?: React.ReactNode;
+  onCancel: () => void;
+  onConfirm: () => void;
+  pending: boolean;
+}) {
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50" onClick={onCancel}>
+      <div className="panel w-full max-w-sm p-5" onClick={(e) => e.stopPropagation()}>
+        <h3 className="text-sm font-semibold text-[var(--text-primary)]">{title}</h3>
+        <p className="mt-2 text-xs text-[var(--text-secondary)]">{body}</p>
+        {extra && <div className="mt-3">{extra}</div>}
+        <div className="mt-5 flex justify-end gap-2">
+          <button onClick={onCancel} className="v-mono text-[11px] px-3 py-1.5 rounded-md border border-[var(--border-subtle)] text-[var(--text-secondary)]">
+            cancel
+          </button>
+          <button
+            onClick={onConfirm}
+            disabled={pending}
+            className={`v-mono text-[11px] px-3 py-1.5 rounded-md border disabled:opacity-50 ${danger
+              ? 'border-[var(--error)]/50 text-[var(--error)] hover:bg-[var(--error)]/10'
+              : 'border-[var(--accent-primary)]/50 text-[var(--accent-primary)] hover:bg-[var(--accent-primary)]/10'}`}
+          >
+            {pending ? 'working…' : confirmLabel}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

app/frontend/src/features/secondary/pages.tsx

@@ -11,6 +11,8 @@ import {
   getCurrentUserProfile,
   listAuditLogs,
   listAgents,
+  pruneAgent,
+  updateAgent,
   listBuilds,
   listGitProviders,
   listProjects,
@@ -293,6 +295,14 @@ export function UsagePage() {
     mutationFn: (id: string) => revokeAgentToken(id),
     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['agent-tokens'] }),
   });
+  const pruneMutation = useMutation({
+    mutationFn: (id: string) => pruneAgent(id),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['usage-agents'] }),
+  });
+  const autoPruneMutation = useMutation({
+    mutationFn: ({ id, on }: { id: string; on: boolean }) => updateAgent(id, { auto_prune: on }),
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ['usage-agents'] }),
+  });
 
   const builds = useMemo(
     () => (isDemoMode ? demoBuilds : buildsQuery.data?.builds ?? []),
@@ -377,9 +387,9 @@ export function UsagePage() {
   const totalAgentMemory = agents.reduce((sum, agent) => sum + agent.resources.memory.total, 0);
   const availableAgentMemory = agents.reduce((sum, agent) => sum + agent.resources.memory.available, 0);
   const agentEndpoint = getAgentPublicBaseUrl();
-  const connectCommand = `CONTAINR_API_URL=${getApiBaseUrl().replace(/\/api\/v1$/, '')} \\
-CONTAINR_AGENT_AUTH_TOKEN=${issuedToken?.token ?? '<token>'} \\
-containr-agent`;
+  const apiBase = getApiBaseUrl().replace(/\/api\/v1$/, '');
+  const installCommand = `curl -fsSL ${apiBase}/api/agents/install.sh | bash -s -- --url ${apiBase} --token ${issuedToken?.token ?? '<token>'}`;
+  const sshCommand = `containr nodes add --ssh <user@host>${issuedToken?.token ? '' : '  # run on a host with the CLI'}`;
 
   let buildActivityBody = 'Track deployment frequency and failed rollouts over time.';
   let runtimeBody = 'Build duration telemetry will appear after completed builds are available.';
@@ -603,12 +613,35 @@ containr-agent`;
                       agents.slice(0, 5).map((agent) => (
                         <div key={agent.id} className="flex items-center justify-between gap-3 border-b border-[var(--border-subtle)] px-4 py-3 last:border-b-0">
                           <div className="min-w-0">
-                            <p className="truncate text-sm font-medium text-[var(--text-primary)]">{agent.name}</p>
+                            <Link to={`/nodes/${agent.id}`} className="truncate text-sm font-medium text-[var(--text-primary)] hover:text-[var(--accent-primary)]">{agent.name}</Link>
                             <p className="truncate text-xs text-[var(--text-tertiary)]">{agent.hostname} · {agent.ipAddress}:{agent.port}</p>
                           </div>
-                          <div className="text-right">
-                            <p className="text-xs font-semibold text-[var(--text-primary)]">{agent.status}</p>
-                            <p className="text-xs text-[var(--text-tertiary)]">{formatBytes(agent.resources.memory.available)} free</p>
+                          <div className="flex items-center gap-3">
+                            {isAdmin && (
+                              <>
+                                <button
+                                  onClick={() => pruneMutation.mutate(agent.id)}
+                                  disabled={pruneMutation.isPending}
+                                  title="Enqueue a bounded docker prune on this node"
+                                  className="text-xs text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:underline disabled:opacity-50"
+                                >
+                                  Prune
+                                </button>
+                                <label className="flex items-center gap-1.5 text-xs text-[var(--text-tertiary)] cursor-pointer" title="Daily automatic docker prune">
+                                  <input
+                                    type="checkbox"
+                                    checked={agent.autoPrune}
+                                    onChange={(e) => autoPruneMutation.mutate({ id: agent.id, on: e.target.checked })}
+                                    className="accent-[var(--accent-primary)]"
+                                  />
+                                  auto
+                                </label>
+                              </>
+                            )}
+                            <div className="text-right">
+                              <p className="text-xs font-semibold text-[var(--text-primary)]">{agent.status}</p>
+                              <p className="text-xs text-[var(--text-tertiary)]">{formatBytes(agent.resources.memory.available)} free</p>
+                            </div>
                           </div>
                         </div>
                       ))
@@ -666,7 +699,8 @@ containr-agent`;
                     </p>
                   )}
 
-                  <pre className="mono text-xs text-[var(--text-secondary)] whitespace-pre-wrap">{connectCommand}</pre>
+                  <pre className="mono text-xs text-[var(--text-secondary)] whitespace-pre-wrap">{installCommand}</pre>
+                  <pre className="mono text-xs text-[var(--text-secondary)] whitespace-pre-wrap mt-2">{sshCommand}</pre>
                   <div className="mt-4 space-y-2 text-xs text-[var(--text-tertiary)]">
                     <p>Agent endpoint: <span className="mono text-[var(--text-primary)]">{agentEndpoint}</span></p>
                     <p>Use an issued token above, or set <span className="mono text-[var(--text-primary)]">CONTAINR_AGENT_AUTH_TOKENS</span> on the backend.</p>

app/frontend/src/features/service/pages/ServiceDetailPage.tsx

@@ -48,6 +48,7 @@ import {
   cloneService,
   moveService,
   listProjects,
+  listNodeOptions,
 } from '@/lib/api-client';
 import { getDemoProjectById, getDemoServiceById, getDemoCronJobsByService } from '@/lib/demo-data';
 import { useDemoMode } from '@/lib/demo-mode';
@@ -466,6 +467,7 @@ export function ServiceDetailPage() {
     onSuccess: () => {
       setNetworkForm(null);
       setSleepDraft(null);
+      setNodeDraft(null);
       invalidateService();
     },
   });
@@ -485,6 +487,13 @@ export function ServiceDetailPage() {
   const [domainChecks, setDomainChecks] = useState<Record<string, DomainCheckResult> | null>(null);
   const [accessForm, setAccessForm] = useState<{ maintenance: boolean; basicAuth: string } | null>(null);
   const [sleepDraft, setSleepDraft] = useState<{ id: string; enabled: boolean; minutes: string } | null>(null);
+  const [nodeDraft, setNodeDraft] = useState<string | null>(null);
+  const nodesQuery = useQuery({
+    queryKey: ['node-options'],
+    queryFn: listNodeOptions,
+    enabled: !isDemoMode,
+    staleTime: 30_000,
+  });
   const [buildForm, setBuildForm] = useState<{
     builder: string; cpuReserve: string; memoryReserve: string; staticCmd: string; staticDir: string;
   } | null>(null);
@@ -2384,6 +2393,58 @@ export function ServiceDetailPage() {
               </div>
             )}
 
+            {!isDemoMode && (nodesQuery.data?.length ?? 0) > 0 && (
+              <div className="mt-6 pt-6 border-t border-[var(--border-subtle)]">
+                <div className="mb-3">
+                  <h3 className="text-sm font-medium text-[var(--text-primary)]">Placement</h3>
+                  <p className="text-xs text-[var(--text-tertiary)] mt-0.5">
+                    Which node runs this service's containers. Remote nodes pull the image
+                    from its registry — git builds and domains stay on the local host.
+                  </p>
+                </div>
+                <div className="flex items-center gap-3 text-xs">
+                  <select
+                    value={nodeDraft ?? (service.nodeId || 'local')}
+                    onChange={(e) => setNodeDraft(e.target.value)}
+                    className="px-2 py-1.5 rounded-[var(--radius-md)] bg-[var(--surface-muted)] border border-[var(--border-subtle)] text-sm text-[var(--text-primary)]"
+                  >
+                    <option value="local">This server (local Docker)</option>
+                    <option value="auto">Auto — least-loaded online node</option>
+                    {(nodesQuery.data ?? []).map((n) => (
+                      <option key={n.id} value={n.id}>
+                        {n.name}{n.status !== 'online' ? ' (offline)' : ''}
+                      </option>
+                    ))}
+                  </select>
+                  {nodeDraft !== null && (
+                    <>
+                      <button
+                        type="button"
+                        disabled={updateServiceMutation.isPending}
+                        onClick={() => updateServiceMutation.mutate({ node_id: nodeDraft })}
+                        className="px-3 py-1.5 rounded-[var(--radius-md)] bg-[var(--accent-primary)] text-[var(--accent-on)] text-xs font-medium disabled:opacity-50"
+                      >
+                        Save
+                      </button>
+                      <button
+                        type="button"
+                        onClick={() => setNodeDraft(null)}
+                        className="text-[var(--text-tertiary)] hover:text-[var(--text-primary)]"
+                      >
+                        Cancel
+                      </button>
+                    </>
+                  )}
+                  {service.nodeName && nodeDraft === null && (
+                    <span className="text-[var(--text-tertiary)]">running on {service.nodeName}</span>
+                  )}
+                </div>
+                {updateServiceMutation.isError && (
+                  <p className="mt-2 text-xs text-[var(--error)]">{(updateServiceMutation.error as Error).message}</p>
+                )}
+              </div>
+            )}
+
             {!isDemoMode && (
               <div className="mt-6 pt-6 border-t border-[var(--border-subtle)]">
                 <div className="flex items-center justify-between mb-4">

app/frontend/src/generated/api-types.ts

@@ -7977,6 +7977,51 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/nodes/options": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Node options for service placement
+         * @description Minimal id/name/status list of registered node agents — available to any authenticated user for the service placement picker. Full agent data is admin-only under /agents.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Node options */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            nodes?: {
+                                id?: string;
+                                name?: string;
+                                status?: string;
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/agents": {
         parameters: {
             query?: never;
@@ -8363,6 +8408,330 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/agents/install.sh": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Agent install script
+         * @description Public bootstrap script — `curl | bash -s -- --url <api> --token <enroll-token>`.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Bourne shell installer */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/x-sh": string;
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/agents/download/{platform}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Download a bundled agent binary
+         * @description platform: linux-amd64 | linux-arm64. Bundled in release images; 404 when absent (install script falls back to GH releases).
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    platform: "linux-amd64" | "linux-arm64";
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Agent binary */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/octet-stream": string;
+                    };
+                };
+                /** @description No bundled binary for platform */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agents/{id}/prune": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Enqueue a bounded docker prune on a node
+         * @description Queues a `prune` command — `docker system prune -af`, volumes excluded unless requested.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Node agent ID */
+                    id: components["parameters"]["AgentIdParam"];
+                };
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description Only prune objects older than this duration (e.g. "168h"). */
+                        until?: string;
+                        /** @description Also prune volumes — destructive, off by default. */
+                        volumes?: boolean;
+                    };
+                };
+            };
+            responses: {
+                /** @description Prune command queued */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            command?: components["schemas"]["AgentCommand"];
+                        };
+                    };
+                };
+                /** @description Agent not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agents/{id}/cordon": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Cordon a node
+         * @description Sets `schedulable=false`: new explicit pins are rejected and `auto` placement skips the node. Already-pinned services keep running and can still reconcile — drain to evict them.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Node agent ID */
+                    id: components["parameters"]["AgentIdParam"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Node cordoned */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            id?: string;
+                            schedulable?: boolean;
+                        };
+                    };
+                };
+                /** @description Agent not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agents/{id}/uncordon": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Uncordon a node
+         * @description Re-opens the node for placement (`schedulable=true`).
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Node agent ID */
+                    id: components["parameters"]["AgentIdParam"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Node uncordoned */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            id?: string;
+                            schedulable?: boolean;
+                        };
+                    };
+                };
+                /** @description Agent not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agents/{id}/drain": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Drain a node
+         * @description Cordons the node, removes every service container via the agent command queue, and clears the affected services' `node_id` pins — they fall back to the local host on next deploy and can be re-pinned elsewhere. Requires the node to be online so it can acknowledge the removals.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Node agent ID */
+                    id: components["parameters"]["AgentIdParam"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Node drained */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            id?: string;
+                            schedulable?: boolean;
+                            services_drained?: number;
+                            services_unpinned?: number;
+                        };
+                    };
+                };
+                /** @description Agent not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Node is not online */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/agents/{id}/metrics": {
         parameters: {
             query?: never;
@@ -10505,6 +10874,10 @@ export interface components {
             sleep_enabled?: boolean;
             /** @description Idle timeout in minutes before sleeping (1-1440, default 15) */
             sleep_idle_minutes?: number;
+            /** @description Node agent id this service is pinned to; empty/null = local Docker host. 'auto' on create/update resolves to the least-loaded online agent. Remote nodes run registry-pulled images only (no git builds, no Traefik domains). */
+            node_id?: string;
+            /** @description Display name of the pinned node agent (read-only) */
+            node_name?: string;
             /** @description Computed public URL (published port or domain) */
             public_url?: string;
             /**
@@ -10575,6 +10948,8 @@ export interface components {
             static_build_cmd?: string;
             /** @description Output directory for the static builder (default dist) */
             static_dir?: string;
+            /** @description Node agent id to pin to, 'auto' = least-loaded online agent; omit/empty = local host */
+            node_id?: string;
         };
         UpdateServiceRequest: {
             /** @description Service name */
@@ -10636,6 +11011,8 @@ export interface components {
             sleep_enabled?: boolean;
             /** @description Idle timeout in minutes before sleeping (1-1440) */
             sleep_idle_minutes?: number;
+            /** @description Node agent id to pin to, 'auto' = least-loaded online agent, 'local' = run on the Containr host (clears the pin) */
+            node_id?: string;
         };
         ServiceDomain: {
             /** Format: uuid */
@@ -11751,6 +12128,10 @@ export interface components {
             metadata?: {
                 [key: string]: unknown;
             };
+            /** @description Enqueue a bounded docker prune on this node once per day. */
+            auto_prune?: boolean;
+            /** @description False on a cordoned/drained node — `auto` placement skips it and new explicit pins are rejected. */
+            schedulable?: boolean;
             /** Format: date-time */
             last_heartbeat?: string;
             /** Format: date-time */
@@ -11875,6 +12256,10 @@ export interface components {
             capabilities: components["schemas"]["AgentCapabilities"];
             /** @description May also be sent via the X-Agent-Token header */
             auth_token?: string;
+            /** @description Overlay-network interface IPs (tailscale/netbird/zerotier/wireguard). Stored under agent metadata.mesh; authoritative — send an empty object when no mesh interfaces exist. */
+            mesh?: {
+                [key: string]: string;
+            };
         };
         AgentHeartbeat: {
             agent_id?: string;

app/frontend/src/generated/docs-snapshot.ts

@@ -40,7 +40,7 @@ export const bundledDocs: BundledDoc[] = [
     "path": "guides/CLI.md",
     "section": "guides",
     "title": "Containr CLI",
-    "markdown": "# Containr CLI\n\nThe CLI controls every part of a Containr instance — the same API surface\nthe web UI uses. Build it with `scripts/build-cli.sh` or\n`go build ./cmd/cli` from `app/backend`.\n\n## Authentication\n\nCreate a personal access token in the web UI under\n**Settings → Personal Access Tokens** (or `containr tokens create`), then:\n\n```bash\ncontainr auth login cnp_...                      # verify + store\ncontainr auth login cnp_... --url https://containr.example.com\ncontainr auth login cnp_... --name production    # named profile\ncontainr auth status                             # show active profile + identity\ncontainr auth logout\n```\n\nResolution order for every command: `--token`/`--api-url` flags >\n`CONTAINR_TOKEN`/`CONTAINR_API_URL` env > active profile >\n`http://localhost:8080/api/v1`. The active profile is `--profile` >\n`CONTAINR_PROFILE` > `current_profile` in `~/.containr.yaml`.\n\n## Output and scripting\n\n- `--json` prints the raw API response — safe to pipe and parse.\n- `--yes` / `-y` skips confirmation on destructive commands (delete,\n  revoke, restore, failover). Non-interactive shells refuse destructive\n  commands without it.\n- Exit codes are stable: `0` ok, `1` error, `2` auth/permission,\n  `3` not found, `4` validation, `5` unreachable.\n\n## Commands\n\n```\nauth login|logout|status         token auth and profiles\ntokens list|create|revoke        personal access tokens\nprojects list|get|create|delete\nservices list|get|create|update|delete|start|stop|restart|redeploy\nservices clone|move              duplicate config or re-parent a service\nservices domains list|add|remove|default|check   multi-domain + DNS preflight\nregistries list|add|update|remove  private-image pull credentials\nvolumes list|delete              docker volume inventory + cleanup (admin)\ndeploy <service-id>              trigger a deployment (--no-cache, --commit-hash, --branch)\ndeployments list|get|logs|rollback|cancel\nlogs <service-id> [--follow]     runtime logs (SSE follow)\nexec <service-id> -- <cmd>       one-off container command\nvariables list|set|unset         env vars (secrets masked; --redeploy applies them)\nvariables shared list|set|unset  project shared vars — referenced as ${{shared.KEY}}\ndatabases list|get|create|update|delete|action|backup|restore|download-backup|import-backup\n                               import-backup <id> <file.tar.gz|-> uploads an archive as a restore\n                               point; ships offsite too when a backup target is assigned\ndatabases list|get|create|update|delete|action|backup|restore|download-backup\n                               create --public exposes the port on all interfaces;\n                               update <id> --public/--public=false toggles it (container recreates, data persists)\ndatabases register <name>      register an external database (--type --host --port --database --username --password --ssl; probed before storing)\ndatabases test-connection      probe a connection — by id, or ad-hoc flags\nbackup-targets list|add|update|remove|test\n                               S3-compatible archive destinations; add/update probe the bucket\n                               first, empty --access-key/--secret-key on update keep stored keys;\n                               update <db-id> --backup-target assigns a target (\"\" clears it)\ncron list|get|create|delete|trigger|executions\ntemplates list|get|create|delete|deploy|plan|import-compose|deploy-graph\n                               deploy --name --var K=V; plan dry-resolves expressions;\n                               import-compose <compose.yml|-> converts a compose file into\n                               a v2 graph config; deploy-graph <project-id> <config.json|->\n                               deploys an ad-hoc service graph\nimport compose <project-id> <compose.yml|->\n                               deploys a docker-compose file straight into a project —\n                               no template row. DB images become managed databases\n                               attached under their service name; --var K=V overrides\n                               template variables\nnodes list|get|delete|tokens     node agents + onboarding tokens (admin)\nscaling status|policies|services|scale\nha status|alerts|health|policies|enable|disable|failover\nsecurity scan|vulnerabilities|metrics\ngateway services|keys|analytics  (admin)\nadmin overview|users|settings|audit-logs\nnotifications list|read\nwebhooks list|create|update|delete|deliveries|test\n                               outbound signed webhooks — create <name> <url>\n                               --event 'service.*' (repeatable, '*' = all);\n                               deliveries are HMAC-signed (X-Containr-Signature)\noperations                       live ops view: active deploys, queue depth,\n                               24h failures, cron runs, backups\nactivity          
Line truncated
+    "markdown": "# Containr CLI\n\nThe CLI controls every part of a Containr instance — the same API surface\nthe web UI uses. Build it with `scripts/build-cli.sh` or\n`go build ./cmd/cli` from `app/backend`.\n\n## Authentication\n\nCreate a personal access token in the web UI under\n**Settings → Personal Access Tokens** (or `containr tokens create`), then:\n\n```bash\ncontainr auth login cnp_...                      # verify + store\ncontainr auth login cnp_... --url https://containr.example.com\ncontainr auth login cnp_... --name production    # named profile\ncontainr auth status                             # show active profile + identity\ncontainr auth logout\n```\n\nResolution order for every command: `--token`/`--api-url` flags >\n`CONTAINR_TOKEN`/`CONTAINR_API_URL` env > active profile >\n`http://localhost:8080/api/v1`. The active profile is `--profile` >\n`CONTAINR_PROFILE` > `current_profile` in `~/.containr.yaml`.\n\n## Output and scripting\n\n- `--json` prints the raw API response — safe to pipe and parse.\n- `--yes` / `-y` skips confirmation on destructive commands (delete,\n  revoke, restore, failover). Non-interactive shells refuse destructive\n  commands without it.\n- Exit codes are stable: `0` ok, `1` error, `2` auth/permission,\n  `3` not found, `4` validation, `5` unreachable.\n\n## Commands\n\n```\nauth login|logout|status         token auth and profiles\ntokens list|create|revoke        personal access tokens\nprojects list|get|create|delete\nservices list|get|create|update|delete|start|stop|restart|redeploy\nservices clone|move              duplicate config or re-parent a service\nservices domains list|add|remove|default|check   multi-domain + DNS preflight\nregistries list|add|update|remove  private-image pull credentials\nvolumes list|delete              docker volume inventory + cleanup (admin)\ndeploy <service-id>              trigger a deployment (--no-cache, --commit-hash, --branch)\ndeployments list|get|logs|rollback|cancel\nlogs <service-id> [--follow]     runtime logs (SSE follow)\nexec <service-id> -- <cmd>       one-off container command\nvariables list|set|unset         env vars (secrets masked; --redeploy applies them)\nvariables shared list|set|unset  project shared vars — referenced as ${{shared.KEY}}\ndatabases list|get|create|update|delete|action|backup|restore|download-backup|import-backup\n                               import-backup <id> <file.tar.gz|-> uploads an archive as a restore\n                               point; ships offsite too when a backup target is assigned\ndatabases list|get|create|update|delete|action|backup|restore|download-backup\n                               create --public exposes the port on all interfaces;\n                               update <id> --public/--public=false toggles it (container recreates, data persists)\ndatabases register <name>      register an external database (--type --host --port --database --username --password --ssl; probed before storing)\ndatabases test-connection      probe a connection — by id, or ad-hoc flags\nbackup-targets list|add|update|remove|test\n                               S3-compatible archive destinations; add/update probe the bucket\n                               first, empty --access-key/--secret-key on update keep stored keys;\n                               update <db-id> --backup-target assigns a target (\"\" clears it)\ncron list|get|create|delete|trigger|executions\ntemplates list|get|create|delete|deploy|plan|import-compose|deploy-graph\n                               deploy --name --var K=V; plan dry-resolves expressions;\n                               import-compose <compose.yml|-> converts a compose file into\n                               a v2 graph config; deploy-graph <project-id> <config.json|->\n                               deploys an ad-hoc service graph\nimport compose <project-id> <compose.yml|->\n                               deploys a docker-compose file straight into a project —\n                               no template row. DB images become managed databases\n                               attached under their service name; --var K=V overrides\n                               template variables\nnodes list|get|delete|tokens     node agents + onboarding tokens (admin)\nnodes add <user@host>            SSH bootstrap — one session installs the agent, then never needed again (--print for manual runs)\nnodes update|prune|commands      rename/auto-prune, bounded docker prune, command history\nmigrate railway                  pull a Railway project (services, vars, domains) via GraphQL and recreate it — --dry-run prints the plan\nmigrate dflow                    import a dflow project (services, vars, volumes, domains) via its Payload REST API — needs --url + --api-key, --dry-run prints the plan\nscaling status|policies|services|scale\nha status|alerts|health|policies|enable|disable|failover\nsecurity scan|vulnerabilities|metrics\ngateway services|keys|anLine truncated
   },
   {
     "path": "guides/CLOUDFLARE_SETUP.md",

app/frontend/src/lib/api-client.ts

@@ -84,9 +84,22 @@ export type ServiceEntity = {
   staticDir?: string;
   sleepEnabled?: boolean;
   sleepIdleMinutes?: number;
+  nodeId?: string;
+  nodeName?: string;
   publicUrl?: string;
 };
 
+export type NodeOption = {
+  id: string;
+  name: string;
+  status: string;
+};
+
+export async function listNodeOptions(): Promise<NodeOption[]> {
+  const payload = await requestJson<{ nodes?: NodeOption[] }>('/nodes/options');
+  return payload.nodes ?? [];
+}
+
 export type ServiceDomain = {
   id: string;
   service_id: string;
@@ -342,6 +355,9 @@ export type NodeAgentEntity = {
   version: string;
   capabilities: AgentCapabilities;
   resources: NodeResources;
+  autoPrune: boolean;
+  schedulable: boolean;
+  metadata: Record<string, unknown>;
   lastHeartbeat?: string;
   createdAt?: string;
   updatedAt?: string;
@@ -678,6 +694,8 @@ function normalizeService(service: RawService): ServiceEntity | null {
     staticDir: service.static_dir,
     sleepEnabled: service.sleep_enabled,
     sleepIdleMinutes: service.sleep_idle_minutes,
+    nodeId: service.node_id,
+    nodeName: service.node_name,
     publicUrl: service.public_url,
   };
 }
@@ -1078,6 +1096,9 @@ function normalizeAgent(agent: RawNodeAgent): NodeAgentEntity | null {
       },
     },
     lastHeartbeat: agent.last_heartbeat,
+    autoPrune: agent.auto_prune ?? false,
+    schedulable: agent.schedulable ?? true,
+    metadata: (agent.metadata ?? {}) as Record<string, unknown>,
     createdAt: agent.created_at,
     updatedAt: agent.updated_at,
   };
@@ -1116,6 +1137,84 @@ export async function listAgents(): Promise<NodeAgentEntity[]> {
   return normalizeAgentArray(payload.agents);
 }
 
+export async function updateAgent(id: string, body: { name?: string; auto_prune?: boolean }): Promise<NodeAgentEntity | null> {
+  const payload = await requestJson<{ agent?: RawNodeAgent }>(`/agents/${id}`, {
+    method: 'PUT',
+    body: JSON.stringify(body),
+  });
+  return payload.agent ? normalizeAgent(payload.agent) : null;
+}
+
+export async function pruneAgent(id: string, body?: { until?: string; volumes?: boolean }): Promise<void> {
+  await requestJson(`/agents/${id}/prune`, {
+    method: 'POST',
+    body: JSON.stringify(body ?? {}),
+  });
+}
+
+export async function cordonAgent(id: string, cordoned: boolean): Promise<void> {
+  await requestJson(`/agents/${id}/${cordoned ? 'cordon' : 'uncordon'}`, { method: 'POST' });
+}
+
+export type DrainResult = { services_drained: number; services_unpinned: number };
+
+export async function drainAgent(id: string): Promise<DrainResult> {
+  return requestJson<DrainResult>(`/agents/${id}/drain`, { method: 'POST' });
+}
+
+export async function getAgent(id: string): Promise<NodeAgentEntity | null> {
+  const payload = await requestJson<{ agent?: RawNodeAgent }>(`/agents/${id}`);
+  return payload.agent ? normalizeAgent(payload.agent) : null;
+}
+
+export async function deleteAgent(id: string): Promise<void> {
+  await requestJson(`/agents/${id}`, { method: 'DELETE' });
+}
+
+export type AgentMetricPoint = {
+  timestamp: string;
+  cpu: { usage: number; usage_percent: number; cores: number };
+  memory: { usage: number; usage_percent: number; limit: number; available: number };
+  system_load: { load_1m: number; load_5m: number; load_15m: number };
+  container_count: number;
+};
+
+export async function getAgentMetrics(id: string, timeRange = '24h'): Promise<AgentMetricPoint[]> {
+  const payload = await requestJson<{ metrics?: AgentMetricPoint[] }>(
+    `/agents/${id}/metrics?time_range=${encodeURIComponent(timeRange)}`,
+  );
+  return payload.metrics ?? [];
+}
+
+export type AgentContainer = {
+  id?: string;
+  name?: string;
+  image?: string;
+  status?: string;
+  service_id?: string;
+  created_at?: string;
+};
+
+export async function listAgentContainers(id: string): Promise<AgentContainer[]> {
+  const payload = await requestJson<{ containers?: AgentContainer[] }>(`/agents/${id}/containers`);
+  return payload.containers ?? [];
+}
+
+export type AgentCommand = {
+  id?: string;
+  type?: string;
+  status?: string;
+  result?: string;
+  error?: string;
+  created_at?: string;
+  completed_at?: string;
+};
+
+export async function listAgentCommands(id: string): Promise<AgentCommand[]> {
+  const payload = await requestJson<{ commands?: AgentCommand[] }>(`/agents/${id}/commands`);
+  return payload.commands ?? [];
+}
+
 export type AgentAuthToken = components['schemas']['AgentAuthToken'];
 export type AgentAuthTokenCreated = components['schemas']['AgentAuthTokenCreated'];
 

docs/api/openapi.yaml

@@ -5080,6 +5080,34 @@ paths:
                 $ref: '#/components/schemas/MessageResponse'
 
   # Node agents — management (JWT-authenticated)
+  /nodes/options:
+    get:
+      tags:
+        - Agents
+      summary: Node options for service placement
+      description: Minimal id/name/status list of registered node agents — available to any authenticated user for the service placement picker. Full agent data is admin-only under /agents.
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Node options
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  nodes:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                        name:
+                          type: string
+                        status:
+                          type: string
+
   /agents:
     get:
       tags:
@@ -5291,6 +5319,190 @@ paths:
               schema:
                 $ref: '#/components/schemas/MessageResponse'
 
+  /api/agents/install.sh:
+    servers:
+      - url: http://localhost:8080
+    get:
+      tags:
+        - Agents
+      summary: Agent install script
+      description: Public bootstrap script — `curl | bash -s -- --url <api> --token <enroll-token>`.
+      security: []
+      responses:
+        '200':
+          description: Bourne shell installer
+          content:
+            text/x-sh:
+              schema:
+                type: string
+
+  /api/agents/download/{platform}:
+    servers:
+      - url: http://localhost:8080
+    get:
+      tags:
+        - Agents
+      summary: Download a bundled agent binary
+      description: "platform: linux-amd64 | linux-arm64. Bundled in release images; 404 when absent (install script falls back to GH releases)."
+      security: []
+      parameters:
+        - name: platform
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [linux-amd64, linux-arm64]
+      responses:
+        '200':
+          description: Agent binary
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '404':
+          description: No bundled binary for platform
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /agents/{id}/prune:
+    post:
+      tags:
+        - Agents
+      summary: Enqueue a bounded docker prune on a node
+      description: Queues a `prune` command — `docker system prune -af`, volumes excluded unless requested.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/AgentIdParam'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                until:
+                  type: string
+                  description: Only prune objects older than this duration (e.g. "168h").
+                volumes:
+                  type: boolean
+                  description: Also prune volumes — destructive, off by default.
+      responses:
+        '202':
+          description: Prune command queued
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  command:
+                    $ref: '#/components/schemas/AgentCommand'
+        '404':
+          description: Agent not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /agents/{id}/cordon:
+    post:
+      tags:
+        - Agents
+      summary: Cordon a node
+      description: >-
+        Sets `schedulable=false`: new explicit pins are rejected and `auto`
+        placement skips the node. Already-pinned services keep running and can
+        still reconcile — drain to evict them.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/AgentIdParam'
+      responses:
+        '200':
+          description: Node cordoned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: string }
+                  schedulable: { type: boolean }
+        '404':
+          description: Agent not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /agents/{id}/uncordon:
+    post:
+      tags:
+        - Agents
+      summary: Uncordon a node
+      description: Re-opens the node for placement (`schedulable=true`).
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/AgentIdParam'
+      responses:
+        '200':
+          description: Node uncordoned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: string }
+                  schedulable: { type: boolean }
+        '404':
+          description: Agent not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
+  /agents/{id}/drain:
+    post:
+      tags:
+        - Agents
+      summary: Drain a node
+      description: >-
+        Cordons the node, removes every service container via the agent
+        command queue, and clears the affected services' `node_id` pins —
+        they fall back to the local host on next deploy and can be re-pinned
+        elsewhere. Requires the node to be online so it can acknowledge the
+        removals.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/AgentIdParam'
+      responses:
+        '200':
+          description: Node drained
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id: { type: string }
+                  schedulable: { type: boolean }
+                  services_drained: { type: integer }
+                  services_unpinned: { type: integer }
+        '404':
+          description: Agent not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: Node is not online
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
   /agents/{id}/metrics:
     get:
       tags:
@@ -6756,6 +6968,12 @@ components:
         sleep_idle_minutes:
           type: integer
           description: Idle timeout in minutes before sleeping (1-1440, default 15)
+        node_id:
+          type: string
+          description: Node agent id this service is pinned to; empty/null = local Docker host. 'auto' on create/update resolves to the least-loaded online agent. Remote nodes run registry-pulled images only (no git builds, no Traefik domains).
+        node_name:
+          type: string
+          description: Display name of the pinned node agent (read-only)
         public_url:
           type: string
           description: Computed public URL (published port or domain)
@@ -6847,6 +7065,9 @@ components:
         static_dir:
           type: string
           description: Output directory for the static builder (default dist)
+        node_id:
+          type: string
+          description: Node agent id to pin to, 'auto' = least-loaded online agent; omit/empty = local host
 
     UpdateServiceRequest:
       type: object
@@ -6933,6 +7154,9 @@ components:
         sleep_idle_minutes:
           type: integer
           description: Idle timeout in minutes before sleeping (1-1440)
+        node_id:
+          type: string
+          description: Node agent id to pin to, 'auto' = least-loaded online agent, 'local' = run on the Containr host (clears the pin)
 
     ServiceDomain:
       type: object
@@ -8810,6 +9034,14 @@ components:
         metadata:
           type: object
           additionalProperties: true
+        auto_prune:
+          type: boolean
+          description: Enqueue a bounded docker prune on this node once per day.
+        schedulable:
+          type: boolean
+          description: >-
+            False on a cordoned/drained node — `auto` placement skips it and
+            new explicit pins are rejected.
         last_heartbeat:
           type: string
           format: date-time
@@ -9043,6 +9275,11 @@ components:
         auth_token:
           type: string
           description: May also be sent via the X-Agent-Token header
+        mesh:
+          type: object
+          additionalProperties:
+            type: string
+          description: Overlay-network interface IPs (tailscale/netbird/zerotier/wireguard). Stored under agent metadata.mesh; authoritative — send an empty object when no mesh interfaces exist.
 
     AgentHeartbeat:
       type: object

docs/guides/CLI.md

@@ -72,6 +72,10 @@ import compose <project-id> <compose.yml|->
                                attached under their service name; --var K=V overrides
                                template variables
 nodes list|get|delete|tokens     node agents + onboarding tokens (admin)
+nodes add <user@host>            SSH bootstrap — one session installs the agent, then never needed again (--print for manual runs)
+nodes update|prune|commands      rename/auto-prune, bounded docker prune, command history
+migrate railway                  pull a Railway project (services, vars, domains) via GraphQL and recreate it — --dry-run prints the plan
+migrate dflow                    import a dflow project (services, vars, volumes, domains) via its Payload REST API — needs --url + --api-key, --dry-run prints the plan
 scaling status|policies|services|scale
 ha status|alerts|health|policies|enable|disable|failover
 security scan|vulnerabilities|metrics
@@ -128,6 +132,30 @@ redeploy — `containr deploy <id>` to apply immediately.
 `volumes list` shows the node's docker volume inventory with in-use
 flags; `volumes delete <name>` removes an unused volume (admin scope).
 
+## Node placement
+
+Pin a service to a registered node agent, or let the scheduler pick the
+least-loaded online node:
+
+```bash
+containr services create --project <id> --name api --image ghcr.io/x/api:v1 --node <agent-id>
+containr services update <id> --node auto    # least-loaded online node
+containr services update <id> --node local   # move back to this server
+```
+
+Remote nodes run registry-pulled images only — git builds, domains
+(Traefik lives on the host), and sleep detection stay local. Start,
+stop, restart, redeploy, and delete all fan out to the pinned node's
+agent. `services get` shows the resolved `node_name`.
+
+Take a node out of rotation or empty it entirely (admin):
+
+```bash
+containr nodes cordon <id>    # no new pins; running replicas stay
+containr nodes uncordon <id>
+containr nodes drain <id>     # cordon + remove its containers + unpin services
+```
+
 ## Service domains and access
 
 A service can carry multiple hostnames; the default is mirrored to