feat(templates): git compose import, six stack seeds, empty-default vars (#63)

* feat(templates): git compose import, six stack seeds, empty-default vars

- POST /templates/import/git fetches a compose file from any git remote
  (clone URL, ssh, owner/repo via connected providers — private repos
  included), ref selects branch or commit. Path defaults through
  compose.yaml/yml then docker-compose.yml/yaml. Reuses the build-on-node
  checkout machinery; repo-relative paths are containment-checked.
- CLI `templates import-git <repo> [path] [--ref]`, MCP
  containr_templates_import_git, OpenAPI entry, and a paste/git toggle
  in the template import dialog.
- {{VAR:-}} with an empty default now resolves instead of reporting the
  var missing — matches shell :- semantics.
- SeedTemplates gains six official graph stacks — n8n (pg+redis+worker),
  Gitea, Nextcloud, Vaultwarden, Umami, Immich — wired with
  {{service.*}} refs and {{secret}} credentials; no hardcoded passwords.
- TestSeedTemplatesResolveCleanly parses, topo-sorts, validates, and
  resolves every seeded graph — catalog drift can't merge silently.
- templates/n8n.md compose block had invalid YAML (mixed depends_on
  list/map) — fixed so the documented stack actually parses.

Verified live: import/git on a dumb-HTTP repo returns the converted
graph (db image → managed postgresql), path/ref/traversal/unauth edges
return clean errors, tpl-n8n plan resolves with zero unresolved vars.

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

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

* ci: pre-pull compose-smoke images via gcr mirror

Anonymous Docker Hub pulls rate-limit shared CI egress IPs — the compose
boot smoke flaked on traefik:pull. postgres/traefik are library/* images
served by mirror.gcr.io without auth; compose reuses the retagged local
images, falling back to a normal pull when the mirror misses.

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

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

* ci: route docker.io through gcr mirror for compose smoke

Pull-time pre-pulls don't cover BuildKit's base-image metadata lookups
(node:22-alpine, nginx:alpine, golang:1.26-alpine all 429). Daemon-level
registry-mirrors covers pulls and resolution in one move.

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

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

* ci: mirror docker.io in buildx for image publish job

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

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

* ci: route smoke pulls/builds through mirror.gcr.io via compose overlay

daemon.json registry-mirrors isn't honored by the runner's containerd
image store. Qualify refs directly: ARG-parameterized Dockerfile FROMs
(defaults unchanged) plus a CI-only compose overlay that points image
pulls and build args at mirror.gcr.io.

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>

.env.example

@@ -47,6 +47,16 @@ SECRETS_KEY=
 CONTAINR_AGENT_AUTH_TOKEN=replace_with_strong_agent_secret
 # Optional rotation list (comma-separated). When set, this takes precedence.
 # CONTAINR_AGENT_AUTH_TOKENS=current_secret,next_secret
+# Bundled agent binaries dir served at /api/agents/download/:platform.
+# CONTAINR_AGENT_BIN_DIR=/agents
+# Directory Traefik's file provider watches. The backend writes one
+# config per remote service here so domains route to node agents. The
+# infra compose wires a shared volume — set only for custom layouts.
+# TRAEFIK_DYNAMIC_DIR=/traefik-dynamic
+# Optional remote template catalog (another Containr instance). Its
+# templates merge into GET /templates as source:"registry" and
+# materialize locally on deploy. The bundled catalog works without it.
+# CONTAINR_TEMPLATE_REGISTRY_URL=https://templates.example.com
 CORS_ORIGINS=http://localhost:3000,http://localhost:8080
 # Optional build-time API URL overrides. Leave empty for the default
 # same-origin setup - the frontend nginx proxies /api to the backend, which

.github/compose.ci.yml

@@ -0,0 +1,18 @@
+# CI-only compose overlay: pull and build through mirror.gcr.io so shared
+# runner egress IPs never touch docker.io (anonymous pulls get 429'd).
+# Production refs in infra/docker-compose.yml stay unchanged.
+services:
+  postgres:
+    image: mirror.gcr.io/library/postgres:15-alpine
+  traefik:
+    image: mirror.gcr.io/library/traefik:v3.2
+  backend:
+    build:
+      args:
+        GO_IMAGE: mirror.gcr.io/library/golang:1.26-alpine
+        NODE_IMAGE: mirror.gcr.io/library/node:22-alpine
+  frontend:
+    build:
+      args:
+        NODE_IMAGE: mirror.gcr.io/library/node:22-alpine
+        NGINX_IMAGE: mirror.gcr.io/library/nginx:alpine

.github/workflows/ci.yml

@@ -163,11 +163,13 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Boot stack
+        # .github/compose.ci.yml swaps every docker.io ref for
+        # mirror.gcr.io — anonymous Hub pulls 429 on shared CI IPs.
         run: |
           BETTER_AUTH_SECRET=$(openssl rand -hex 32)
           BETTER_AUTH_INTERNAL_TOKEN=$(openssl rand -hex 32)
           export BETTER_AUTH_SECRET BETTER_AUTH_INTERNAL_TOKEN
-          docker compose -f infra/docker-compose.yml up -d --build postgres dragonfly backend frontend traefik
+          docker compose -f infra/docker-compose.yml -f .github/compose.ci.yml up -d --build postgres dragonfly backend frontend traefik
 
       - name: Wait for backend health
         run: |
@@ -204,7 +206,13 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Setup Docker Buildx
+        # Mirror docker.io through gcr — shared CI IPs hit anonymous
+        # rate limits on base-image metadata resolution otherwise.
         uses: docker/setup-buildx-action@v3
+        with:
+          config-inline: |
+            [registry."docker.io"]
+              mirrors = ["mirror.gcr.io"]
 
       - name: Login to GHCR
         if: github.event_name != 'pull_request'
@@ -248,6 +256,10 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta-backend.outputs.tags }}
           labels: ${{ steps.meta-backend.outputs.labels }}
+          # Stamp the release tag into the binary so the in-app upgrade
+          # check knows what it's running ("dev" disables it).
+          build-args: |
+            VERSION=${{ github.ref_type == 'tag' && github.ref_name || 'dev' }}
           cache-from: type=gha,scope=backend
           cache-to: type=gha,mode=max,scope=backend
 

README.md

@@ -49,7 +49,7 @@ dedicated console.
 - **Public project catalog** — approved projects are browsable anonymously; new projects stay private until an admin approves them
 - **Admin console** (`/admin`) — platform stats, project approval/edit/delete, user admin management
 - **Private networking** — every project gets an isolated Docker network; services reach each other by name (`web:3000`) and share variables via `${{service.KEY}}` references
-- **Deployments & builds** — Docker deploys with history, image rollback, live build status
+- **Deployments & builds** — Docker deploys with history, image rollback, live build status; git-sourced services build directly on remote node agents (no registry required)
 - **Runtime** — replicas, published ports, domains, health checks, restart policies; start/stop/restart/redeploy from canvas or service page
 - **Git integration** — GitHub, GitLab, Bitbucket, Gitea; webhooks, GitHub App
 - **Managed databases** — create PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Dragonfly, or ClickHouse directly from `/databases`, with backup/restore

ROADMAP2.md

@@ -91,10 +91,10 @@ Legend: ✅ done · 🟡 partial/different · ❌ missing · ➖ not applicable
 | White-label (logo/favicon/title/OG/theme colors) | ❌ | `app_settings.branding` — **Containr remains the default brand** |
 | Activity feed (icon/severity/category/metadata, 90-day TTL job) | ✅ `/activity` + project view | — |
 | Admin metrics dashboard (users/servers/queued/failed counts) | 🟡 `/admin` exists | Extend |
-| **Impersonate user** | ❌ | Admin support tool |
+| **Impersonate user** | ✅ admin token + `impersonated_by` claim (browser swap pending) | Done (CLI/API/MCP) |
 | In-app docs (content-collections markdown) | ✅ `/docs` | — |
-| Dynamic client-side filter framework (535-line `filter.utils`) | 🟡 audit page filters only | Reuse pattern for tables |
+| Dynamic client-side filter framework (535-line `filter.utils`) | ✅ `dynamic-filter.ts` + URL state; audit/builds/activity | Done |
-| Ops "bubble" (queue monitor, terminal, sync) | ❌ | Operations page |
+| Ops "bubble" (queue monitor, terminal, sync) | ✅ `/operations` + interactive terminal | Done |
 
 #### Agent surface
 | dflow capability | Containr status | Action |
@@ -103,8 +103,8 @@ Legend: ✅ done · 🟡 partial/different · ❌ missing · ➖ not applicable
 | CLI | ❌ | none in dflow — **Containr CLI is a genuine leap past it** |
 | MCP | ❌ | none — same leap |
 | Railway migrator script | ❌ | `containr migrate railway` |
-| GitHub App **manifest flow** (instance self-provisions the App) | 🟡 env-configured App | `POST /git/github-app/manifest` flow |
+| GitHub App **manifest flow** (instance self-provisions the App) | ✅ manifest + convert + App webhook | Done |
-| fork-sync webhook deploy trigger | ❌ | ~20 lines on receiver |
+| fork-sync webhook deploy trigger | ✅ sync/repository_dispatch/workflow_run | Done |
 | Azure DevOps provider | ❌ | Optional (dflow does token-clone only) |
 
 ---
@@ -228,48 +228,127 @@ goroutines; this fixes correctness *and* unlocks the ops surface.
 
 ## 6. Phase E — Templates v2 (absorbs compose-catalog spec + dflow graph templates)
 
-- [ ] **Template = ordered service graph** — `services[]` entries with
+- [x] **Template = ordered service graph** — `services[]` entries with
   `{name, type, source, build, ports, volumes, variables, depends_on}`;
-  deploy order from dependency refs.
+  deploy order from dependency refs. `templategraph.go`,
-- [ ] **Expressions** — `${{service.KEY}}` (already the runtime ref
+  `topoSortServices`.
-  syntax — reuse), `{{secret(len,"charset")}}`, `{{random:int}}`,
+- [x] **Expressions** — `{{service.KEY.prop}}` (host/port/user/password/
-  `{{VAR:-default}}`; `POST /templates/:id/plan` returns the resolved
+  database/url), `{{secret}}`/`{{secret(N)}}`, `{{random:N}}`,
-  graph without deploying (agents love this).
+  `{{VAR:-default}}` (incl. explicitly-empty defaults); `POST
-- [ ] **Compose import** — `POST /templates/import/compose` (compose-go
+  /templates/:id/plan` returns the resolved graph without deploying.
-  parser → graph), `POST /templates/import/github` (compose file from
+- [x] **Compose import** — `POST /templates/import/compose` (yaml →
-  repo path). Implements `docs/superpowers/specs/2026-04-14-*`.
+  graph, known DB images become managed databases), `POST
-- [ ] **Graph deploy pipeline** — creates project + services in
+  /templates/import/git` (compose file fetched from any git repo — clone
-  dependency order, resolves vars, triggers builds; defined
+  URL, ssh remote, or owner/repo via connected providers, `ref` selects
-  partial-failure policy.
+  branch/commit); `templates import-compose|import-git` CLI, MCP tools,
+  paste-or-git toggle in the template UI.
+- [x] **Graph deploy pipeline** — creates services in dependency order,
+  resolves vars/secrets, triggers builds. `deployTemplateGraph`,
+  `POST /templates/deploy` (inline), `POST /projects/:id/import-compose`.
 - [ ] **Visual template builder** — canvas mode: drop git/image/db
   nodes, wire refs, set order, save/publish. Reuses existing canvas
   primitives (dflow's `templates/compose` is exactly this).
-- [ ] **Catalog growth** — convert `templates/*.md` (20 app guides) into
+- [x] **Catalog growth** — seeded graph stacks for n8n, Gitea,
-  real graph templates; screenshots + badges per the old spec.
+  Nextcloud, Vaultwarden, Umami, Immich (Plausible already shipped).
+  `TestSeedTemplatesResolveCleanly` keeps every seed parseable,
+  topo-sortable, and fully resolved. Remaining single-service guides can
+  convert incrementally via the same endpoint.
 
 **Gate**: paste n8n compose → 3-service project with generated secrets
 and wired refs, one click or one CLI call.
 
 ## 7. Phase F — Nodes & infrastructure
 
-- [ ] **SSH bootstrap install** — `containr nodes add --ssh user@host` +
+- [x] **SSH bootstrap install** — `containr nodes add <user@host>` mints an
-  UI flow: one SSH session runs agent install (binary + systemd +
+  enroll token, SSHes once (agent/key/default keys), runs
-  enroll token), SSH closed forever. dflow onboarding UX, agent-model
+  `GET /api/agents/install.sh | bash` remotely, closes the session.
-  security.
+  `--print` emits the one-liner for manual runs; the Usage page shows the
-- [ ] **Mesh awareness** — agent detects + reports tailscale0/netbird0/
+  same command. Agent binaries ship in the image under `/agents` and are
-  zt0 IPs at register; backend stores + displays. Optional
+  served at `/api/agents/download/{linux-amd64,linux-arm64}` (install
-  `TAILSCALE_AUTH_KEY` enroll-at-provision later.
+  script falls back to GH releases). `cli/commands/nodes_add.go`,
-- [ ] **Node detail page** — placed services, telemetry history, agent
+  `api/assets/install-agent.sh`, `agents.go:ServeInstallScript`/`ServeAgentBinary`.
-  version + self-upgrade, **drain/cordon**, remove.
+- [x] **Mesh awareness** — agent reports tailscale/netbird/wireguard/
-- [ ] **Node housekeeping** — agent `prune` command (docker system
+  zerotier interface IPs at register (`mesh` field, authoritative on
-  prune, bounded) + optional schedule (`setServerAutoCleanup` analog —
+  re-register), stored in `node_agents.metadata.mesh`, shown on the node
-  disk pressure is the #1 small-VPS killer).
+  detail page. `TAILSCALE_AUTH_KEY` enroll-at-provision still open.
-- [ ] **Multi-node scheduling** — wire `scheduling_rules` (table exists):
+- [x] **Node detail page** — `/nodes/:id` (admin): heartbeat telemetry
-  pin/spread/affinity, prefer-lowest-usage; deploy engine routes to
+  (cpu/mem sparklines over 1h/24h/7d via `GET /agents/:id/metrics`),
-  `services.node_id` via agent commands (agent already runs containers).
+  containers, command history, rename, auto-prune toggle, prune-now,
-- [ ] **Build-on-node** — agents currently `docker run` prebuilt images
+  remove. Drain/cordon and self-upgrade deferred — they need
-  only; extend agent to pull registry images (build stays central) —
+  `services.node_id` routing which lands with multi-node scheduling.
-  private registry creds flow through Phase C.
+- [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. Spread placement shipped:
+  `services.spread` distributes replicas deterministically across every
+  online schedulable agent (replica i → agents[i mod n]), mutually
+  exclusive with a pin; `auto` is now resource-aware — least memory
+  utilisation, then cpu, then container count, with uninstrumented
+  agents sorting last. Lifecycle and `GET /runtime` are
+  inventory-driven, so remote replicas show up and tear down wherever
+  they run. Remote ingress shipped: the agent reports assigned host
+  ports in the `create_container` result, the backend renders a
+  Traefik file-provider config per remote service into
+  `TRAEFIK_DYNAMIC_DIR` (shared volume, `watch=true`) pointing the
+  loadbalancer at each replica's mesh IP + published port; route files
+  are rewritten on every remote reconcile and removed on teardown or
+  local placement. Agents report managed-container states at every
+  heartbeat — exits, OOMs, and crash loops land in inventory between
+  reconciles (tombstones never resurrect). Remote sleep/wake shipped:
+  heartbeats carry per-container net counters, idle remote services
+  lose replicas via agent remove + tombstones, and the route file
+  repoints at `/internal/wake-page/:id` on the backend — first hit
+  retriggers the wake reconcile, which recreates replicas and restores
+  real upstreams. Remote nodes run
+  registry-pulled images only — git builds are the remaining
+  documented ceiling. Tag affinity shipped: `node_agents.tags`
+  (operator-set via `PUT /agents/:id` / `nodes update --tags`) +
+  `services.placement_tags` — `auto` and `spread` only consider
+  online schedulable agents carrying every required tag, tags are
+  re-evaluated each reconcile (a tag change re-spreads replicas),
+  unsatisfiable requirements fail with a clear error, pin + tags
+  and local + tags are rejected, empty array clears. Surfaces:
+  `--placement-tags` on services create/update, `--tags` on
+  `nodes update`, MCP args, OpenAPI, node-detail tag editor +
+  service-detail placement-tags input. Remaining: build-on-node,
+  remote sleep/wake, spread weighting by real capacity.
+- [x] **Agent self-upgrade** — `POST /agents/:id/upgrade` enqueues a
+  `self_upgrade` command carrying platform + sha256 + server version;
+  the agent downloads its replacement from `GET /agents/download/
+  :platform`, verifies the checksum, sanity-checks `--version`,
+  atomically swaps its own executable, reports the result, then
+  re-execs (`syscall.Exec`) — no supervisor needed. Agents now stamp
+  `main.version` via ldflags at image build and report it at
+  register/heartbeat (`node_agents.version` refreshes on re-register;
+  older agents keep their stored value). Surfaces: `nodes upgrade`
+  CLI, `containr_nodes_upgrade` MCP (confirm-gated), node-detail page
+  button (online-gated). Ceilings: linux amd64/arm64 only; agents on
+  other platforms get a `NO_BINARY` 409.
+- [🟡] **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.
@@ -307,9 +386,12 @@ and wired refs, one click or one CLI call.
   UI at `/operations` (Operate nav) with live refetch; `containr
   operations` CLI + `containr_operations_get` MCP. Remaining: agent
   commands once node fleet lands; flush/stuck-job tools.
-- [ ] **Interactive terminal** — upgrade exec to WS PTY (`xterm.js`);
+- [x] **Interactive terminal** — `GET /services/:id/terminal` upgrades
-  `nodes/:id/terminal` via agent (dflow's wetty without the extra
+  to a WebSocket bridged to a `docker exec` PTY (bash→sh fallback,
-  container).
+  `TERM=xterm-256color`, resize frames). xterm.js Console section on the
+  service page; `containr shell <id>` bridges a local TTY; distroless
+  images get a clean "no shell" error. Remaining: `nodes/:id/terminal`
+  via agent.
 - [x] **Team invites** — `POST /admin/invites` returns a one-time
   link (sha256-hashed token at rest, optional email binding, TTL);
   public `GET /auth/invites/:token` validates and
@@ -329,11 +411,21 @@ and wired refs, one click or one CLI call.
   events (HMAC-verified) and enqueues matching services. Settings→env
   fallback wired into install-URL + installation-token paths.
   `containr admin github-app` CLI + MCP + OpenAPI.
-- [ ] **fork-sync trigger** — accept repo-sync events on webhook
+- [x] **fork-sync trigger** — webhook receiver accepts `sync`,
-  receiver.
+  `repository_dispatch`, and `workflow_run` events (no `ref`) alongside
-- [ ] **Dynamic filter framework** — port dflow's `filter.utils`
+  pushes: branch falls back to the webhook filter, then the service's
-  pattern (typed filter configs → URL state → client filtering) for
+  own `git_branch`; repo-only matching when no branch is known.
-  audit logs, deployments, notifications tables.
+  Also fixed a latent bug where the webhook's deployment insert omitted
+  the NOT NULL `version` column — push-triggered deploys silently
+  failed for every service.
+- [x] **Dynamic filter framework** — ported dflow's `filter.utils`
+  pattern as `lib/dynamic-filter.ts` + `use-dynamic-filter.ts`
+  (`FilterConfig` schema → `FilterEngine` → `FilterBar`; state lives in
+  `?f.<key>` search params so filtered views are shareable links).
+  `useFilterState` exposes URL state pre-fetch for server-backed
+  filters. Applied: audit logs (server-backed), builds (server + client
+  date-range), activity (severity server + client category/search).
+  Notifications table has no list surface yet — apply when one lands.
 - [ ] **Notification producers round-out** — backups, agent offline,
   upgrade available, security findings.
 - [x] **Sleep-on-idle / wake-on-traffic** (serverless-lite) —
@@ -367,19 +459,27 @@ and wired refs, one click or one CLI call.
 
 ## 9. Phase H — Migration & ecosystem
 
-- [ ] **Railway migrator** — `containr migrate railway --token --project
+- [x] **Railway migrator** — `containr migrate railway --token --project
-  --dry-run`: Railway GraphQL → services/vars/domains → recreate via
+  --environment --into --dry-run`: Railway GraphQL (backboard) →
-  PAT. Landing-page pitch: "off Railway in one command."
+  services (git-repo/image + command + replicas), variables, custom +
-- [ ] **dflow importer** — `containr migrate dflow` via Payload REST
+  service domains → recreates via the Containr API. Project tokens and
-  export or Mongo dump: servers→nodes, projects, services(+vars/
+  account tokens both supported. `cli/commands/migrate.go`.
-  domains/volumes), databases, templates. Onboards dflow refugees.
+- [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
   graph-provisioned managed databases (`database_services.project_id`).
-- [ ] **Template registry** — optional `CONTAINR_TEMPLATE_REGISTRY_URL`
+- [x] **Template registry** — `CONTAINR_TEMPLATE_REGISTRY_URL` merges a
-  fetch/publish; bundled catalog works offline (dflow's self-contained
+  remote Containr catalog into `GET /templates` as `source:"registry"`
-  principle — nothing phones home).
+  (60s cache, dead registry never blocks local). `GET /templates/:id`
+  falls through to the registry; deploy materializes a deterministic
+  `reg-<hash>` private copy for the deployer so re-deploys don't dup.
+  `api/templateregistry.go`, `.env.example`.
 
 ## 9b. Phase I — Companion surfaces
 

app/backend/Dockerfile

@@ -1,5 +1,7 @@
 # Build Go API binary
-FROM golang:1.26-alpine AS go-builder
+ARG GO_IMAGE=golang:1.26-alpine
+ARG NODE_IMAGE=node:22-alpine
+FROM ${GO_IMAGE} AS go-builder
 
 RUN apk add --no-cache git ca-certificates tzdata
 
@@ -9,10 +11,16 @@ COPY go.mod go.sum ./
 RUN go mod download
 
 COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main cmd/server/main.go
+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 -ldflags "-X main.version=${VERSION}" -o /agents/containr-agent-linux-amd64 ./cmd/agent && \
+    CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags "-X main.version=${VERSION}" -o /agents/containr-agent-linux-arm64 ./cmd/agent
 
 # Build embedded Better Auth runtime dependencies
-FROM node:22-alpine AS auth-builder
+FROM ${NODE_IMAGE} AS auth-builder
 
 WORKDIR /auth
 
@@ -22,9 +30,9 @@ RUN npm ci --omit=dev
 COPY auth/src ./src
 
 # Final runtime image (Go API + Better Auth sidecar in one container)
-FROM node:22-alpine
+FROM ${NODE_IMAGE}
 
-RUN apk --no-cache add ca-certificates tzdata wget
+RUN apk --no-cache add ca-certificates tzdata wget git
 
 RUN addgroup -g 1001 -S appgroup && \
     adduser -u 1001 -S appuser -G appgroup
@@ -33,6 +41,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

@@ -3,14 +3,18 @@ package main
 import (
 	"bytes"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
 	"log"
 	"net"
 	"net/http"
 	"os"
 	"os/exec"
+	"path/filepath"
 	"runtime"
 	"strconv"
 	"strings"
@@ -104,7 +108,15 @@ type registerResponse struct {
 	Status  string `json:"status"`
 }
 
+// version is stamped at build time via -ldflags "-X main.version=…".
+// The server reports it on upgrades so agents can show what they run.
+var version = "dev"
+
 func main() {
+	if len(os.Args) > 1 && (os.Args[1] == "--version" || os.Args[1] == "version") {
+		fmt.Printf("containr-agent %s\n", version)
+		return
+	}
 	cfg, err := loadConfig()
 	if err != nil {
 		log.Fatal(err)
@@ -167,6 +179,9 @@ func register(ctx context.Context, client *http.Client, cfg agentConfig) (string
 		"ip_address":   cfg.IP,
 		"port":         cfg.Port,
 		"capabilities": detectCapabilities(),
+		"version":      firstEnv("CONTAINR_AGENT_VERSION", version),
+		// 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 {
@@ -188,11 +203,93 @@ func sendHeartbeat(ctx context.Context, client *http.Client, cfg agentConfig, ag
 		"container_count": dockerContainerCount(),
 		"system_load":     readSystemLoad(),
 		"uptime":          readSystemUptime(),
-		"version":         firstEnv("CONTAINR_AGENT_VERSION", "dev"),
+		"version":         firstEnv("CONTAINR_AGENT_VERSION", version),
+		"containers":      managedContainerStates(),
 	}
 	return postJSON(ctx, client, cfg, "/api/agents/heartbeat", payload, nil)
 }
 
+// managedContainerStates lists every containr-managed container's docker
+// state plus cumulative network counters — state keeps runtime honest,
+// net bytes let the sleeper detect idle remote services.
+func managedContainerStates() []map[string]interface{} {
+	out, err := runDocker("ps", "-a",
+		"--filter", "label=containr.managed=true",
+		"--format", "{{.Names}}\t{{.State}}")
+	if err != nil {
+		return nil
+	}
+	netIO := containerNetIO()
+	var states []map[string]interface{}
+	for _, line := range strings.Split(out, "\n") {
+		parts := strings.SplitN(line, "\t", 2)
+		if len(parts) != 2 || parts[0] == "" {
+			continue
+		}
+		entry := map[string]interface{}{"name": parts[0], "state": parts[1]}
+		if io, ok := netIO[parts[0]]; ok {
+			entry["rx_bytes"], entry["tx_bytes"] = io[0], io[1]
+		}
+		states = append(states, entry)
+	}
+	return states
+}
+
+// containerNetIO snapshots cumulative rx/tx per running container. Stats
+// only covers running containers — stopped replicas report state without
+// counters, which is all the sleeper needs.
+func containerNetIO() map[string][2]int64 {
+	out, err := runDocker("stats", "--no-stream",
+		"--format", "{{.Name}}\t{{.NetIO}}")
+	if err != nil {
+		return nil
+	}
+	result := map[string][2]int64{}
+	for _, line := range strings.Split(out, "\n") {
+		parts := strings.SplitN(line, "\t", 2)
+		if len(parts) != 2 {
+			continue
+		}
+		io := strings.Split(parts[1], "/")
+		if len(io) != 2 {
+			continue
+		}
+		result[parts[0]] = [2]int64{parseHumanBytes(io[0]), parseHumanBytes(io[1])}
+	}
+	return result
+}
+
+// parseHumanBytes converts docker's human units ("1.2kB", "3.4MB") to bytes.
+func parseHumanBytes(s string) int64 {
+	s = strings.TrimSpace(s)
+	var num float64
+	var unit string
+	if _, err := fmt.Sscanf(s, "%f%s", &num, &unit); err != nil {
+		return 0
+	}
+	switch strings.ToUpper(unit) {
+	case "B":
+		return int64(num)
+	case "KB":
+		return int64(num * 1e3)
+	case "MB":
+		return int64(num * 1e6)
+	case "GB":
+		return int64(num * 1e9)
+	case "TB":
+		return int64(num * 1e12)
+	case "KIB":
+		return int64(num * 1024)
+	case "MIB":
+		return int64(num * 1024 * 1024)
+	case "GIB":
+		return int64(num * 1024 * 1024 * 1024)
+	case "TIB":
+		return int64(num * 1024 * 1024 * 1024 * 1024)
+	}
+	return int64(num)
+}
+
 func processCommands(ctx context.Context, client *http.Client, cfg agentConfig, agentID string) error {
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, fmt.Sprintf("%s/api/agents/%s/commands", cfg.APIURL, agentID), nil)
 	if err != nil {
@@ -214,7 +311,13 @@ func processCommands(ctx context.Context, client *http.Client, cfg agentConfig,
 		return err
 	}
 	for _, item := range list.Commands {
-		result, runErr := executeCommand(item)
+		var result, reexecPath string
+		var runErr error
+		if item.Type == "self_upgrade" {
+			result, reexecPath, runErr = selfUpgrade(cfg, item.Payload)
+		} else {
+			result, runErr = executeCommand(cfg, item)
+		}
 		status := "completed"
 		errText := ""
 		if runErr != nil {
@@ -230,11 +333,17 @@ func processCommands(ctx context.Context, client *http.Client, cfg agentConfig,
 		if err := postJSON(ctx, client, cfg, path, payload, nil); err != nil {
 			log.Printf("report command result failed: command=%s err=%v", item.ID, err)
 		}
+		// Re-exec AFTER the result posts — the new binary picks up the loop.
+		if reexecPath != "" {
+			if err := syscall.Exec(reexecPath, os.Args, os.Environ()); err != nil {
+				log.Fatalf("re-exec after upgrade failed: %v", err)
+			}
+		}
 	}
 	return nil
 }
 
-func executeCommand(item command) (string, error) {
+func executeCommand(cfg agentConfig, item command) (string, error) {
 	switch item.Type {
 	case "create_container":
 		return createContainer(item.Payload)
@@ -245,12 +354,100 @@ func executeCommand(item command) (string, error) {
 	case "restart_container":
 		return runDocker("restart", commandTarget(item.Payload))
 	case "remove_container":
-		return runDocker("rm", "-f", commandTarget(item.Payload))
+		out, err := runDocker("rm", "-f", commandTarget(item.Payload))
+		// A missing container is the desired end state — report success.
+		if err != nil && strings.Contains(out, "No such container") {
+			return out, nil
+		}
+		return out, err
+	case "build_image":
+		return buildImage(cfg, item.Payload)
+	case "load_image":
+		return loadImage(cfg, 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)
 	}
 }
 
+// selfUpgrade downloads the agent binary the server bundles for this
+// platform, verifies it, swaps it in atomically, and returns the path to
+// re-exec. On any failure the running binary is left untouched.
+func selfUpgrade(cfg agentConfig, payload map[string]interface{}) (string, string, error) {
+	platform := firstString(stringValue(payload["platform"]), runtime.GOOS+"-"+runtime.GOARCH)
+
+	exe, err := os.Executable()
+	if err != nil {
+		return "", "", fmt.Errorf("resolve own path: %w", err)
+	}
+	if resolved, err := filepath.EvalSymlinks(exe); err == nil {
+		exe = resolved
+	}
+
+	url := fmt.Sprintf("%s/api/agents/download/%s", cfg.APIURL, platform)
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return "", "", err
+	}
+	resp, err := (&http.Client{Timeout: 2 * time.Minute}).Do(req)
+	if err != nil {
+		return "", "", fmt.Errorf("download %s: %w", platform, err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", "", fmt.Errorf("download %s: server returned %d", platform, resp.StatusCode)
+	}
+
+	newPath := exe + ".new"
+	out, err := os.OpenFile(newPath, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o755)
+	if err != nil {
+		return "", "", fmt.Errorf("write %s: %w", newPath, err)
+	}
+	h := sha256.New()
+	if _, err := io.Copy(io.MultiWriter(out, h), resp.Body); err != nil {
+		out.Close()
+		os.Remove(newPath)
+		return "", "", fmt.Errorf("download write: %w", err)
+	}
+	out.Close()
+
+	if want := stringValue(payload["sha256"]); want != "" {
+		if got := hex.EncodeToString(h.Sum(nil)); got != want {
+			os.Remove(newPath)
+			return "", "", fmt.Errorf("sha256 mismatch: got %s want %s", got, want)
+		}
+	}
+
+	// Sanity: the new binary must at least report its version.
+	if verOut, err := exec.Command(newPath, "--version").CombinedOutput(); err != nil {
+		os.Remove(newPath)
+		return "", "", fmt.Errorf("new binary failed sanity check: %s", strings.TrimSpace(string(verOut)))
+	}
+
+	if err := os.Rename(newPath, exe); err != nil {
+		os.Remove(newPath)
+		return "", "", fmt.Errorf("swap binary: %w", err)
+	}
+	return fmt.Sprintf("upgraded to %s (%s)", firstString(stringValue(payload["version"]), "latest"), platform), exe, nil
+}
+
+// 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 +460,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 +506,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 +535,165 @@ 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)
+	}
+	// Report the real host port bindings — ephemeral publishes pick a port
+	// the server can't guess, and remote ingress needs the actual mapping.
+	hostPorts := map[string]string{}
+	portsJSON, _ := runDocker("inspect", "-f", "{{json .NetworkSettings.Ports}}", name)
+	var bindings map[string][]struct {
+		HostIP   string `json:"HostIp"`
+		HostPort string `json:"HostPort"`
+	}
+	if json.Unmarshal([]byte(portsJSON), &bindings) == nil {
+		for cport, addrs := range bindings {
+			for _, a := range addrs {
+				if a.HostPort != "" && a.HostPort != "0" {
+					hostPorts[cport] = a.HostPort
+				}
+			}
+		}
+	}
+	out, _ := json.Marshal(map[string]interface{}{"name": name, "host_ports": hostPorts})
+	return string(out), nil
+}
+
+// fetchArtifact downloads a server-side deploy artifact (build context or
+// docker-save tarball) into a temp file the docker CLI consumes.
+func fetchArtifact(cfg agentConfig, artifactID string) (*os.File, error) {
+	if len(artifactID) != 32 {
+		return nil, fmt.Errorf("invalid artifact id")
+	}
+	url := fmt.Sprintf("%s/api/agents/artifacts/%s", cfg.APIURL, artifactID)
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("X-Containr-Agent-Token", cfg.Token)
+	resp, err := (&http.Client{Timeout: 10 * time.Minute}).Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download artifact: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("download artifact: server returned %d", resp.StatusCode)
+	}
+	f, err := os.CreateTemp("", "containr-artifact-*.tar")
+	if err != nil {
+		return nil, err
+	}
+	if _, err := io.Copy(f, resp.Body); err != nil {
+		f.Close()
+		os.Remove(f.Name())
+		return nil, fmt.Errorf("write artifact: %w", err)
+	}
+	if _, err := f.Seek(0, io.SeekStart); err != nil {
+		f.Close()
+		os.Remove(f.Name())
+		return nil, err
+	}
+	return f, nil
+}
+
+// buildImage docker-builds a packaged context tar on this node. The context
+// already carries its Dockerfile at the tar root, so `docker build -` can
+// stream it straight from stdin. Result reports the image digest so the
+// server records what each node actually produced.
+func buildImage(cfg agentConfig, payload map[string]interface{}) (string, error) {
+	image := stringValue(payload["image"])
+	artifactID := stringValue(payload["artifact_id"])
+	if image == "" || artifactID == "" {
+		return "", errors.New("build_image requires image and artifact_id")
+	}
+	f, err := fetchArtifact(cfg, artifactID)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	defer os.Remove(f.Name())
+
+	args := []string{"build", "-t", image}
+	if boolValue(payload["no_cache"]) {
+		args = append(args, "--no-cache")
+	}
+	// Bare --build-arg keys read their values from the process env — keeps
+	// token-bearing args out of the node's process list.
+	env := os.Environ()
+	if buildArgs, ok := payload["build_args"].(map[string]interface{}); ok {
+		for k, v := range buildArgs {
+			args = append(args, "--build-arg", k)
+			env = append(env, fmt.Sprintf("%s=%v", k, v))
+		}
+	}
+	args = append(args, "-")
+	cmd := exec.Command("docker", args...)
+	cmd.Stdin = f
+	cmd.Env = env
+	outBytes, err := cmd.CombinedOutput()
+	out := strings.TrimSpace(string(outBytes))
+	if err != nil {
+		return "", fmt.Errorf("docker build failed: %s", tailOutput(out, 4096))
+	}
+	digest, _ := runDocker("inspect", "-f", "{{.Id}}", image)
+	size, _ := runDocker("inspect", "-f", "{{.Size}}", image)
+	result, _ := json.Marshal(map[string]string{
+		"image": image, "id": digest, "size": size,
+		"log_tail": tailOutput(out, 4096),
+	})
+	return string(result), nil
+}
+
+// loadImage imports a docker-save tarball — rollbacks of locally-built tags
+// reach remote nodes this way since no registry serves containr-* images.
+func loadImage(cfg agentConfig, payload map[string]interface{}) (string, error) {
+	artifactID := stringValue(payload["artifact_id"])
+	if artifactID == "" {
+		return "", errors.New("load_image requires artifact_id")
+	}
+	f, err := fetchArtifact(cfg, artifactID)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	defer os.Remove(f.Name())
+	out, err := runDockerStdin(f, "load")
+	if err != nil {
+		return "", fmt.Errorf("docker load failed: %s", tailOutput(out, 4096))
+	}
+	return out, nil
+}
+
+// tailOutput bounds command results — full docker build logs would swamp
+// the agent_commands row.
+func tailOutput(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[len(s)-max:]
+}
+
+// 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 +746,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("/")
@@ -469,6 +897,15 @@ func runDocker(args ...string) (string, error) {
 	return strings.TrimSpace(string(output)), err
 }
 
+// runDockerStdin pipes stdin into docker — build contexts and saved image
+// tarballs stream in without a second copy on disk.
+func runDockerStdin(stdin io.Reader, args ...string) (string, error) {
+	cmd := exec.Command("docker", args...)
+	cmd.Stdin = stdin
+	output, err := cmd.CombinedOutput()
+	return strings.TrimSpace(string(output)), err
+}
+
 func dockerAvailable() bool {
 	_, err := exec.LookPath("docker")
 	if err != nil {
@@ -564,3 +1001,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,17 @@ import (
 	"crypto/sha256"
 	"crypto/subtle"
 	"database/sql"
+	_ "embed"
 	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
+	"io"
+	"log"
 	"math"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -36,6 +40,11 @@ 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"`
+	// Tags are operator-set placement labels; services with placement_tags
+	// only schedule onto agents carrying every required tag.
+	Tags          []string               `json:"tags"`
 	CreatedAt     time.Time              `json:"created_at"`
 	UpdatedAt     time.Time              `json:"updated_at"`
 	Metadata      map[string]interface{} `json:"metadata"`
@@ -189,6 +198,17 @@ type AgentHeartbeat struct {
 	SystemLoad     SystemLoad    `json:"system_load"`
 	Uptime         int64         `json:"uptime"`
 	Version        string        `json:"version"`
+	// Containers reports managed-container liveness — {name, state} per
+	// containr.managed container on the node — so remote replica status
+	// reflects reality between reconciles (exits, OOMs, crash loops).
+	Containers []AgentContainerState `json:"containers,omitempty"`
+}
+
+type AgentContainerState struct {
+	Name    string `json:"name"`
+	State   string `json:"state"`
+	RxBytes int64  `json:"rx_bytes,omitempty"`
+	TxBytes int64  `json:"tx_bytes,omitempty"`
 }
 
 type SystemLoad struct {
@@ -225,16 +245,44 @@ 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 {
+		var tags []string
+		if len(row.Tags) > 0 {
+			_ = json.Unmarshal(row.Tags, &tags)
+		}
+		options = append(options, gin.H{
+			"id":     row.ID,
+			"name":   row.Name,
+			"status": row.Status.String,
+			"tags":   tags,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"nodes": options})
+}
+
 func agentFromRow(row sqlcdb.NodeAgent) NodeAgent {
 	agent := NodeAgent{
-		ID:        row.ID,
+		ID:          row.ID,
-		Name:      row.Name,
+		Name:        row.Name,
-		Hostname:  row.Hostname,
+		Hostname:    row.Hostname,
-		IPAddress: row.IpAddress,
+		IPAddress:   row.IpAddress,
-		Port:      int(row.Port),
+		Port:        int(row.Port),
-		Status:    row.Status.String,
+		Status:      row.Status.String,
-		Version:   row.Version.String,
+		Version:     row.Version.String,
-		Metadata:  map[string]interface{}{},
+		AutoPrune:   row.AutoPrune,
+		Schedulable: row.Schedulable,
+		Tags:        []string{},
+		Metadata:    map[string]interface{}{},
 	}
 	if row.LastHeartbeat.Valid {
 		agent.LastHeartbeat = row.LastHeartbeat.Time
@@ -248,6 +296,9 @@ func agentFromRow(row sqlcdb.NodeAgent) NodeAgent {
 	unmarshalRaw(row.Capabilities, &agent.Capabilities)
 	unmarshalRaw(row.Resources, &agent.Resources)
 	unmarshalRaw(row.Metadata, &agent.Metadata)
+	if len(row.Tags) > 0 {
+		_ = json.Unmarshal(row.Tags, &agent.Tags)
+	}
 	return agent
 }
 
@@ -326,7 +377,9 @@ func (h *NodeAgentHandler) RegisterAgent(c *gin.Context) {
 		IPAddress    string            `json:"ip_address" binding:"required"`
 		Port         int               `json:"port" binding:"required"`
 		Capabilities AgentCapabilities `json:"capabilities" binding:"required"`
+		Version      string            `json:"version"`
 		AuthToken    string            `json:"auth_token"`
+		Mesh         map[string]string `json:"mesh"`
 	}
 
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -341,24 +394,43 @@ 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,
+			ID:        existing.ID,
-			Name:          req.Name,
+			Name:      req.Name,
-			Hostname:      existing.Hostname,
+			Hostname:  existing.Hostname,
-			IpAddress:     existing.IpAddress,
+			IpAddress: existing.IpAddress,
-			Port:          int32(req.Port),
+			Port:      int32(req.Port),
-			Status:        sql.NullString{String: "connecting", Valid: true},
+			Status:    sql.NullString{String: "connecting", Valid: true},
-			Version:       existing.Version,
+			// Older agents don't report a version — keep whatever's stored.
+			Version:       sql.NullString{String: firstNonEmpty(req.Version, existing.Version.String), Valid: true},
 			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"})
@@ -404,11 +476,11 @@ func (h *NodeAgentHandler) RegisterAgent(c *gin.Context) {
 		IpAddress:     req.IPAddress,
 		Port:          int32(req.Port),
 		Status:        sql.NullString{String: "connecting", Valid: true},
-		Version:       sql.NullString{},
+		Version:       sql.NullString{String: req.Version, Valid: req.Version != ""},
 		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,13 +561,34 @@ 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"})
 		return
 	}
 
-	c.JSON(http.StatusOK, gin.H{"agent": agentFromRow(updated)})
+	// Tags persist through their own column write — UpdateAgent keeps the
+	// register-path signature untouched.
+	resp := agentFromRow(updated)
+	if raw, ok := updates["tags"]; ok {
+		var tags []string
+		if b, mErr := json.Marshal(raw); mErr == nil {
+			_ = json.Unmarshal(b, &tags)
+		}
+		tags = normalizePlacementTags(tags)
+		if err := h.q.SetAgentTags(ctx, sqlcdb.SetAgentTagsParams{
+			ID:      id,
+			Column2: json.RawMessage(tagsJSON(tags)),
+		}); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to update agent tags"})
+			return
+		}
+		resp.Tags = tags
+	}
+
+	c.JSON(http.StatusOK, gin.H{"agent": resp})
 }
 
 // applyAgentUpdates merges whitelisted keys from an arbitrary update map.
@@ -516,6 +609,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
@@ -581,6 +676,22 @@ func (h *NodeAgentHandler) SendHeartbeat(c *gin.Context) {
 		return
 	}
 
+	// Reconcile remote container liveness — exits and crash loops surface
+	// in inventory between reconciles. Best-effort, never fatal.
+	for _, rc := range heartbeat.Containers {
+		if rc.Name == "" || rc.State == "" {
+			continue
+		}
+		stateJSON, _ := json.Marshal(rc.State)
+		bytesJSON, _ := json.Marshal(rc.RxBytes + rc.TxBytes)
+		_ = h.q.UpdateContainerStateByName(ctx, sqlcdb.UpdateContainerStateByNameParams{
+			Name:        rc.Name,
+			NodeAgentID: heartbeat.NodeAgentID,
+			Column3:     stateJSON,
+			Column4:     bytesJSON,
+		})
+	}
+
 	c.Status(http.StatusOK)
 }
 
@@ -650,9 +761,51 @@ 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
+// credential-bearing fields blanked — registry passwords and build-time
+// args (tokens like NPM_TOKEN ride along as build args). 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
+	}
+	dirty := false
+	if container, ok := doc["container"].(map[string]interface{}); ok {
+		if reg, ok := container["registry"].(map[string]interface{}); ok && reg["password"] != nil {
+			reg["password"] = "***"
+			dirty = true
+		}
+	}
+	for _, key := range []string{"build_args", "environment"} {
+		if args, ok := doc[key].(map[string]interface{}); ok && len(args) > 0 {
+			for k := range args {
+				args[k] = "***"
+			}
+			dirty = true
+		}
+	}
+	if !dirty {
+		return
+	}
+	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 +956,103 @@ 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})
+}
+
+// UpgradeAgent enqueues a self_upgrade command: the agent downloads its
+// replacement binary from this server's bundled /download endpoint,
+// verifies the sha256, swaps it in, and re-execs. Fails fast when no
+// bundled binary exists for the agent's architecture.
+func (h *NodeAgentHandler) UpgradeAgent(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 offline — reconnect it before upgrading")
+		return
+	}
+
+	arch := "amd64"
+	var caps struct {
+		SupportedArchitectures []string `json:"supported_architectures"`
+	}
+	unmarshalRaw(agent.Capabilities, &caps)
+	if len(caps.SupportedArchitectures) > 0 && caps.SupportedArchitectures[0] != "" {
+		arch = caps.SupportedArchitectures[0]
+	}
+	platform := "linux-" + arch // agents only ship for linux today
+
+	dir := os.Getenv("CONTAINR_AGENT_BIN_DIR")
+	if dir == "" {
+		dir = "/agents"
+	}
+	path := filepath.Join(dir, "containr-agent-"+platform)
+	sum, err := sha256File(path)
+	if err != nil {
+		respondError(c, http.StatusConflict, "NO_BINARY",
+			fmt.Sprintf("no bundled agent binary for %s on this server", platform))
+		return
+	}
+
+	command, err := h.q.CreateCommand(ctx, sqlcdb.CreateCommandParams{
+		ID:          uuid.New().String(),
+		Type:        "self_upgrade",
+		NodeAgentID: id,
+		Payload: rawJSON(map[string]interface{}{
+			"platform": platform,
+			"sha256":   sum,
+			"version":  Version,
+		}),
+	})
+	if err != nil {
+		respondError(c, http.StatusInternalServerError, "INTERNAL", "failed to enqueue upgrade")
+		return
+	}
+	LogAuditWithRequest(c, "node", id, "upgrade", map[string]interface{}{"platform": platform, "version": Version})
+	c.JSON(http.StatusAccepted, gin.H{"command": command, "platform": platform, "version": Version})
+}
+
+func sha256File(path string) (string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	h := sha256.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
 // ExecuteCommand executes a command on an agent
 func (h *NodeAgentHandler) ExecuteCommand(c *gin.Context) {
 	agentID := c.Param("id")
@@ -1214,9 +1464,49 @@ 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)
+
+		// Deploy artifacts (build contexts, image tarballs) — token-gated;
+		// the blobs are per-deployment source code, not public bootstrap.
+		agents.GET("/artifacts/:id", h.ServeArtifact)
 	}
 }
 
+//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 +1533,95 @@ 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/upgrade", h.UpgradeAgent)
+		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/artifacts.go

@@ -0,0 +1,136 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// containrWorkDir is the build workspace root — same dir the BuildManager
+// was constructed with; checkouts and agent artifacts live beneath it.
+const containrWorkDir = "/tmp/containr-builds"
+
+// artifacts is a one-shot blob store for node agents: build contexts and
+// docker-save tarballs the server produced on behalf of a deployment. Files
+// live under workdir/artifacts/<id> and are removed when the deployment
+// finishes or after maxArtifactAge.
+var artifacts = &artifactStore{files: map[string]string{}}
+
+type artifactStore struct {
+	mu    sync.Mutex
+	dir   string
+	files map[string]string
+}
+
+const maxArtifactAge = 2 // hours — a deployment can never outlive this
+
+// initArtifacts points the store at dir (created on demand).
+func initArtifacts(dir string) {
+	artifacts.mu.Lock()
+	defer artifacts.mu.Unlock()
+	artifacts.dir = dir
+	_ = os.MkdirAll(dir, 0o755)
+}
+
+// artifactDir returns the store root, defaulting under the build workdir.
+func artifactDir() string {
+	artifacts.mu.Lock()
+	defer artifacts.mu.Unlock()
+	if artifacts.dir != "" {
+		return artifacts.dir
+	}
+	return filepath.Join(containrWorkDir, "artifacts")
+}
+
+// putArtifact streams rc into the store and returns the artifact id.
+func putArtifact(rc io.Reader) (string, error) {
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	id := hex.EncodeToString(buf)
+	dir := artifactDir()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", err
+	}
+	path := filepath.Join(dir, id+".tar")
+	f, err := os.Create(path)
+	if err != nil {
+		return "", err
+	}
+	if _, err := io.Copy(f, rc); err != nil {
+		f.Close()
+		os.Remove(path)
+		return "", err
+	}
+	f.Close()
+
+	artifacts.mu.Lock()
+	artifacts.files[id] = path
+	artifacts.mu.Unlock()
+	return id, nil
+}
+
+// removeArtifact deletes the file and forgets the id. Safe on missing ids.
+func removeArtifact(id string) {
+	artifacts.mu.Lock()
+	path, ok := artifacts.files[id]
+	delete(artifacts.files, id)
+	artifacts.mu.Unlock()
+	if ok {
+		_ = os.Remove(path)
+		return
+	}
+	// Registered before a restart — remove best-effort by name.
+	if id != "" {
+		_ = os.Remove(filepath.Join(artifactDir(), id+".tar"))
+	}
+}
+
+// ServeArtifact streams a stored blob to a token-authenticated agent. Files
+// persist across downloads — spread builds share one context — and are
+// deleted by the deployment that created them.
+func (h *NodeAgentHandler) ServeArtifact(c *gin.Context) {
+	if !h.isValidAgentAuthToken(c.Request.Context(), agentAuthTokenFromRequest(c)) {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid auth token"})
+		return
+	}
+	id := c.Param("id")
+	raw, err := hex.DecodeString(id)
+	if len(id) != 32 || err != nil || len(raw) != 16 {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Artifact not found"})
+		return
+	}
+	path := filepath.Join(artifactDir(), id+".tar")
+	info, err := os.Stat(path)
+	if err != nil || info.IsDir() {
+		c.JSON(http.StatusNotFound, gin.H{"error": "Artifact not found"})
+		return
+	}
+	c.Header("Content-Type", "application/x-tar")
+	c.File(path)
+}
+
+// purgeStaleArtifacts drops files older than maxArtifactAge. Called on boot.
+func purgeStaleArtifacts() {
+	entries, err := os.ReadDir(artifactDir())
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if info.ModTime().Before(time.Now().Add(-maxArtifactAge * time.Hour)) {
+			_ = os.Remove(filepath.Join(artifactDir(), e.Name()))
+		}
+	}
+}

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/databases.go

@@ -2,6 +2,7 @@ package api
 
 import (
 	"archive/tar"
+	"containr/internal/database"
 	"containr/internal/database/sqlcdb"
 	"containr/internal/deployment"
 	"containr/internal/docker"
@@ -1868,14 +1869,22 @@ func (h *DatabaseHandler) createBackupProcess(databaseID, backupID, backupPath s
 	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Minute)
 	defer cancel()
 
+	notify := func(title, body string) {
+		if row, err := h.queries.GetDatabaseServiceByID(context.Background(), databaseID); err == nil && row.UserID != "" {
+			insertUserNotification(&database.DB{DB: h.db}, row.UserID, "backup", title, body, "database", databaseID)
+		}
+	}
+
 	if h.dockerClient == nil {
 		_ = h.setDatabaseBackupStatus(backupID, "failed", "0 B", false)
+		notify("Database backup failed", "Backup could not start: docker unavailable.")
 		return
 	}
 
 	sizeLabel, err := h.snapshotDatabaseVolume(ctx, databaseID, backupPath)
 	if err != nil {
 		_ = h.setDatabaseBackupStatus(backupID, "failed", "0 B", false)
+		notify("Database backup failed", fmt.Sprintf("Snapshot failed: %v", err))
 		return
 	}
 	if dbRow, err := h.queries.GetDatabaseServiceByID(ctx, databaseID); err == nil {
@@ -1886,6 +1895,7 @@ func (h *DatabaseHandler) createBackupProcess(databaseID, backupID, backupPath s
 		}
 	}
 	_ = h.setDatabaseBackupStatus(backupID, "completed", sizeLabel, true)
+	notify("Database backup completed", fmt.Sprintf("Backup archived (%s).", sizeLabel))
 }
 
 func (h *DatabaseHandler) restoreBackupProcess(databaseID, backupID string, backupPath string) {

app/backend/internal/api/deployments.go

@@ -5,11 +5,15 @@ import (
 	"containr/internal/deployment"
 	"containr/internal/deployqueue"
 	"containr/internal/docker"
+	"containr/internal/source"
+	"containr/internal/types"
 	"context"
 	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -377,6 +381,23 @@ func runDeploymentAndSyncWithImage(
 	ctx, cancel := context.WithTimeout(parentCtx, 30*time.Minute)
 	defer cancel()
 
+	// The checkout and any shipped artifacts die with this deployment.
+	var artifactIDs []string
+	checkoutRoot := filepath.Join(containrWorkDir, "repos", dbDeployment.ID.String())
+	defer func() {
+		_ = os.RemoveAll(checkoutRoot)
+		for _, id := range artifactIDs {
+			removeArtifact(id)
+		}
+	}()
+	failDeploy := func(msg string) {
+		failedAt := time.Now()
+		_, _ = db.Exec(
+			`UPDATE deployments SET status = 'failed', error = $1, completed_at = $2, updated_at = $2 WHERE id = $3`,
+			msg, failedAt, dbDeployment.ID,
+		)
+	}
+
 	sourcePath := strings.TrimSpace(service.BuildPath)
 	if sourcePath == "" {
 		sourcePath = "."
@@ -421,6 +442,33 @@ func runDeploymentAndSyncWithImage(
 		maintURL = maintenanceURL(db)
 	}
 
+	// Node-pinned and spread services dispatch to agent command queues.
+	nodeID := serviceNodeID(db, service.ID)
+	spread := serviceSpread(db, service.ID)
+	remote := nodeID != "" || spread
+
+	// Materialize the git checkout — local builds consume it directly;
+	// remote builds package it into a context artifact the node builds.
+	if service.GitRepo != "" && imageOverride == "" {
+		var ownerID string
+		_ = db.QueryRow(`SELECT owner_id FROM projects WHERE id = $1`, service.ProjectID).Scan(&ownerID)
+		branch := req.Branch
+		if branch == "" {
+			branch = service.GitBranch
+		}
+		cloneSpec, err := resolveGitCloneSpec(db, ownerID, service.GitRepo, branch, req.CommitHash, service.BuildPath)
+		if err != nil {
+			failDeploy("resolve git source: " + err.Error())
+			return
+		}
+		src, err := source.Checkout(ctx, checkoutRoot, cloneSpec)
+		if err != nil {
+			failDeploy("git checkout: " + err.Error())
+			return
+		}
+		sourcePath = src
+	}
+
 	deployReq := &deployment.DeploymentRequest{
 		ProjectID:   service.ProjectID.String(),
 		ServiceID:   service.ID.String(),
@@ -447,6 +495,8 @@ func runDeploymentAndSyncWithImage(
 			Maintenance:    maintenanceMode,
 			MaintenanceURL: maintURL,
 			BasicAuthUsers: basicAuthUsers,
+			NodeID:         nodeID,
+			Spread:         spread,
 		},
 		Trigger: deployment.TriggerConfig{
 			Type:      req.Trigger,
@@ -463,14 +513,36 @@ func runDeploymentAndSyncWithImage(
 		if image == "" {
 			image = service.Image
 		}
-		var ownerID string
+		if remote && strings.HasPrefix(image, "containr-") {
-		_ = db.QueryRow(`SELECT owner_id FROM projects WHERE id = $1`, service.ProjectID).Scan(&ownerID)
+			// Locally-built tag — no registry serves it. Ship the image
-		auth := registryAuthFor(db, ownerID, image)
+			// itself as a docker-save artifact; the node loads it.
-		deployReq.BuildConfig = &deployment.BuildConfig{
+			rc, err := engine.DockerClient().SaveImage(ctx, image)
-			BuildType:     "prebuilt",
+			if err != nil {
-			PrebuiltImage: image,
+				failDeploy("export rollback image: " + err.Error())
-			PullUsername:  auth.Username,
+				return
-			PullPassword:  auth.Password,
+			}
+			artifactID, err := putArtifact(rc)
+			_ = rc.Close()
+			if err != nil {
+				failDeploy("store rollback image artifact: " + err.Error())
+				return
+			}
+			artifactIDs = append(artifactIDs, artifactID)
+			deployReq.Config.RemoteLoad = &deployment.RemoteLoadSpec{ArtifactID: artifactID}
+			deployReq.BuildConfig = &deployment.BuildConfig{
+				BuildType:     "remote",
+				PrebuiltImage: image,
+			}
+		} else {
+			var ownerID string
+			_ = db.QueryRow(`SELECT owner_id FROM projects WHERE id = $1`, service.ProjectID).Scan(&ownerID)
+			auth := registryAuthFor(db, ownerID, image)
+			deployReq.BuildConfig = &deployment.BuildConfig{
+				BuildType:     "prebuilt",
+				PrebuiltImage: image,
+				PullUsername:  auth.Username,
+				PullPassword:  auth.Password,
+			}
 		}
 	} else {
 		// "auto" leaves BuildType empty so the manager detects it; the static
@@ -480,16 +552,54 @@ func runDeploymentAndSyncWithImage(
 		if service.Builder != "" && service.Builder != "auto" {
 			buildType = service.Builder
 		}
-		deployReq.BuildConfig = &deployment.BuildConfig{
+		buildArgs := map[string]string{}
-			BuildType:  buildType,
+		buildCommand := ""
-			SourcePath: sourcePath,
-			Branch:     req.Branch,
-			Commit:     req.CommitHash,
-			NoCache:    req.NoCache,
-		}
 		if buildType == "static" {
-			deployReq.BuildConfig.BuildCommand = firstNonEmpty(service.StaticBuildCmd, "npm ci && npm run build")
+			buildCommand = firstNonEmpty(service.StaticBuildCmd, "npm ci && npm run build")
-			deployReq.BuildConfig.BuildArgs = map[string]string{"STATIC_DIR": firstNonEmpty(service.StaticDir, "dist")}
+			buildArgs["STATIC_DIR"] = firstNonEmpty(service.StaticDir, "dist")
+		}
+		if remote {
+			// Package the context — the node docker-builds it itself.
+			packReq := &types.BuildRequest{
+				BuildType:    buildType,
+				SourcePath:   sourcePath,
+				BuildCommand: buildCommand,
+				BuildArgs:    buildArgs,
+				Environment:  env,
+			}
+			rc, err := engine.BuildManager().PackageContext(ctx, packReq)
+			if err != nil {
+				failDeploy("package build context: " + err.Error())
+				return
+			}
+			artifactID, err := putArtifact(rc)
+			_ = rc.Close()
+			if err != nil {
+				failDeploy("store build context artifact: " + err.Error())
+				return
+			}
+			artifactIDs = append(artifactIDs, artifactID)
+			deployReq.Config.RemoteBuild = &deployment.RemoteBuildSpec{
+				ArtifactID: artifactID,
+				BuildArgs:  buildArgs,
+				NoCache:    req.NoCache,
+			}
+			deployReq.BuildConfig = &deployment.BuildConfig{
+				BuildType: "remote",
+				Branch:    req.Branch,
+				Commit:    req.CommitHash,
+				NoCache:   req.NoCache,
+			}
+		} else {
+			deployReq.BuildConfig = &deployment.BuildConfig{
+				BuildType:    buildType,
+				SourcePath:   sourcePath,
+				BuildCommand: buildCommand,
+				BuildArgs:    buildArgs,
+				Branch:       req.Branch,
+				Commit:       req.CommitHash,
+				NoCache:      req.NoCache,
+			}
 		}
 	}
 

app/backend/internal/api/git_receiver.go

@@ -7,6 +7,7 @@ import (
 	"crypto/subtle"
 	"encoding/hex"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
 	"strings"
@@ -90,11 +91,24 @@ func handleGitWebhookPush(c *gin.Context) {
 		return
 	}
 
-	if !strings.HasPrefix(payload.Ref, "refs/heads/") {
+	// Non-push events that still mean "the repo changed": fork-sync bots
+	// (sync), repository_dispatch, workflow_run completions. They carry no
+	// `ref`, so fall back to the webhook's branch filter (or the service's
+	// own git_branch via the repo match below).
+	event := c.Request.Header.Get("X-GitHub-Event")
+	if event == "" {
+		event = c.Request.Header.Get("X-Gitea-Event")
+	}
+	syncEvent := event == "sync" || event == "repository_dispatch" || event == "workflow_run"
+
+	if !strings.HasPrefix(payload.Ref, "refs/heads/") && !syncEvent {
 		c.JSON(http.StatusAccepted, gin.H{"received": true, "ignored": "not a branch push"})
 		return
 	}
 	branch := strings.TrimPrefix(payload.Ref, "refs/heads/")
+	if branch == "" {
+		branch = branchFilter
+	}
 	if branchFilter != "" && branchFilter != branch {
 		c.JSON(http.StatusAccepted, gin.H{"received": true, "ignored": "branch not watched"})
 		return
@@ -133,12 +147,17 @@ func handleGitWebhookPush(c *gin.Context) {
 // the pushed repo+branch. Shared by the per-repo webhook receiver and the
 // GitHub App webhook endpoint.
 func dispatchPushToServices(c *gin.Context, db *database.DB, engine *deployment.DeploymentEngine, cloneURL, fullName, branch, commit, repoUserID string) (int, error) {
-	rows, err := db.Query(`
+	// Sync-style events may carry no branch — match services on repo only.
+	branchClause := "s.git_branch = $1"
+	if branch == "" {
+		branchClause = "TRUE"
+	}
+	rows, err := db.Query(fmt.Sprintf(`
 		SELECT s.id, s.project_id, s.name, s.type, s.status, s.image, s.command,
 		       s.environment, s.git_repo, s.git_branch, s.build_path, s.cpu, s.memory,
 		       s.created_at, s.updated_at
 		FROM services s
-		WHERE s.git_branch = $1 AND (s.git_repo = $2 OR s.git_repo = $3)`,
+		WHERE %s AND (s.git_repo = $2 OR s.git_repo = $3)`, branchClause),
 		branch, cloneURL, fullName)
 	if err != nil {
 		return 0, err
@@ -175,9 +194,9 @@ func dispatchPushToServices(c *gin.Context, db *database.DB, engine *deployment.
 		}
 		if _, err := db.Exec(
 			`INSERT INTO deployments
-			 (id, service_id, commit_hash, status, image_name, image_tag, created_at, updated_at)
+			 (id, service_id, version, commit_hash, status, image_name, image_tag, created_at, updated_at)
-			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
-			d.ID, d.ServiceID, d.CommitHash, d.Status, d.ImageName, d.ImageTag, d.CreatedAt, d.UpdatedAt,
+			d.ID, d.ServiceID, fmt.Sprintf("v%d", now.Unix()), d.CommitHash, d.Status, d.ImageName, d.ImageTag, d.CreatedAt, d.UpdatedAt,
 		); err != nil {
 			continue
 		}
@@ -196,7 +215,11 @@ func dispatchPushToServices(c *gin.Context, db *database.DB, engine *deployment.
 		)
 		// Webhook pushes default to a clean build — stale layers are the
 		// classic silent-rollback failure (dflow convention).
-		webhookReq := CreateDeploymentRequest{CommitHash: commit, Branch: branch, Trigger: "webhook", NoCache: true}
+		branchForBuild := branch
+		if branchForBuild == "" {
+			branchForBuild = service.GitBranch
+		}
+		webhookReq := CreateDeploymentRequest{CommitHash: commit, Branch: branchForBuild, Trigger: "webhook", NoCache: true}
 		if pos := getDeployQueue(c).Enqueue(service.ID, deployqueue.Job{
 			DeploymentID: d.ID,
 			Run: func(jctx context.Context) {

app/backend/internal/api/gitcreds.go

@@ -0,0 +1,84 @@
+package api
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"containr/internal/database"
+	"containr/internal/source"
+)
+
+// resolveGitCloneSpec turns a service's git_repo (clone URL, ssh remote, or
+// owner/repo) into a source.Spec with the project owner's provider token.
+// Public repos get no token — the clone proceeds anonymously. github_app
+// providers store the installation id, not a usable token; a fresh
+// installation token is minted per deploy.
+func resolveGitCloneSpec(db *database.DB, ownerID, gitRepo, branch, commit, buildPath string) (source.Spec, error) {
+	raw := strings.TrimSpace(gitRepo)
+	cloneURL, err := source.NormalizeCloneURL(raw)
+	if err != nil {
+		return source.Spec{}, err
+	}
+
+	spec := source.Spec{Branch: branch, Commit: commit, BuildPath: buildPath}
+
+	var providerID string
+	if !strings.Contains(cloneURL, "://") {
+		// Bare owner/repo — the connected repository row knows the host.
+		err = db.QueryRow(
+			`SELECT clone_url, provider_id FROM git_repositories
+			 WHERE full_name = $1 AND user_id = $2 LIMIT 1`,
+			cloneURL, ownerID,
+		).Scan(&cloneURL, &providerID)
+		if err != nil {
+			return source.Spec{}, fmt.Errorf("repository %s is not connected — connect it under Git settings or store a clone URL", raw)
+		}
+	} else {
+		// URL form — match a connected repo for its provider when possible;
+		// an unmatched public URL still clones, just without credentials.
+		_ = db.QueryRow(
+			`SELECT provider_id FROM git_repositories
+			 WHERE clone_url = $1 AND user_id = $2 LIMIT 1`,
+			cloneURL, ownerID,
+		).Scan(&providerID)
+	}
+
+	if err := source.ValidateRemoteURL(cloneURL); err != nil {
+		return source.Spec{}, err
+	}
+	spec.CloneURL = cloneURL
+
+	if providerID == "" {
+		return spec, nil
+	}
+	var name, apiURL, token string
+	if err := db.QueryRow(
+		`SELECT name, api_url, access_token FROM git_providers
+		 WHERE id = $1 AND user_id = $2`,
+		providerID, ownerID,
+	).Scan(&name, &apiURL, &token); err != nil {
+		return spec, nil // provider row gone — anonymous clone still works for public repos
+	}
+
+	switch strings.ToLower(name) {
+	case "github_app":
+		installationID, err := strconv.ParseInt(strings.TrimSpace(token), 10, 64)
+		if err == nil && installationID > 0 {
+			if minted, err := getGitHubAppInstallationToken(apiURL, installationID); err == nil {
+				spec.Token = minted
+				spec.User = "x-access-token"
+			}
+		}
+	case "gitlab":
+		spec.Token = token
+		spec.User = "oauth2"
+	case "bitbucket":
+		spec.Token = token
+		spec.User = "x-token-auth"
+	default:
+		spec.Token = token
+		spec.User = "x-access-token"
+	}
+	return spec, nil
+}

app/backend/internal/api/ingress.go

@@ -0,0 +1,212 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
+	"containr/internal/deployment"
+)
+
+// Remote ingress: replicas on node agents aren't on the hub's
+// containr-network, so Traefik's Docker provider can't see them. Instead
+// the backend renders one file-provider config per service into
+// TRAEFIK_DYNAMIC_DIR (a directory Traefik watches), pointing the
+// loadbalancer at the node's reachable IP + the ephemeral host port the
+// agent reported back after `create_container`.
+//
+// Empty dir → feature off (bare-metal dev). Files are best-effort: a
+// failed write never fails a reconcile.
+
+func ingressDir() string { return os.Getenv("TRAEFIK_DYNAMIC_DIR") }
+
+func ingressFile(serviceID string) string {
+	return filepath.Join(ingressDir(), "containr-"+serviceID+".yml")
+}
+
+// jsonInt coerces JSON-ish numbers (int/int32/int64/float64) to int —
+// spec fields arrive as int32, agent payloads unmarshal as float64.
+func jsonInt(v interface{}) int {
+	switch n := v.(type) {
+	case int:
+		return n
+	case int32:
+		return int(n)
+	case int64:
+		return int(n)
+	case float64:
+		return int(n)
+	}
+	return 0
+}
+
+// reportedHostPorts parses the agent's create_container result —
+// {"name": ..., "host_ports": {"80/tcp": "32768"}}. Older agents return a
+// bare name string; JSON parse failure means no port info.
+func reportedHostPorts(result string) map[string]string {
+	var out struct {
+		HostPorts map[string]string `json:"host_ports"`
+	}
+	if json.Unmarshal([]byte(result), &out) != nil {
+		return nil
+	}
+	return out.HostPorts
+}
+
+// nodeIngressIP picks the address the hub can reach the node on. Mesh
+// overlays first — the agent operator joined a mesh precisely so the hub
+// can reach it — then the reported primary IP as a LAN fallback.
+func nodeIngressIP(agent sqlcdb.NodeAgent) string {
+	var meta struct {
+		Mesh map[string]string `json:"mesh"`
+	}
+	_ = json.Unmarshal(agent.Metadata.RawMessage, &meta)
+	for _, prefix := range []string{"tailscale", "netbird", "wg", "zt"} {
+		var keys []string
+		for name := range meta.Mesh {
+			keys = append(keys, name)
+		}
+		sort.Strings(keys)
+		for _, name := range keys {
+			if strings.HasPrefix(name, prefix) && meta.Mesh[name] != "" {
+				return meta.Mesh[name]
+			}
+		}
+	}
+	return agent.IpAddress
+}
+
+// syncRemoteIngress rewrites the service's file-provider config from the
+// live remote replica set. Called after every remote reconcile so replica
+// adds/removals and node retargets converge the upstream list.
+func syncRemoteIngress(ctx context.Context, db *database.DB, spec deployment.RuntimeSpec) {
+	if ingressDir() == "" {
+		return
+	}
+	domains := spec.Domains
+	if len(domains) == 0 && spec.Domain != "" {
+		domains = []string{spec.Domain}
+	}
+	if len(domains) == 0 || spec.Port <= 0 {
+		removeServiceIngress(spec.ServiceID)
+		return
+	}
+
+	q := sqlcdb.New(db.DB)
+	rows, err := q.ListServiceContainers(ctx, spec.ServiceID)
+	if err != nil {
+		return
+	}
+	type upstream struct{ ip, port string }
+	var servers []upstream
+	for _, row := range rows {
+		var st struct {
+			State string `json:"state"`
+		}
+		_ = json.Unmarshal(row.Status.RawMessage, &st)
+		if st.State != "running" {
+			continue
+		}
+		var port string
+		var plist []map[string]interface{}
+		if err := json.Unmarshal(row.Ports.RawMessage, &plist); err == nil {
+			for _, p := range plist {
+				if hp, ok := p["host_port"].(float64); ok && hp > 0 {
+					port = fmt.Sprintf("%d", int(hp))
+				}
+			}
+		}
+		if port == "" {
+			continue
+		}
+		agent, err := q.GetAgent(ctx, row.NodeAgentID)
+		if err != nil {
+			continue
+		}
+		if ip := nodeIngressIP(agent); ip != "" {
+			servers = append(servers, upstream{ip, port})
+		}
+	}
+	if len(servers) == 0 {
+		removeServiceIngress(spec.ServiceID)
+		return
+	}
+
+	router := "svc-" + spec.ServiceID[:8]
+	rules := make([]string, 0, len(domains))
+	for _, d := range domains {
+		rules = append(rules, "Host(`"+d+"`)")
+	}
+	var b strings.Builder
+	b.WriteString("http:\n  routers:\n    " + router + ":\n")
+	b.WriteString("      rule: \"" + strings.Join(rules, " || ") + "\"\n")
+	b.WriteString("      entrypoints: [web]\n")
+	b.WriteString("      service: " + router + "\n")
+	b.WriteString("  services:\n    " + router + ":\n      loadBalancer:\n        servers:\n")
+	for _, s := range servers {
+		b.WriteString("          - url: \"http://" + s.ip + ":" + s.port + "\"\n")
+	}
+	// Atomic-ish: write temp then rename so Traefik's watcher never reads a
+	// truncated file.
+	tmp := ingressFile(spec.ServiceID) + ".tmp"
+	if err := os.WriteFile(tmp, []byte(b.String()), 0o644); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, ingressFile(spec.ServiceID))
+}
+
+// removeServiceIngress deletes the service's remote route. Called on
+// remote teardown and when a service returns to local placement.
+func removeServiceIngress(serviceID string) {
+	if ingressDir() == "" {
+		return
+	}
+	_ = os.Remove(ingressFile(serviceID))
+}
+
+// wakeUpstreamURL is where a sleeping remote service's route points —
+// the backend's wake-page endpoint. Defaults to the compose service name;
+// TRAEFIK_BACKEND_URL overrides for custom layouts.
+func wakeUpstreamURL(apiPort int) string {
+	if v := strings.TrimSpace(os.Getenv("TRAEFIK_BACKEND_URL")); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return fmt.Sprintf("http://containr-backend:%d", apiPort)
+}
+
+// writeWakeIngress routes the service's domains at the wake-page endpoint —
+// first hit triggers the wake reconcile and serves a reloading page.
+func writeWakeIngress(serviceID string, domains []string, apiPort int) {
+	if ingressDir() == "" {
+		return
+	}
+	sort.Strings(domains)
+	router := "svc-" + serviceID[:8] + "-wake"
+	rules := make([]string, 0, len(domains))
+	for _, d := range domains {
+		rules = append(rules, "Host(`"+d+"`)")
+	}
+	var b strings.Builder
+	mw := router + "-rw"
+	b.WriteString("http:\n  routers:\n    " + router + ":\n")
+	b.WriteString("      rule: \"" + strings.Join(rules, " || ") + "\"\n")
+	b.WriteString("      entrypoints: [web]\n")
+	b.WriteString("      service: " + router + "\n")
+	b.WriteString("      priority: 100\n")
+	b.WriteString("      middlewares: [" + mw + "]\n")
+	b.WriteString("  middlewares:\n    " + mw + ":\n")
+	b.WriteString("      replacePath:\n        path: \"/api/v1/internal/wake-page/" + serviceID + "\"\n")
+	b.WriteString("  services:\n    " + router + ":\n      loadBalancer:\n        servers:\n")
+	b.WriteString("          - url: \"" + wakeUpstreamURL(apiPort) + "\"\n")
+	tmp := ingressFile(serviceID) + ".tmp"
+	if err := os.WriteFile(tmp, []byte(b.String()), 0o644); err != nil {
+		return
+	}
+	_ = os.Rename(tmp, ingressFile(serviceID))
+}

app/backend/internal/api/noderunner.go

@@ -0,0 +1,496 @@
+package api
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/json"
+	"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. Domains route through the file provider —
+// syncRemoteIngress renders per-service configs from live inventory.
+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)
+	}
+	return r.reconcileOnAgents(ctx, spec, func(int) string { return spec.NodeID })
+}
+
+// ReconcileSpread distributes replicas deterministically across online,
+// schedulable agents: replica i lands on agents[i % len(agents)], agents
+// sorted by id. Replicas wrap when they outnumber nodes. The local host is
+// not a spread target — pin "local" or leave unset for local execution.
+func (r *agentNodeRunner) ReconcileSpread(ctx context.Context, spec deployment.RuntimeSpec) (*deployment.RuntimeState, error) {
+	tagsRaw, _ := json.Marshal(spec.PlacementTags)
+	if len(spec.PlacementTags) == 0 {
+		tagsRaw = []byte("[]")
+	}
+	agents, err := r.q.ListSchedulableAgentsMatching(ctx, json.RawMessage(tagsRaw))
+	if err != nil {
+		return nil, fmt.Errorf("list schedulable nodes: %w", err)
+	}
+	if len(agents) == 0 {
+		if len(spec.PlacementTags) > 0 {
+			return nil, fmt.Errorf("no online schedulable nodes carry placement tags %v — tag a node or relax the requirement", spec.PlacementTags)
+		}
+		return nil, fmt.Errorf("no online schedulable nodes — connect an agent or unset spread")
+	}
+	return r.reconcileOnAgents(ctx, spec, func(i int) string {
+		return agents[i%len(agents)].ID
+	})
+}
+
+// ReconcileAuto resolves the least-loaded online agent matching the
+// service's placement tags and reconciles every replica onto it. Stale
+// replicas on other agents retire through reconcileOnAgents — a service
+// follows its tags when the matching set changes.
+func (r *agentNodeRunner) ReconcileAuto(ctx context.Context, spec deployment.RuntimeSpec) (*deployment.RuntimeState, error) {
+	tagsRaw, _ := json.Marshal(spec.PlacementTags)
+	if len(spec.PlacementTags) == 0 {
+		tagsRaw = []byte("[]")
+	}
+	agentID, err := r.q.PickLeastLoadedAgentMatching(ctx, json.RawMessage(tagsRaw))
+	if err != nil {
+		return nil, fmt.Errorf("no online nodes carry placement tags %v", spec.PlacementTags)
+	}
+	return r.reconcileOnAgents(ctx, spec, func(int) string { return agentID })
+}
+
+// RemoteRuntimeState reads the service's remote replicas from inventory.
+// Rows only carry the last dispatched state — the agent doesn't stream
+// container events — so "running" means "last create succeeded".
+func (r *agentNodeRunner) RemoteRuntimeState(ctx context.Context, serviceID string) (*deployment.RuntimeState, error) {
+	rows, err := r.q.ListServiceContainers(ctx, serviceID)
+	if err != nil {
+		return nil, err
+	}
+	state := &deployment.RuntimeState{Status: "stopped"}
+	running := 0
+	for _, row := range rows {
+		var status struct {
+			State string `json:"state"`
+		}
+		unmarshalRaw(row.Status, &status)
+		if status.State == "" || status.State == "removed" {
+			continue
+		}
+		replica := -1
+		if idx, err := strconv.Atoi(strings.TrimPrefix(row.Name, fmt.Sprintf("containr-%s-", serviceID))); err == nil {
+			replica = idx
+		}
+		state.Containers = append(state.Containers, deployment.RuntimeContainer{
+			ID: row.ID, Name: row.Name, State: status.State, Replica: replica,
+		})
+		if status.State == "running" {
+			running++
+		}
+	}
+	if running > 0 {
+		state.Status = "running"
+	}
+	return state, nil
+}
+
+// reconcileOnAgents creates the service's replicas on the agents chosen by
+// targetFor and retires stale replicas on any agent — including leftovers
+// from a previous pin or a different spread assignment.
+func (r *agentNodeRunner) reconcileOnAgents(ctx context.Context, spec deployment.RuntimeSpec, targetFor func(replica int) string) (*deployment.RuntimeState, error) {
+	replicas := spec.Replicas
+	if replicas < 1 {
+		replicas = 1
+	}
+
+	prefix := fmt.Sprintf("containr-%s-", spec.ServiceID)
+	existing, _ := r.q.ListServiceContainers(ctx, spec.ServiceID)
+	for _, row := range existing {
+		if !strings.HasPrefix(row.Name, prefix) {
+			continue
+		}
+		replica, err := strconv.Atoi(strings.TrimPrefix(row.Name, prefix))
+		keep := err == nil && replica < replicas && row.NodeAgentID == targetFor(replica)
+		if keep {
+			continue
+		}
+		if _, cmdErr := r.enqueueAndWait(ctx, row.NodeAgentID, "", "remove_container",
+			map[string]interface{}{"container_name": row.Name}); cmdErr != nil {
+			return nil, fmt.Errorf("remove stale replica %s on node %s: %w", row.Name, row.NodeAgentID, cmdErr)
+		}
+		_ = r.q.UpdateContainerStatus(ctx, sqlcdb.UpdateContainerStatusParams{
+			ID:     row.ID,
+			Status: rawJSON(map[string]interface{}{"state": "removed"}),
+		})
+	}
+
+	// Ship the image to every distinct target agent before replicas start.
+	// RemoteBuild nodes docker-build from the packaged context artifact;
+	// RemoteLoad nodes docker-load a saved tarball (local-tag rollbacks).
+	// Registry-pullable images skip this — docker run pulls on demand.
+	if spec.RemoteBuild != nil || spec.RemoteLoad != nil {
+		seen := map[string]bool{}
+		for i := 0; i < replicas; i++ {
+			agentID := targetFor(i)
+			if seen[agentID] {
+				continue
+			}
+			seen[agentID] = true
+			if spec.RemoteBuild != nil {
+				buildArgs := map[string]interface{}{}
+				for k, v := range spec.RemoteBuild.BuildArgs {
+					buildArgs[k] = v
+				}
+				_, err := r.enqueueAndWaitTimeout(ctx, agentID, "", "build_image",
+					map[string]interface{}{
+						"artifact_id": spec.RemoteBuild.ArtifactID,
+						"image":       spec.Image,
+						"build_args":  buildArgs,
+						"no_cache":    spec.RemoteBuild.NoCache,
+					}, 25*time.Minute)
+				if err != nil {
+					return nil, fmt.Errorf("build image on node %s: %w", agentID, err)
+				}
+			} else if spec.RemoteLoad != nil {
+				_, err := r.enqueueAndWaitTimeout(ctx, agentID, "", "load_image",
+					map[string]interface{}{
+						"artifact_id": spec.RemoteLoad.ArtifactID,
+					}, 10*time.Minute)
+				if err != nil {
+					return nil, fmt.Errorf("load image on node %s: %w", agentID, err)
+				}
+			}
+		}
+	}
+
+	state := &deployment.RuntimeState{Desired: replicas, Status: "running"}
+	for i := 0; i < replicas; i++ {
+		agentID := targetFor(i)
+		name := remoteContainerName(spec.ServiceID, i)
+		containerID := remoteContainerID(agentID, spec.ServiceID, i)
+		container, env, ports, volumes, restart := r.replicaPayload(spec, agentID, i, name)
+
+		_ = r.q.UpsertServiceContainer(ctx, sqlcdb.UpsertServiceContainerParams{
+			ID:            containerID,
+			Name:          name,
+			Image:         spec.Image,
+			ProjectID:     spec.ProjectID,
+			ServiceID:     spec.ServiceID,
+			NodeAgentID:   agentID,
+			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}),
+		})
+
+		result, err := r.enqueueAndWait(ctx, agentID, containerID, "create_container",
+			map[string]interface{}{"container": container})
+		if err != nil {
+			return nil, fmt.Errorf("replica %d on node %s: %w", i, agentID, err)
+		}
+		if assigned := reportedHostPorts(result); len(assigned) > 0 {
+			for _, p := range ports {
+				pm, ok := p.(map[string]interface{})
+				if !ok {
+					continue
+				}
+				cport := jsonInt(pm["container_port"])
+				proto, _ := pm["protocol"].(string)
+				if hp, ok := assigned[fmt.Sprintf("%d/%s", cport, proto)]; ok {
+					if n, err := strconv.Atoi(hp); err == nil {
+						pm["host_port"] = n
+					}
+				}
+			}
+			_ = r.q.UpdateContainerPorts(ctx, sqlcdb.UpdateContainerPortsParams{
+				ID:     containerID,
+				Status: rawJSON(map[string]interface{}{"state": "running", "health": "none"}),
+				Ports:  rawJSON(ports),
+			})
+		} else {
+			_ = 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,
+		})
+	}
+	syncRemoteIngress(ctx, r.db, spec)
+	return state, nil
+}
+
+// replicaPayload builds the agent create_container payload for one replica.
+func (r *agentNodeRunner) replicaPayload(spec deployment.RuntimeSpec, agentID string, i int, name string) (map[string]interface{}, map[string]interface{}, []interface{}, []interface{}, string) {
+	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)
+	}
+	return 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":    agentID,
+		},
+	}, env, ports, volumes, restart
+}
+
+// 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
+		}
+		// Tombstoned replicas are already gone remotely — skip the dispatch
+		// or a fresh docker rm on a missing name reports a false failure.
+		if action == "remove" {
+			var st struct {
+				State string `json:"state"`
+			}
+			if err := json.Unmarshal(row.Status.RawMessage, &st); err == nil && st.State == "removed" {
+				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
+	}
+	if err := r.q.DeleteServiceContainersOnAgent(ctx, sqlcdb.DeleteServiceContainersOnAgentParams{
+		NodeAgentID: agentID,
+		ServiceID:   serviceID,
+	}); err != nil {
+		return err
+	}
+	removeServiceIngress(serviceID)
+	return nil
+}
+
+// RetireService removes the service's remote replicas wherever they run —
+// called when the service converges to local placement so a cleared pin or
+// removed tag requirement doesn't leave containers behind.
+func (r *agentNodeRunner) RetireService(ctx context.Context, serviceID string) error {
+	agentIDs, err := r.q.ListServiceAgents(ctx, serviceID)
+	if err != nil {
+		return err
+	}
+	for _, agentID := range agentIDs {
+		if err := r.RemoveService(ctx, serviceID, agentID); err != nil {
+			return fmt.Errorf("retire on node %s: %w", agentID, err)
+		}
+	}
+	removeServiceIngress(serviceID)
+	return nil
+}
+
+// enqueueAndWait pushes a command to the agent's queue and polls for the
+// reported result, returning the agent's result string on success. 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{}) (string, error) {
+	return r.enqueueAndWaitTimeout(ctx, agentID, containerID, cmdType, payload, 8*time.Minute)
+}
+
+func (r *agentNodeRunner) enqueueAndWaitTimeout(ctx context.Context, agentID, containerID, cmdType string, payload map[string]interface{}, timeout time.Duration) (string, 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(timeout) // image pulls/builds 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 row.Result.String, 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 that carries every required placement tag;
+// "" / "local" clears the pin. An explicit pin bypasses tag filtering —
+// the operator is overriding placement on purpose.
+func resolveNodePin(ctx context.Context, db *database.DB, requested string, requiredTags []string) (string, error) {
+	requested = strings.TrimSpace(requested)
+	if requested == "" || requested == "local" {
+		return "", nil
+	}
+	q := sqlcdb.New(db.DB)
+	if requested == "auto" {
+		tagsRaw, _ := json.Marshal(requiredTags)
+		if len(requiredTags) == 0 {
+			tagsRaw = []byte("[]")
+		}
+		id, err := q.PickLeastLoadedAgentMatching(ctx, json.RawMessage(tagsRaw))
+		if err != nil {
+			if len(requiredTags) > 0 {
+				return "", fmt.Errorf("no online nodes carry placement tags %v", requiredTags)
+			}
+			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

@@ -0,0 +1,238 @@
+package api
+
+// Notification producers — the emitters behind `insertUserNotification`.
+// Deployment success/failure lives in deployments.go; this file covers
+// the remaining producers from the roadmap: admin fan-out helper, the
+// agent offline/online sweep, and the upgrade-available check.
+
+import (
+	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// Version is stamped at image build time via -ldflags "-X
+// containr/internal/api.Version=…". "dev" disables the upgrade check.
+var Version = "dev"
+
+// notifyAdmins inserts a notification for every admin user. Best-effort.
+func notifyAdmins(db *database.DB, kind, title, body, resourceType, resourceID string) {
+	if db == nil {
+		return
+	}
+	rows, err := db.Query(`SELECT id FROM users WHERE is_admin`)
+	if err != nil {
+		log.Printf("containr: notify admins lookup failed: %v", err)
+		return
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var id uuid.UUID
+		if err := rows.Scan(&id); err == nil {
+			insertUserNotification(db, id.String(), kind, title, body, resourceType, resourceID)
+		}
+	}
+}
+
+// StartAgentHealthSweep marks agents offline when their heartbeat goes
+// stale (and back online when it resumes), notifying admins on each
+// transition. Heartbeats keep the row fresh via UpdateAgentHeartbeat.
+func StartAgentHealthSweep(ctx context.Context, db *database.DB) {
+	const staleAfter = 3 * time.Minute
+	go func() {
+		ticker := time.NewTicker(time.Minute)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				reconcileAgentHealth(db, staleAfter)
+			}
+		}
+	}()
+}
+
+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)
+	var agents []agentHealthRow
+	rows, err := db.Query(
+		`SELECT id, COALESCE(name, hostname, id::text), COALESCE(status, ''),
+		        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 agentHealthRow
+		if err := rows.Scan(&a.id, &a.name, &a.status, &a.stale, &a.autoPrune); err == nil {
+			agents = append(agents, a)
+		}
+	}
+	rows.Close()
+
+	for _, a := range agents {
+		switch {
+		case a.stale && a.status != "offline":
+			if _, err := db.Exec(
+				`UPDATE node_agents SET status = 'offline', updated_at = NOW() WHERE id = $1`, a.id); err != nil {
+				continue
+			}
+			notifyAdmins(db, "agent", "Node agent offline",
+				fmt.Sprintf("Agent %s missed its heartbeat for over %s.", a.name, staleAfter), "agent", a.id)
+		case !a.stale && a.status == "offline":
+			if _, err := db.Exec(
+				`UPDATE node_agents SET status = 'online', updated_at = NOW() WHERE id = $1`, a.id); err != nil {
+				continue
+			}
+			notifyAdmins(db, "agent", "Node agent back online",
+				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
+// notifies admins when it is newer than the running version. The last
+// notified tag is persisted in app_settings so restarts don't re-fire.
+func StartUpgradeCheck(ctx context.Context, db *database.DB, currentVersion string) {
+	if currentVersion == "" || currentVersion == "dev" {
+		return
+	}
+	go func() {
+		checkForUpgrade(db, currentVersion)
+		ticker := time.NewTicker(24 * time.Hour)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				checkForUpgrade(db, currentVersion)
+			}
+		}
+	}()
+}
+
+func checkForUpgrade(db *database.DB, currentVersion string) {
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
+		"https://api.github.com/repos/Dvorinka/Containr/releases/latest", nil)
+	if err != nil {
+		return
+	}
+	req.Header.Set("Accept", "application/vnd.github+json")
+	req.Header.Set("User-Agent", "containr-upgrade-check")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return
+	}
+	var release struct {
+		TagName string `json:"tag_name"`
+		HTMLURL string `json:"html_url"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&release); err != nil || release.TagName == "" {
+		return
+	}
+	if !semverNewer(release.TagName, currentVersion) {
+		return
+	}
+
+	var lastNotified string
+	_ = db.QueryRow(`SELECT value FROM app_settings WHERE key = 'upgrade_notified_tag'`).Scan(&lastNotified)
+	if lastNotified == release.TagName {
+		return
+	}
+	notifyAdmins(db, "upgrade", "Containr update available",
+		fmt.Sprintf("Release %s is available (running %s). %s", release.TagName, currentVersion, release.HTMLURL),
+		"release", release.TagName)
+	_, _ = db.Exec(
+		`INSERT INTO app_settings (key, value, updated_at) VALUES ('upgrade_notified_tag', $1, NOW())
+		 ON CONFLICT (key) DO UPDATE SET value = $1, updated_at = NOW()`, release.TagName)
+}
+
+// semverNewer reports whether candidate is a higher semver than current.
+// Non-semver input (e.g. "dev", commit hashes) compares false.
+func semverNewer(candidate, current string) bool {
+	parse := func(s string) ([]int, bool) {
+		s = strings.TrimPrefix(strings.TrimSpace(s), "v")
+		// Prerelease/build metadata sorts after the same base version
+		// upstream — for "is a newer release available" purposes the base
+		// comparison is what matters.
+		if j := strings.IndexAny(s, "-+"); j >= 0 {
+			s = s[:j]
+		}
+		parts := strings.Split(s, ".")
+		if len(parts) == 0 || len(parts) > 3 {
+			return nil, false
+		}
+		out := make([]int, 3)
+		for i, p := range parts {
+			n, err := strconv.Atoi(p)
+			if err != nil {
+				return nil, false
+			}
+			out[i] = n
+		}
+		return out, true
+	}
+	c, ok1 := parse(candidate)
+	cur, ok2 := parse(current)
+	if !ok1 || !ok2 {
+		return false
+	}
+	for i := 0; i < 3; i++ {
+		if c[i] != cur[i] {
+			return c[i] > cur[i]
+		}
+	}
+	return false
+}

app/backend/internal/api/notification_producers_test.go

@@ -0,0 +1,26 @@
+package api
+
+import "testing"
+
+func TestSemverNewer(t *testing.T) {
+	cases := []struct {
+		candidate, current string
+		want               bool
+	}{
+		{"v1.2.3", "v1.2.2", true},
+		{"1.3.0", "v1.2.9", true},
+		{"v2.0.0", "v1.9.9", true},
+		{"v1.2.3", "v1.2.3", false},
+		{"v1.2.0", "v1.2.3", false},
+		{"v1.10.0", "v1.9.9", true}, // numeric, not lexicographic
+		{"dev", "v1.0.0", false},
+		{"v1.0.0", "main", false},
+		{"v1.2.3-rc.1", "v1.2.2", true}, // prerelease suffix tolerated
+		{"", "v1.0.0", false},
+	}
+	for _, tc := range cases {
+		if got := semverNewer(tc.candidate, tc.current); got != tc.want {
+			t.Errorf("semverNewer(%q, %q) = %v, want %v", tc.candidate, tc.current, got, tc.want)
+		}
+	}
+}

app/backend/internal/api/routes.go

@@ -5,6 +5,7 @@ import (
 	"log"
 	"net/http"
 	"os"
+	"path/filepath"
 	"time"
 
 	"containr/internal/build"
@@ -43,6 +44,11 @@ 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)
+		initArtifacts(filepath.Join("/tmp/containr-builds", "artifacts"))
+		purgeStaleArtifacts()
+		// 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)
 	}
@@ -109,6 +115,13 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 	// Audit retention — prunes rows past AUDIT_RETENTION_DAYS (default 90).
 	StartAuditRetention(context.Background(), db)
 
+	// Agent health — marks stale heartbeats offline, notifies admins on
+	// offline/recovery transitions.
+	StartAgentHealthSweep(context.Background(), db)
+
+	// Daily upgrade check — notifies admins when a newer release exists.
+	StartUpgradeCheck(context.Background(), db, Version)
+
 	// Initialize database handler
 	databaseHandler := NewDatabaseHandler(db.DB, dockerClient)
 
@@ -275,6 +288,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 			// Wake callback for sleep-mode placeholders. Unauthenticated but
 			// non-destructive: it only reconciles the service back to running.
 			public.Any("/internal/wake/:id", handleServiceWake)
+			public.Any("/internal/wake-page/:id", handleServiceWakePage)
 		}
 
 		// Read routes — public browsing. OptionalAuth resolves a session when
@@ -348,6 +362,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)
 
@@ -388,6 +403,9 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 			authed.POST("/deployments/:id/rollback", handleRollbackDeployment)
 			authed.POST("/deployments/:id/cancel", handleCancelDeployment)
 
+			// Interactive terminal — WebSocket → docker exec pty.
+			authed.GET("/services/:id/terminal", handleServiceTerminal)
+
 			// Environment variables — secrets, owner/admin only.
 			authed.GET("/services/:id/variables", handleGetVariables)
 			authed.PUT("/services/:id/variables", handleUpdateVariables)
@@ -469,6 +487,7 @@ func SetupRoutes(router *gin.Engine, db *database.DB, redis *database.Redis, cfg
 			authed.POST("/templates/:id/deploy", handleCreateFromTemplate)
 			authed.POST("/templates/:id/plan", handlePlanTemplate)
 			authed.POST("/templates/import/compose", handleImportCompose)
+			authed.POST("/templates/import/git", handleImportGitCompose)
 			authed.POST("/templates/deploy", handleDeployInlineGraph)
 
 			authed.POST("/cron-jobs", handleCreateCronJob)

app/backend/internal/api/runtime.go

@@ -18,6 +18,61 @@ import (
 	"github.com/google/uuid"
 )
 
+// remoteAgentsForService lists every agent holding inventory rows for the
+// service — covers pinned placements, spread replicas, and leftovers from a
+// since-cleared pin.
+func remoteAgentsForService(ctx context.Context, db *database.DB, serviceID uuid.UUID) []string {
+	rows, err := db.Query(
+		`SELECT DISTINCT node_agent_id FROM container_instances WHERE service_id = $1`,
+		serviceID,
+	)
+	if err != nil {
+		return nil
+	}
+	defer rows.Close()
+	var ids []string
+	for rows.Next() {
+		var id string
+		if rows.Scan(&id) == nil && id != "" {
+			ids = append(ids, id)
+		}
+	}
+	return ids
+}
+
+// serviceLifecycle routes a start/stop/restart action to every agent holding
+// the service's replicas, then to the local Docker engine. Both run — a
+// service can't be pinned and local at once, but stale containers from a
+// cleared pin shouldn't survive a stop.
+func serviceLifecycle(ctx context.Context, db *database.DB, engine *deployment.DeploymentEngine, serviceID uuid.UUID, action string) error {
+	for _, agentID := range remoteAgentsForService(ctx, db, serviceID) {
+		if err := engine.ControlServiceOnNode(ctx, serviceID.String(), agentID, action); err != nil {
+			return err
+		}
+	}
+	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 nodes
+// (pinned or spread) and the local Docker host.
+func removeServiceRuntime(ctx context.Context, db *database.DB, engine *deployment.DeploymentEngine, serviceID uuid.UUID) {
+	for _, agentID := range remoteAgentsForService(ctx, db, serviceID) {
+		_ = engine.RemoveServiceContainersOnNode(ctx, serviceID.String(), agentID)
+	}
+	_ = 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 +92,9 @@ func serviceRuntimeSpec(db *database.DB, service Service) (deployment.RuntimeSpe
 		Domain:        service.Domain,
 		HealthPath:    service.HealthCheckPath,
 		RestartPolicy: service.RestartPolicy,
+		NodeID:        serviceNodeID(db, service.ID),
+		Spread:        serviceSpread(db, service.ID),
+		PlacementTags: servicePlacementTags(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
@@ -341,6 +399,7 @@ func handleGetServiceRuntime(c *gin.Context) {
 		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
 		return
 	}
+	mergeRemoteRuntime(c.Request.Context(), engine, service.ID.String(), state)
 	engine.ProbeServiceHealth(c.Request.Context(), state, service.ProjectID.String(), service.Name, service.Port, service.HealthCheckPath)
 	persistPublishedPort(db, service.ID, state.Ports)
 	if host := requestHostname(c); host != "" {
@@ -384,7 +443,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 +461,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 +480,7 @@ func handleServiceRestart(c *gin.Context) {
 		return
 	}
 	ctx := c.Request.Context()
-	if err := engine.StopService(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
-	}
-	if err := engine.StartService(ctx, service.ID.String()); err != nil {
 		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
 		return
 	}
@@ -535,6 +590,37 @@ func enqueueServiceRedeploy(c *gin.Context, db *database.DB, service Service) bo
 	return true
 }
 
+// mergeRemoteRuntime folds inventory-backed remote replica state into a
+// local runtime view so pinned and spread services report their containers.
+// Remote rows carry deterministic UUIDs, local ones Docker IDs — no overlap.
+func mergeRemoteRuntime(ctx context.Context, engine *deployment.DeploymentEngine, serviceID string, state *deployment.RuntimeState) {
+	remote, err := engine.RemoteRuntimeState(ctx, serviceID)
+	if err != nil || remote == nil {
+		return
+	}
+	running := 0
+	for _, c := range state.Containers {
+		if c.State == "running" {
+			running++
+		}
+	}
+	for _, rc := range remote.Containers {
+		state.Containers = append(state.Containers, rc)
+		if rc.State == "running" {
+			running++
+		}
+	}
+	switch {
+	case len(state.Containers) == 0:
+	case running == 0:
+		state.Status = "stopped"
+	case running < state.Desired:
+		state.Status = "degraded"
+	default:
+		state.Status = "running"
+	}
+}
+
 // persistPublishedPort records the host port Docker actually bound so later
 // redeploys can reuse it. Idempotent — only writes when the value changed.
 func persistPublishedPort(db *database.DB, serviceID uuid.UUID, ports []uint16) {
@@ -558,7 +644,11 @@ func liveServiceStatus(c *gin.Context, db *database.DB, service *Service) {
 	ctx, cancel := context.WithTimeout(c.Request.Context(), 3*time.Second)
 	defer cancel()
 	state, err := engine.RuntimeState(ctx, service.ID.String(), service.Replicas)
-	if err != nil || state == nil || len(state.Containers) == 0 {
+	if err != nil || state == nil {
+		return
+	}
+	mergeRemoteRuntime(ctx, engine, service.ID.String(), state)
+	if len(state.Containers) == 0 {
 		return
 	}
 	if state.Status != service.Status {

app/backend/internal/api/security.go

@@ -29,9 +29,27 @@ type SecurityHandler struct {
 func NewSecurityHandler(db *database.DB, encryptionKey string) *SecurityHandler {
 	encryptionManager, _ := security.NewEncryptionManager(encryptionKey)
 
+	scanner := security.NewScanner(db)
+	// Notify the project owner when a background scan completes — criticals
+	// earn a distinct title so they stand out in the notification list.
+	scanner.OnScanComplete = func(scan *security.SecurityScan) {
+		var ownerID string
+		if err := db.QueryRow(`SELECT owner_id::text FROM projects WHERE id = $1`, scan.ProjectID).Scan(&ownerID); err != nil || ownerID == "" {
+			return
+		}
+		title := "Security scan completed"
+		if scan.Summary.Critical > 0 || scan.Summary.High > 0 {
+			title = "Security scan found issues"
+		}
+		insertUserNotification(db, ownerID, "security", title,
+			fmt.Sprintf("%s scan finished: %d critical, %d high, %d total findings (score %d/100).",
+				scan.ScanType, scan.Summary.Critical, scan.Summary.High, scan.Summary.Total, scan.Summary.Score),
+			"project", scan.ProjectID)
+	}
+
 	return &SecurityHandler{
 		db:                   db,
-		scanner:              security.NewScanner(db),
+		scanner:              scanner,
 		complianceManager:    security.NewComplianceManager(db),
 		encryptionManager:    encryptionManager,
 		dataRetentionManager: security.NewDataRetentionManager(encryptionManager),

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,18 @@ 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"`
+	// NodeID pins the service to a node agent ("" = local Docker host,
-	UpdatedAt        time.Time       `json:"updated_at" db:"updated_at"`
+	// 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:"-"`
+	// Spread distributes replicas across every online, schedulable agent.
+	// Mutually exclusive with an explicit NodeID pin.
+	Spread bool `json:"spread" db:"-"`
+	// PlacementTags restrict auto/spread candidates to agents carrying all
+	// listed tags. An explicit pin overrides them — pin + tags is rejected.
+	PlacementTags []string  `json:"placement_tags,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 +75,78 @@ 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 ""
+}
+
+// serviceSpread reads the spread column with the same lazy pattern.
+func serviceSpread(db *database.DB, serviceID uuid.UUID) bool {
+	var spread bool
+	if err := db.QueryRow(`SELECT COALESCE(spread, false) FROM services WHERE id = $1`, serviceID).Scan(&spread); err == nil {
+		return spread
+	}
+	return false
+}
+
+// servicePlacementTags reads the placement_tags column with the lazy pattern.
+func servicePlacementTags(db *database.DB, serviceID uuid.UUID) []string {
+	var raw []byte
+	if err := db.QueryRow(`SELECT placement_tags FROM services WHERE id = $1`, serviceID).Scan(&raw); err != nil {
+		return nil
+	}
+	var tags []string
+	if err := json.Unmarshal(raw, &tags); err != nil {
+		return nil
+	}
+	return tags
+}
+
+// normalizePlacementTags trims, lowercases, and dedupes tag input. Tags are
+// matched verbatim against node_agents.tags.
+func normalizePlacementTags(tags []string) []string {
+	seen := map[string]bool{}
+	out := make([]string, 0, len(tags))
+	for _, t := range tags {
+		t = strings.ToLower(strings.TrimSpace(t))
+		if t == "" || seen[t] {
+			continue
+		}
+		seen[t] = true
+		out = append(out, t)
+	}
+	return out
+}
+
+// tagsJSON marshals a tag list for a jsonb column; empty stays an array, not null.
+func tagsJSON(tags []string) []byte {
+	if len(tags) == 0 {
+		return []byte("[]")
+	}
+	raw, _ := json.Marshal(tags)
+	return raw
+}
+
+// loadServiceNode fills the pin + spread + placement tags + the agent's
+// display name for responses.
+func loadServiceNode(db *database.DB, s *Service) {
+	var name sql.NullString
+	s.NodeID = serviceNodeID(db, s.ID)
+	s.Spread = serviceSpread(db, s.ID)
+	s.PlacementTags = servicePlacementTags(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 +224,19 @@ type CreateServiceRequest struct {
 	MemoryReserve   string          `json:"memory_reserve"`
 	StaticBuildCmd  string          `json:"static_build_cmd"`
 	StaticDir       string          `json:"static_dir"`
+	// SleepEnabled/SleepIdleMinutes opt the service into scale-to-zero at
+	// create time — previously update-only, which surprised API/CLI users.
+	SleepEnabled     *bool `json:"sleep_enabled"`
+	SleepIdleMinutes *int  `json:"sleep_idle_minutes"`
+	// 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"`
+	// Spread distributes replicas across every online, schedulable agent.
+	// Mutually exclusive with an explicit node pin.
+	Spread *bool `json:"spread"`
+	// PlacementTags restrict auto/spread candidates to agents carrying all
+	// listed tags. Mutually exclusive with an explicit node pin.
+	PlacementTags []string `json:"placement_tags"`
 }
 
 // UpdateServiceRequest represents a request to update a service
@@ -170,6 +266,15 @@ 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"`
+	// Spread toggles multi-node replica distribution; pointer so false is
+	// a real update, not a missing field.
+	Spread *bool `json:"spread"`
+	// PlacementTags restrict auto/spread candidates to agents carrying all
+	// listed tags; pointer so [] clears the requirement. Mutually exclusive
+	// with an explicit node pin.
+	PlacementTags *[]string `json:"placement_tags"`
 }
 
 // handleGetServices retrieves all services for a project
@@ -253,6 +358,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 +515,39 @@ func handleCreateService(c *gin.Context) {
 
 	sourceType := inferServiceSourceType(service)
 
+	if req.SleepEnabled != nil {
+		service.SleepEnabled = *req.SleepEnabled
+	}
+	if req.SleepIdleMinutes != nil {
+		if *req.SleepIdleMinutes < 1 || *req.SleepIdleMinutes > 1440 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "sleep_idle_minutes must be 1-1440", "code": "VALIDATION"})
+			return
+		}
+		service.SleepIdleMinutes = *req.SleepIdleMinutes
+	}
+	if req.Spread != nil {
+		service.Spread = *req.Spread
+	}
+	service.PlacementTags = normalizePlacementTags(req.PlacementTags)
+	if req.NodeID != "" {
+		if service.Spread && req.NodeID != "auto" && req.NodeID != "local" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "spread and an explicit node pin are mutually exclusive", "code": "VALIDATION"})
+			return
+		}
+		if len(service.PlacementTags) > 0 && req.NodeID != "auto" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "placement tags only apply to remote placement — set node_id=\"auto\" or omit it", "code": "VALIDATION"})
+			return
+		}
+		nodeID, nodeErr := resolveNodePin(c.Request.Context(), db.(*database.DB), req.NodeID, service.PlacementTags)
+		if nodeErr != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": nodeErr.Error(), "code": "VALIDATION"})
+			return
+		}
+		if !service.Spread {
+			service.NodeID = nodeID
+		}
+	}
+
 	// Insert service into database
 	_, err = db.(*database.DB).Exec(
 		`INSERT INTO services
@@ -417,16 +556,23 @@ 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, spread, placement_tags, sleep_enabled, sleep_idle_minutes,
+			 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, $35, $36, $37, $38)`,
 		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.Spread,
+		tagsJSON(service.PlacementTags),
+		service.SleepEnabled,
+		sql.NullInt32{Int32: int32(service.SleepIdleMinutes), Valid: service.SleepIdleMinutes > 0},
+		service.CreatedAt, service.UpdatedAt,
 	)
 
 	if err != nil {
@@ -456,7 +602,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 +695,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 +874,44 @@ func handleUpdateService(c *gin.Context) {
 		volumesArg = volumesJSON
 	}
 
+	if req.Spread != nil {
+		existingService.Spread = *req.Spread
+	} else {
+		existingService.Spread = serviceSpread(db.(*database.DB), serviceID)
+	}
+	if req.PlacementTags != nil {
+		existingService.PlacementTags = normalizePlacementTags(*req.PlacementTags)
+	} else {
+		existingService.PlacementTags = servicePlacementTags(db.(*database.DB), serviceID)
+	}
+	if req.NodeID != nil {
+		nodeValue := strings.TrimSpace(*req.NodeID)
+		if existingService.Spread && nodeValue != "" && nodeValue != "auto" && nodeValue != "local" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "spread and an explicit node pin are mutually exclusive — set spread=false first", "code": "VALIDATION"})
+			return
+		}
+		if len(existingService.PlacementTags) > 0 && nodeValue != "" && nodeValue != "auto" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "service has placement tags — clear them (placement_tags=[]) before pinning or going local", "code": "VALIDATION"})
+			return
+		}
+		nodeID, nodeErr := resolveNodePin(c.Request.Context(), db.(*database.DB), nodeValue, existingService.PlacementTags)
+		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)
+	}
+	if existingService.Spread && existingService.NodeID != "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "service already has an explicit node pin — clear it (node_id=\"local\") before enabling spread", "code": "VALIDATION"})
+		return
+	}
+	if len(existingService.PlacementTags) > 0 && existingService.NodeID != "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "service already has an explicit node pin — clear it (node_id=\"local\") before setting placement tags", "code": "VALIDATION"})
+		return
+	}
+
 	existingService.UpdatedAt = time.Now()
 
 	// Update service in database
@@ -736,7 +923,8 @@ 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, spread = $27,
+				placement_tags = $28::jsonb
 			WHERE id = $18`,
 		existingService.Name, existingService.Type, existingService.Image, existingService.Command,
 		existingService.Environment, existingService.GitRepo, existingService.GitBranch,
@@ -747,6 +935,9 @@ 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 != ""},
+		existingService.Spread,
+		tagsJSON(existingService.PlacementTags),
 	)
 
 	if err != nil {
@@ -816,6 +1007,7 @@ func handleUpdateService(c *gin.Context) {
 		}
 	}
 
+	loadServiceNode(db.(*database.DB), &existingService)
 	c.JSON(http.StatusOK, gin.H{"service": existingService})
 }
 
@@ -865,7 +1057,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/sleeper.go

@@ -13,6 +13,7 @@ import (
 	"time"
 
 	"containr/internal/database"
+	"containr/internal/database/sqlcdb"
 	"containr/internal/deployment"
 	"containr/internal/docker"
 
@@ -100,7 +101,20 @@ func sweepSleeping(ctx context.Context, db *database.DB, dc *docker.Client, engi
 	}
 	rows.Close()
 
+	q := sqlcdb.New(db.DB)
 	for _, svc := range candidates {
+		// Remote replicas live in inventory, not the local docker host —
+		// idleness comes from heartbeat-reported net counters instead.
+		if remote := remoteLiveContainers(ctx, q, svc.ID.String()); len(remote) > 0 {
+			var total uint64
+			for _, row := range remote {
+				total += rowNetBytes(row)
+			}
+			if markIdle(svc.ID, total, time.Duration(svc.IdleMinutes)*time.Minute) {
+				putToSleepRemote(ctx, db, q, svc, apiPort)
+			}
+			continue
+		}
 		containers, err := engine.ListServiceContainers(ctx, svc.ID.String())
 		if err != nil || len(containers) == 0 {
 			continue
@@ -125,6 +139,65 @@ func sweepSleeping(ctx context.Context, db *database.DB, dc *docker.Client, engi
 	}
 }
 
+// remoteLiveContainers returns inventory rows whose replicas are alive on
+// node agents — the signal that idleness must be measured remotely.
+func remoteLiveContainers(ctx context.Context, q *sqlcdb.Queries, serviceID string) []sqlcdb.ListServiceContainersRow {
+	rows, err := q.ListServiceContainers(ctx, serviceID)
+	if err != nil {
+		return nil
+	}
+	live := rows[:0]
+	for _, row := range rows {
+		var st struct {
+			State string `json:"state"`
+		}
+		if err := json.Unmarshal(row.Status.RawMessage, &st); err == nil &&
+			st.State != "" && st.State != "removed" && st.State != "sleeping" {
+			live = append(live, row)
+		}
+	}
+	return live
+}
+
+// rowNetBytes reads the cumulative rx+tx the agent reported at its last
+// heartbeat — 0 for rows written before the counter existed.
+func rowNetBytes(row sqlcdb.ListServiceContainersRow) uint64 {
+	var res struct {
+		NetBytes uint64 `json:"net_bytes"`
+	}
+	_ = json.Unmarshal(row.Resources.RawMessage, &res)
+	return res.NetBytes
+}
+
+// putToSleepRemote removes the service's remote replicas via their agents,
+// marks the service sleeping, and repoints the domain route at the wake
+// endpoint so inbound traffic brings it back.
+func putToSleepRemote(ctx context.Context, db *database.DB, q *sqlcdb.Queries, svc sleepCandidate, apiPort int) {
+	runner := newAgentNodeRunner(db)
+	for _, agentID := range remoteAgentsForService(ctx, db, svc.ID) {
+		if err := runner.ControlService(ctx, svc.ID.String(), agentID, "remove"); err != nil {
+			log.Printf("sleep: remote remove on %s failed: %v", agentID, err)
+			continue
+		}
+		_ = q.DeleteServiceContainersOnAgent(ctx, sqlcdb.DeleteServiceContainersOnAgentParams{
+			NodeAgentID: agentID,
+			ServiceID:   svc.ID.String(),
+		})
+	}
+	tracker.mu.Lock()
+	delete(tracker.activity, svc.ID)
+	tracker.mu.Unlock()
+	_, _ = db.Exec(`UPDATE services SET status = 'sleeping', updated_at = $1 WHERE id = $2`, time.Now(), svc.ID)
+	log.Printf("sleep: %s (%s) remote replicas removed after idle timeout", svc.Name, svc.ID)
+
+	var domain string
+	_ = db.QueryRow(`SELECT COALESCE(domain,'') FROM services WHERE id = $1`, svc.ID).Scan(&domain)
+	domains := serviceDomainNames(db, svc.ID, domain)
+	if len(domains) > 0 {
+		writeWakeIngress(svc.ID.String(), domains, apiPort)
+	}
+}
+
 // markIdle returns true when the network counter stopped growing past the
 // timeout. First sighting only sets the baseline — no idle without history.
 func markIdle(id uuid.UUID, bytes uint64, timeout time.Duration) bool {
@@ -191,9 +264,20 @@ func putToSleep(ctx context.Context, db *database.DB, dc *docker.Client, engine
 	}
 }
 
+// wakeCGIScript is installed as /cgi-bin/wake in the wake container. It
+// fires the wake callback on the first reachable candidate URL, in the
+// background, then serves the reloading placeholder page. Deliberately
+// single-quote-free — the file is written through printf '%s'.
+const wakeCGIScript = `#!/bin/sh
+for u in $WAKE_URLS; do wget -q -O /dev/null --timeout=20 "$u" && break; done >/dev/null 2>&1 &
+printf "Content-Type: text/html\r\n\r\n"
+printf "%s" "$WAKE_PAGE"
+`
+
 // spawnWakeContainer runs a busybox httpd holding the service's Traefik
-// host rule at higher priority. On boot it calls the wake endpoint, then
+// host rule at higher priority. Inbound hits redirect to /cgi-bin/wake,
-// keeps serving a reloading page until the next reconcile removes it.
+// which calls the internal wake endpoint and serves a reloading page
+// until the reconcile removes the placeholder.
 func spawnWakeContainer(ctx context.Context, db *database.DB, dc *docker.Client, engine *deployment.DeploymentEngine, svc sleepCandidate, domains []string, apiPort int) error {
 	edgeNet := ""
 	for _, n := range networkList(ctx, dc) {
@@ -223,19 +307,25 @@ func spawnWakeContainer(ctx context.Context, db *database.DB, dc *docker.Client,
 		"traefik.http.services." + router + ".loadbalancer.server.port": "80",
 	}
 
-	wakeURL := wakeEndpointURL(ctx, dc, apiPort, svc.ID, edgeNet)
+	wakeURLs := wakeEndpointURLs(ctx, dc, apiPort, svc.ID, edgeNet)
 	page := `<!doctype html><html><head><meta http-equiv="refresh" content="4"><title>Waking up</title>` +
 		`<style>body{font-family:system-ui,sans-serif;background:#0b0d12;color:#dde2ea;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}` +
 		`.card{text-align:center;max-width:34rem;padding:2rem}h1{font-size:1.25rem;font-weight:600}p{color:#98a2b3}</style></head>` +
 		`<body><div class="card"><h1>Service is waking up</h1><p>This Containr service was sleeping and is resuming now. The page reloads automatically.</p></div></body></html>`
-	// httpd without -f daemonizes, so the sequence is: write page, start
+	// The wake callback must fire when a request arrives, not at boot —
-	// httpd, fire the wake callback, then hold PID1 on sleep infinity.
+	// firing unconditionally makes the service flap sleep→wake forever.
+	// index.html redirects to /cgi-bin/wake; the CGI fires the callback
+	// (first reachable URL wins) and serves the reloading page.
+	indexPage := `<!doctype html><html><head><meta http-equiv="refresh" content="0;url=/cgi-bin/wake"></head><body></body></html>`
+	// httpd without -f daemonizes, so PID1 ends on sleep infinity. URLs
+	// and the page travel via env so the CGI script needs no quoting.
 	cmd := fmt.Sprintf(
-		`mkdir -p /www && printf '%%s' '%s' > /www/index.html && `+
+		`mkdir -p /www/cgi-bin && printf '%%s' '%s' > /www/index.html && `+
-			`httpd -p 80 -h /www && `+
+			`printf '%%s' '%s' > /www/cgi-bin/wake && chmod +x /www/cgi-bin/wake && `+
-			`(sleep 2; wget -q -O /dev/null --timeout=20 '%s' 2>/dev/null || true) && `+
+			`printf '%%s\n' 'E404:/cgi-bin/wake' > /www/httpd.conf && `+
-			`sleep infinity`,
+			`httpd -p 80 -h /www && sleep infinity`,
-		strings.ReplaceAll(page, "'", "'\\''"), wakeURL)
+		strings.ReplaceAll(indexPage, "'", "'\\''"),
+		strings.ReplaceAll(wakeCGIScript, "'", "'\\''"))
 
 	endpoints := map[string]*network.EndpointSettings{edgeNet: {}}
 	if ownNet := dc.OwnNetworkName(ctx); ownNet != "" && ownNet != edgeNet {
@@ -256,9 +346,13 @@ func spawnWakeContainer(ctx context.Context, db *database.DB, dc *docker.Client,
 	}
 
 	id, err := dc.CreateContainer(ctx, docker.ContainerConfig{
-		Name:     name,
+		Name:  name,
-		Image:    wakeImage,
+		Image: wakeImage,
-		Cmd:      []string{"sh", "-c", cmd},
+		Cmd:   []string{"sh", "-c", cmd},
+		Env: []string{
+			"WAKE_URLS=" + strings.Join(wakeURLs, " "),
+			"WAKE_PAGE=" + page,
+		},
 		Labels:   labels,
 		Networks: endpoints,
 	})
@@ -280,25 +374,41 @@ func networkList(ctx context.Context, dc *docker.Client) []string {
 	return names
 }
 
-// wakeEndpointURL builds the internal URL the wake container calls. The
+// wakeEndpointURLs builds ordered candidate URLs for the wake container to
-// edge network's gateway reaches the host's published API port; when the
+// call, deduplicated. No single address covers every topology: a containerized
-// API itself is containerized its own name resolves on the shared network.
+// API resolves by name on the shared network; Docker Desktop containers reach
-func wakeEndpointURL(ctx context.Context, dc *docker.Client, apiPort int, serviceID uuid.UUID, edgeNet string) string {
+// the host via host.docker.internal; on native Docker the edge network's
+// gateway routes to host-published ports. busybox wget walks the chain until
+// one answers.
+func wakeEndpointURLs(ctx context.Context, dc *docker.Client, apiPort int, serviceID uuid.UUID, edgeNet string) []string {
+	var hosts []string
 	if dc.OwnNetworkName(ctx) != "" {
 		if self, err := dc.GetContainer(ctx, selfID()); err == nil {
-			name := strings.TrimPrefix(self.Name, "/")
+			if name := strings.TrimPrefix(self.Name, "/"); name != "" {
-			if name != "" {
+				hosts = append(hosts, name)
-				return fmt.Sprintf("http://%s:%d/api/v1/internal/wake/%s", name, apiPort, serviceID)
 			}
 		}
 	}
+	hosts = append(hosts, "host.docker.internal")
 	if gw := networkGateway(ctx, dc, edgeNet); gw != "" {
-		return fmt.Sprintf("http://%s:%d/api/v1/internal/wake/%s", gw, apiPort, serviceID)
+		hosts = append(hosts, gw)
 	}
 	if probe := dc.HostProbeHost(ctx); probe != "" {
-		return fmt.Sprintf("http://%s:%d/api/v1/internal/wake/%s", probe, apiPort, serviceID)
+		hosts = append(hosts, probe)
 	}
-	return fmt.Sprintf("http://127.0.0.1:%d/api/v1/internal/wake/%s", apiPort, serviceID)
+	seen := map[string]bool{}
+	var urls []string
+	for _, h := range hosts {
+		if h == "" || seen[h] {
+			continue
+		}
+		seen[h] = true
+		urls = append(urls, fmt.Sprintf("http://%s:%d/api/v1/internal/wake/%s", h, apiPort, serviceID))
+	}
+	if len(urls) == 0 {
+		urls = append(urls, fmt.Sprintf("http://127.0.0.1:%d/api/v1/internal/wake/%s", apiPort, serviceID))
+	}
+	return urls
 }
 
 func networkGateway(ctx context.Context, dc *docker.Client, name string) string {
@@ -346,18 +456,40 @@ func pruneWakeContainers(ctx context.Context, db *database.DB, dc *docker.Client
 // idempotent and non-destructive, so no token is required; the endpoint
 // never mutates configuration.
 func handleServiceWake(c *gin.Context) {
+	code, body := triggerServiceWake(c)
+	if code != 0 {
+		c.JSON(code, body)
+	}
+}
+
+// handleServiceWakePage is the remote ingress wake target — Traefik routes
+// a sleeping remote service's domain here via the file provider. Every hit
+// (re)triggers the wake reconcile and returns a reloading page.
+func handleServiceWakePage(c *gin.Context) {
+	triggerServiceWake(c)
+	c.Header("Content-Type", "text/html; charset=utf-8")
+	c.String(http.StatusOK, wakePageHTML)
+}
+
+const wakePageHTML = `<!doctype html><html><head><meta http-equiv="refresh" content="4"><title>Waking up</title>` +
+	`<style>body{font-family:system-ui,sans-serif;background:#0b0d12;color:#dde2ea;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}` +
+	`.card{text-align:center;max-width:34rem;padding:2rem}h1{font-size:1.25rem;font-weight:600}p{color:#98a2b3}</style></head>` +
+	`<body><div class="card"><h1>Service is waking up</h1><p>This Containr service was sleeping and is resuming now. The page reloads automatically.</p></div></body></html>`
+
+// triggerServiceWake loads the service and reconciles it back to running
+// in the background. Returns (0, nil) when a response was already written
+// by an embedded handler path, else the JSON status to send.
+func triggerServiceWake(c *gin.Context) (int, gin.H) {
 	dbVal, _ := c.Get("db")
 	db := dbVal.(*database.DB)
 	engineVal, _ := c.Get("deployment_engine")
 	engine, _ := engineVal.(*deployment.DeploymentEngine)
 	if engine == nil {
-		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "deployment engine unavailable"})
+		return http.StatusServiceUnavailable, gin.H{"error": "deployment engine unavailable"}
-		return
 	}
 	id, err := uuid.Parse(c.Param("id"))
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid service id"})
+		return http.StatusBadRequest, gin.H{"error": "invalid service id"}
-		return
 	}
 	var service Service
 	err = db.QueryRow(
@@ -385,22 +517,23 @@ func handleServiceWake(c *gin.Context) {
 		&service.CreatedAt, &service.UpdatedAt,
 	)
 	if err != nil {
-		c.JSON(http.StatusNotFound, gin.H{"error": "service not found"})
+		return http.StatusNotFound, gin.H{"error": "service not found"}
-		return
 	}
 	if service.Status == "running" || service.Status == "deployed" {
-		c.JSON(http.StatusOK, gin.H{"status": service.Status})
+		return http.StatusOK, gin.H{"status": service.Status}
-		return
 	}
 	go func() {
 		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
 		defer cancel()
 		spec, err := serviceRuntimeSpec(db, service)
 		if err != nil {
+			log.Printf("wake: runtime spec for %s failed: %v", service.ID, err)
+			_, _ = db.Exec(`UPDATE services SET status = 'failed', updated_at = $1 WHERE id = $2`, time.Now(), service.ID)
 			return
 		}
 		state, err := engine.ReconcileService(ctx, spec)
 		if err != nil {
+			log.Printf("wake: reconcile for %s failed: %v", service.ID, err)
 			_, _ = db.Exec(`UPDATE services SET status = 'failed', updated_at = $1 WHERE id = $2`, time.Now(), service.ID)
 			return
 		}
@@ -411,7 +544,7 @@ func handleServiceWake(c *gin.Context) {
 		}
 		_, _ = db.Exec(`UPDATE services SET status = $1, updated_at = $2 WHERE id = $3`, status, time.Now(), service.ID)
 	}()
-	c.JSON(http.StatusAccepted, gin.H{"status": "waking"})
+	return http.StatusAccepted, gin.H{"status": "waking"}
 }
 
 // handleServiceSleep puts a service to sleep immediately (owner+ only).
@@ -438,7 +571,12 @@ func handleServiceSleep(c *gin.Context) {
 		Name:      service.Name,
 		Status:    service.Status,
 	}
-	go putToSleep(context.Background(), db, dc, engine, svc, apiPortFromContext(c))
+	q := sqlcdb.New(db.DB)
+	if len(remoteLiveContainers(c.Request.Context(), q, service.ID.String())) > 0 {
+		go putToSleepRemote(context.Background(), db, q, svc, apiPortFromContext(c))
+	} else {
+		go putToSleep(context.Background(), db, dc, engine, svc, apiPortFromContext(c))
+	}
 	c.JSON(http.StatusAccepted, gin.H{"status": "sleeping"})
 }
 

app/backend/internal/api/templategraph.go

@@ -11,6 +11,8 @@ import (
 	"log"
 	"math/big"
 	"net/http"
+	"os"
+	"path/filepath"
 	"regexp"
 	"sort"
 	"strconv"
@@ -22,6 +24,7 @@ import (
 	"containr/internal/deployment"
 	"containr/internal/deployqueue"
 	"containr/internal/secrets"
+	"containr/internal/source"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
@@ -227,7 +230,9 @@ func resolveStaticExpr(value string, userVars map[string]string, unresolved *[]s
 		if val, ok := userVars[key]; ok {
 			return val
 		}
-		if sub[2] != "" {
+		// {{VAR:-x}} supplies a default; {{VAR:-}} declares an explicitly
+		// empty one. Both resolve — only a bare {{VAR}} is unresolved.
+		if strings.Contains(m, ":-") {
 			return sub[2]
 		}
 		if unresolved != nil {
@@ -637,7 +642,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)
@@ -1112,6 +1117,130 @@ func handleImportCompose(c *gin.Context) {
 	})
 }
 
+// handleImportGitCompose fetches a compose file out of a git repository and
+// runs it through the same conversion as handleImportCompose. Works with any
+// git remote — connected providers (including GitHub App installs) supply
+// credentials for private repos. Nothing is persisted; the response feeds
+// the template create form or a direct deploy.
+func handleImportGitCompose(c *gin.Context) {
+	userID, ok := requireAuthenticatedUserID(c)
+	if !ok {
+		return
+	}
+	db := c.MustGet("db").(*database.DB)
+
+	var req struct {
+		Repo string `json:"repo" binding:"required"`
+		Path string `json:"path"`
+		Ref  string `json:"ref"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	branch, commit := "", ""
+	if ref := strings.TrimSpace(req.Ref); ref != "" {
+		if isCommitSHA(ref) {
+			commit = ref
+		} else {
+			branch = ref
+		}
+	}
+	spec, err := resolveGitCloneSpec(db, userID, req.Repo, branch, commit, "")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error(), "code": "VALIDATION"})
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Minute)
+	defer cancel()
+	checkoutRoot := filepath.Join(containrWorkDir, "repos", "import-"+uuid.NewString())
+	defer os.RemoveAll(checkoutRoot)
+	repoDir, err := source.Checkout(ctx, checkoutRoot, spec)
+	if err != nil {
+		c.JSON(http.StatusBadGateway, gin.H{"error": "git fetch failed: " + err.Error(), "code": "GIT_FETCH"})
+		return
+	}
+
+	// Default search order mirrors common compose conventions.
+	candidates := []string{req.Path}
+	if strings.TrimSpace(req.Path) == "" {
+		candidates = []string{"compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml"}
+	}
+	var raw []byte
+	for _, rel := range candidates {
+		p, rerr := resolveRepoFile(repoDir, rel)
+		if rerr != nil {
+			continue
+		}
+		raw, err = os.ReadFile(p)
+		if err == nil {
+			break
+		}
+	}
+	if raw == nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "compose file not found in repository", "code": "NOT_FOUND"})
+		return
+	}
+	if len(raw) > 512*1024 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Compose file exceeds 512 KiB"})
+		return
+	}
+
+	var file composeFileDef
+	if err := yaml.Unmarshal(raw, &file); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid compose YAML: " + err.Error()})
+		return
+	}
+	services, warnings, convErr := composeToSpecs(&file)
+	if convErr != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": convErr.Error()})
+		return
+	}
+	config := TemplateConfig{Version: 2, Services: services}
+	configJSON, _ := json.Marshal(config)
+	c.JSON(http.StatusOK, gin.H{
+		"config":    json.RawMessage(configJSON),
+		"variables": []TemplateVariable{},
+		"warnings":  warnings,
+	})
+}
+
+// resolveRepoFile maps a repo-relative file path onto the checkout and
+// rejects escapes — same containment rule as ResolveBuildPath, for files.
+func resolveRepoFile(checkoutDir, rel string) (string, error) {
+	rel = strings.TrimSpace(rel)
+	if rel == "" || filepath.IsAbs(rel) {
+		return "", fmt.Errorf("invalid repo path %q", rel)
+	}
+	clean := filepath.Clean(rel)
+	if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("path escapes the checkout: %q", rel)
+	}
+	resolved := filepath.Join(checkoutDir, clean)
+	info, err := os.Stat(resolved)
+	if err != nil {
+		return "", fmt.Errorf("path %q not found in checkout", rel)
+	}
+	if !info.Mode().IsRegular() {
+		return "", fmt.Errorf("path %q is not a file", rel)
+	}
+	return resolved, nil
+}
+
+func isCommitSHA(ref string) bool {
+	if len(ref) != 40 {
+		return false
+	}
+	for _, r := range ref {
+		if !('0' <= r && r <= '9') && !('a' <= r && r <= 'f') {
+			return false
+		}
+	}
+	return true
+}
+
 // composeToSpecs converts a parsed compose file into graph service specs.
 // Compose service names become keys; declaration order follows YAML document
 // order — yaml.v3 maps lose order, so sort keys for stability.

app/backend/internal/api/templategraph_compose_test.go

@@ -1,6 +1,8 @@
 package api
 
 import (
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -124,3 +126,42 @@ func TestComposeToSpecsWarnings(t *testing.T) {
 		t.Errorf("missing env warning: %v", warnings)
 	}
 }
+
+func TestResolveRepoFileContainment(t *testing.T) {
+	dir := t.TempDir()
+	inner := filepath.Join(dir, "sub")
+	if err := os.MkdirAll(inner, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(inner, "compose.yml"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	p, err := resolveRepoFile(dir, "sub/compose.yml")
+	if err != nil {
+		t.Fatalf("valid file rejected: %v", err)
+	}
+	if p != filepath.Join(dir, "sub", "compose.yml") {
+		t.Errorf("unexpected path %q", p)
+	}
+
+	for _, bad := range []string{"", "/etc/passwd", "../escape.yml", "..", "sub/../../out.yml"} {
+		if _, err := resolveRepoFile(dir, bad); err == nil {
+			t.Errorf("path %q should have been rejected", bad)
+		}
+	}
+	if _, err := resolveRepoFile(dir, "sub"); err == nil {
+		t.Error("directory accepted as file")
+	}
+}
+
+func TestIsCommitSHA(t *testing.T) {
+	if !isCommitSHA("0123456789abcdef0123456789abcdef01234567") {
+		t.Error("40-hex ref not recognised as a commit")
+	}
+	for _, bad := range []string{"main", "v1.2.3", "0123456789abcdef0123456789abcdef0123456", "0123456789abcdef0123456789abcdef0123456G"} {
+		if isCommitSHA(bad) {
+			t.Errorf("ref %q misclassified as commit SHA", bad)
+		}
+	}
+}

app/backend/internal/api/templateregistry.go

@@ -0,0 +1,186 @@
+package api
+
+// Template registry — CONTAINR_TEMPLATE_REGISTRY_URL points at another
+// Containr instance (or any server answering the same template shape):
+//   GET {base}/api/v1/templates     → {"templates": [ServiceTemplate…]}
+//   GET {base}/api/v1/templates/:id → {"template": …, "config": …, "variables": …}
+// Registry entries merge into the catalog as source:"registry"; deploying
+// one materializes it as a user template for the deployer first. The
+// bundled catalog always works offline — a dead registry never blocks it.
+
+import (
+	"containr/internal/database/sqlcdb"
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"encoding/json"
+	"net/http"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/sqlc-dev/pqtype"
+)
+
+const registryCacheTTL = 60 * time.Second
+
+var registryCache struct {
+	mu        sync.Mutex
+	fetchedAt time.Time
+	templates []ServiceTemplate
+}
+
+func registryBaseURL() string {
+	base := strings.TrimRight(strings.TrimSpace(os.Getenv("CONTAINR_TEMPLATE_REGISTRY_URL")), "/")
+	base = strings.TrimSuffix(base, "/api/v1")
+	return base
+}
+
+// fetchRegistryTemplates lists the remote catalog, cached for
+// registryCacheTTL. Failures degrade to an empty list — never fatal.
+func fetchRegistryTemplates(ctx context.Context) []ServiceTemplate {
+	if registryBaseURL() == "" {
+		return nil
+	}
+	registryCache.mu.Lock()
+	fresh := time.Since(registryCache.fetchedAt) < registryCacheTTL && registryCache.templates != nil
+	cached := registryCache.templates
+	registryCache.mu.Unlock()
+	if fresh {
+		return cached
+	}
+
+	var templates []ServiceTemplate
+	var payload struct {
+		Templates []ServiceTemplate `json:"templates"`
+	}
+	if err := registryGet(ctx, "/api/v1/templates", &payload); err == nil {
+		templates = payload.Templates
+	}
+	for i := range templates {
+		templates[i].Source = "registry"
+	}
+
+	registryCache.mu.Lock()
+	registryCache.fetchedAt = time.Now()
+	registryCache.templates = templates
+	registryCache.mu.Unlock()
+	return templates
+}
+
+// fetchRegistryTemplate fetches one remote template's full document
+// (template + config + variables). nil when the registry lacks it.
+func fetchRegistryTemplate(ctx context.Context, id string) *ServiceTemplate {
+	base := registryBaseURL()
+	if base == "" {
+		return nil
+	}
+	var payload struct {
+		Template  ServiceTemplate    `json:"template"`
+		Config    json.RawMessage    `json:"config"`
+		Variables []TemplateVariable `json:"variables"`
+	}
+	if err := registryGet(ctx, "/api/v1/templates/"+id, &payload); err != nil {
+		return nil
+	}
+	t := payload.Template
+	if t.ID == "" {
+		t.ID = id
+	}
+	t.Source = "registry"
+	// The detail endpoint returns config/variables decoded; store them back
+	// as raw JSON so they can persist unmodified into a local copy.
+	if len(payload.Config) > 0 {
+		t.Config = string(payload.Config)
+	}
+	if payload.Variables != nil {
+		if raw, err := json.Marshal(payload.Variables); err == nil {
+			t.Variables = string(raw)
+		}
+	}
+	return &t
+}
+
+func registryGet(ctx context.Context, path string, out interface{}) error {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, registryBaseURL()+path, nil)
+	if err != nil {
+		return err
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return errRegistry{resp.StatusCode}
+	}
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+type errRegistry struct{ status int }
+
+func (e errRegistry) Error() string { return "template registry status " + http.StatusText(e.status) }
+
+// respondRegistryTemplate answers GET /templates/:id for a registry-only
+// template with the same envelope shape as local templates.
+func respondRegistryTemplate(c *gin.Context, t *ServiceTemplate) {
+	config := json.RawMessage(t.Config)
+	if len(config) == 0 {
+		config = json.RawMessage(`{}`)
+	}
+	variables := json.RawMessage(t.Variables)
+	if len(variables) == 0 {
+		variables = json.RawMessage(`[]`)
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"template":  t,
+		"config":    config,
+		"variables": variables,
+	})
+}
+
+// materializeRegistryTemplate copies a registry template into the local
+// catalog as a private template owned by the deployer, so the normal
+// deploy path (and future re-deploys) work without the registry. The
+// local id is deterministic per (registry, template, user) so repeat
+// deploys reuse the same copy instead of accumulating duplicates.
+func materializeRegistryTemplate(c *gin.Context, q *sqlcdb.Queries, userID, templateID string) (sqlcdb.ServiceTemplate, error) {
+	ownerUUID, err := uuid.Parse(userID)
+	if err != nil {
+		return sqlcdb.ServiceTemplate{}, err
+	}
+	sum := sha256.Sum256([]byte(registryBaseURL() + "|" + templateID + "|" + userID))
+	localID := "reg-" + hex.EncodeToString(sum[:8])
+	if existing, err := q.GetServiceTemplateByID(c.Request.Context(), localID); err == nil {
+		return existing, nil
+	}
+
+	rt := fetchRegistryTemplate(c.Request.Context(), templateID)
+	if rt == nil {
+		return sqlcdb.ServiceTemplate{}, sql.ErrNoRows
+	}
+	variables := pqtype.NullRawMessage{}
+	if rt.Variables != "" {
+		variables = pqtype.NullRawMessage{RawMessage: json.RawMessage(rt.Variables), Valid: true}
+	}
+	if err := q.CreateUserTemplate(c.Request.Context(), sqlcdb.CreateUserTemplateParams{
+		ID:          localID,
+		Name:        rt.Name,
+		Description: nullableText(rt.Description),
+		Category:    rt.Category,
+		Logo:        nullableText(rt.Logo),
+		Config:      json.RawMessage(rt.Config),
+		Variables:   variables,
+		OwnerID:     uuid.NullUUID{UUID: ownerUUID, Valid: true},
+		IsPublic:    false,
+	}); err != nil {
+		return sqlcdb.ServiceTemplate{}, err
+	}
+	return q.GetServiceTemplateByID(c.Request.Context(), localID)
+}

app/backend/internal/api/templates.go

@@ -21,18 +21,20 @@ import (
 )
 
 type ServiceTemplate struct {
-	ID          string    `json:"id" db:"id"`
+	ID          string `json:"id" db:"id"`
-	Name        string    `json:"name" db:"name"`
+	Name        string `json:"name" db:"name"`
-	Description string    `json:"description" db:"description"`
+	Description string `json:"description" db:"description"`
-	Category    string    `json:"category" db:"category"`
+	Category    string `json:"category" db:"category"`
-	Logo        string    `json:"logo" db:"logo"`
+	Logo        string `json:"logo" db:"logo"`
-	Config      string    `json:"config" db:"config"`
+	Config      string `json:"config" db:"config"`
-	Variables   string    `json:"variables" db:"variables"`
+	Variables   string `json:"variables" db:"variables"`
-	IsOfficial  bool      `json:"is_official" db:"is_official"`
+	IsOfficial  bool   `json:"is_official" db:"is_official"`
-	OwnerID     string    `json:"owner_id,omitempty" db:"owner_id"`
+	OwnerID     string `json:"owner_id,omitempty" db:"owner_id"`
-	IsPublic    bool      `json:"is_public" db:"is_public"`
+	IsPublic    bool   `json:"is_public" db:"is_public"`
-	CreatedAt   time.Time `json:"created_at" db:"created_at"`
+	// Source marks catalog origin: "" (local/official) or "registry".
-	UpdatedAt   time.Time `json:"updated_at" db:"updated_at"`
+	Source    string    `json:"source,omitempty" db:"-"`
+	CreatedAt time.Time `json:"created_at" db:"created_at"`
+	UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
 }
 
 type TemplateConfig struct {
@@ -97,10 +99,24 @@ func handleGetTemplates(c *gin.Context) {
 	}
 
 	templates := make([]ServiceTemplate, 0, len(templateRows))
+	localIDs := make(map[string]bool, len(templateRows))
 	for _, row := range templateRows {
+		localIDs[row.ID] = true
 		templates = append(templates, mapSQLCTemplate(row))
 	}
 
+	// Merge the configured remote registry (CONTAINR_TEMPLATE_REGISTRY_URL).
+	// Registry ids never shadow local templates.
+	for _, t := range fetchRegistryTemplates(ctx) {
+		if localIDs[t.ID] {
+			continue
+		}
+		if category != "" && t.Category != category {
+			continue
+		}
+		templates = append(templates, t)
+	}
+
 	c.JSON(http.StatusOK, gin.H{"templates": templates})
 }
 
@@ -112,6 +128,11 @@ func handleGetTemplate(c *gin.Context) {
 	row, err := queries.GetServiceTemplateByID(c.Request.Context(), templateID)
 	if err != nil {
 		if errors.Is(err, sql.ErrNoRows) {
+			// Registry fallback — remote templates materialize read-only.
+			if rt := fetchRegistryTemplate(c.Request.Context(), templateID); rt != nil {
+				respondRegistryTemplate(c, rt)
+				return
+			}
 			c.JSON(http.StatusNotFound, gin.H{"error": "Template not found"})
 			return
 		}
@@ -190,11 +211,18 @@ func handleCreateFromTemplate(c *gin.Context) {
 	templateRow, err := queries.GetServiceTemplateByID(ctx, templateID)
 	if err != nil {
 		if errors.Is(err, sql.ErrNoRows) {
-			c.JSON(http.StatusNotFound, gin.H{"error": "Template not found"})
+			// Registry template — materialize a local copy for the
+			// deployer, then continue down the normal deploy path.
+			row, mErr := materializeRegistryTemplate(c, queries, userID, templateID)
+			if mErr != nil {
+				c.JSON(http.StatusNotFound, gin.H{"error": "Template not found"})
+				return
+			}
+			templateRow = row
+		} else {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to fetch template"})
 			return
 		}
-		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to fetch template"})
-		return
 	}
 
 	template := mapSQLCTemplate(templateRow)
@@ -1074,6 +1102,98 @@ func SeedTemplates() []ServiceTemplate {
 			Variables:  `[{"key":"APP_URL","label":"Public URL","default":"","required":false,"secret":false}]`,
 			IsOfficial: true,
 		},
+		{
+			ID:          "tpl-n8n",
+			Name:        "n8n + PostgreSQL + Redis",
+			Description: "Workflow automation in queue mode with managed PostgreSQL and Redis",
+			Category:    "stack",
+			Logo:        "https://cdn.simpleicons.org/n8n",
+			Config: `{"version":2,"services":[
+				{"key":"db","type":"database","runtime":"postgresql","environment":{"POSTGRES_DB":"n8n","POSTGRES_USER":"n8n"},"volumes":[{"source":"n8n-db","target":"/var/lib/postgresql/data"}]},
+				{"key":"redis","type":"database","runtime":"redis"},
+				{"key":"n8n","type":"web","runtime":"docker.n8n.io/n8nio/n8n:latest","port":5678,"health_check":"/healthz","depends_on":["db","redis"],
+				 "environment":{"DB_TYPE":"postgresdb","DB_POSTGRESDB_HOST":"{{service.db.host}}","DB_POSTGRESDB_PORT":"5432","DB_POSTGRESDB_DATABASE":"{{service.db.database}}","DB_POSTGRESDB_USER":"{{service.db.user}}","DB_POSTGRESDB_PASSWORD":"{{service.db.password}}","QUEUE_BULL_REDIS_HOST":"{{service.redis.host}}","QUEUE_BULL_REDIS_PASSWORD":"{{service.redis.password}}","EXECUTIONS_MODE":"queue","N8N_ENCRYPTION_KEY":"{{secret(32)}}","N8N_HOST":"{{APP_URL:-http://localhost:5678}}","N8N_EDITOR_BASE_URL":"{{APP_URL:-http://localhost:5678}}"},
+				 "volumes":[{"source":"n8n-data","target":"/home/node/.n8n"}]},
+				{"key":"worker","name":"n8n-worker","type":"worker","runtime":"docker.n8n.io/n8nio/n8n:latest","start_command":"worker","depends_on":["n8n","db","redis"],
+				 "environment":{"DB_TYPE":"postgresdb","DB_POSTGRESDB_HOST":"{{service.db.host}}","DB_POSTGRESDB_PORT":"5432","DB_POSTGRESDB_DATABASE":"{{service.db.database}}","DB_POSTGRESDB_USER":"{{service.db.user}}","DB_POSTGRESDB_PASSWORD":"{{service.db.password}}","QUEUE_BULL_REDIS_HOST":"{{service.redis.host}}","QUEUE_BULL_REDIS_PASSWORD":"{{service.redis.password}}","EXECUTIONS_MODE":"queue","N8N_ENCRYPTION_KEY":"{{secret(32)}}","QUEUE_HEALTH_CHECK_ACTIVE":"true"},
+				 "volumes":[{"source":"n8n-data","target":"/home/node/.n8n"}]}]}`,
+			Variables:  `[{"key":"APP_URL","label":"Public URL","default":"","required":false,"secret":false}]`,
+			IsOfficial: true,
+		},
+		{
+			ID:          "tpl-gitea",
+			Name:        "Gitea + PostgreSQL",
+			Description: "Self-hosted git service with managed PostgreSQL",
+			Category:    "stack",
+			Logo:        "https://cdn.simpleicons.org/gitea",
+			Config: `{"version":2,"services":[
+				{"key":"db","type":"database","runtime":"postgresql","environment":{"POSTGRES_DB":"gitea","POSTGRES_USER":"gitea"},"volumes":[{"source":"gitea-db","target":"/var/lib/postgresql/data"}]},
+				{"key":"gitea","type":"web","runtime":"gitea/gitea:latest","port":3000,"health_check":"/api/healthz","depends_on":["db"],
+				 "environment":{"GITEA__database__DB_TYPE":"postgres","GITEA__database__HOST":"{{service.db.host}}:{{service.db.port}}","GITEA__database__NAME":"{{service.db.database}}","GITEA__database__USER":"{{service.db.user}}","GITEA__database__PASSWD":"{{service.db.password}}","GITEA__security__INSTALL_LOCK":"true","GITEA__security__SECRET_KEY":"{{secret(32)}}","GITEA__security__INTERNAL_TOKEN":"{{secret(64)}}","GITEA__server__DOMAIN":"{{DOMAIN:-localhost}}","GITEA__server__ROOT_URL":"{{ROOT_URL:-http://localhost:3000}}","GITEA__server__SSH_PORT":"2222","USER_UID":"1000","USER_GID":"1000"},
+				 "volumes":[{"source":"gitea-data","target":"/data"}]}]}`,
+			Variables:  `[{"key":"DOMAIN","label":"Public domain","default":"","required":false,"secret":false},{"key":"ROOT_URL","label":"Root URL","default":"","required":false,"secret":false}]`,
+			IsOfficial: true,
+		},
+		{
+			ID:          "tpl-nextcloud",
+			Name:        "Nextcloud + PostgreSQL + Redis",
+			Description: "Self-hosted file sync and collaboration with managed PostgreSQL and Redis",
+			Category:    "stack",
+			Logo:        "https://cdn.simpleicons.org/nextcloud",
+			Config: `{"version":2,"services":[
+				{"key":"db","type":"database","runtime":"postgresql","environment":{"POSTGRES_DB":"nextcloud","POSTGRES_USER":"nextcloud"},"volumes":[{"source":"nextcloud-db","target":"/var/lib/postgresql/data"}]},
+				{"key":"redis","type":"database","runtime":"redis"},
+				{"key":"nextcloud","type":"web","runtime":"nextcloud:latest","port":80,"depends_on":["db","redis"],
+				 "environment":{"POSTGRES_HOST":"{{service.db.host}}","POSTGRES_DB":"{{service.db.database}}","POSTGRES_USER":"{{service.db.user}}","POSTGRES_PASSWORD":"{{service.db.password}}","REDIS_HOST":"{{service.redis.host}}","REDIS_HOST_PASSWORD":"{{service.redis.password}}","NEXTCLOUD_ADMIN_USER":"admin","NEXTCLOUD_ADMIN_PASSWORD":"{{secret(24)}}","NEXTCLOUD_TRUSTED_DOMAINS":"{{DOMAIN:-localhost}}","OVERWRITEHOST":"{{DOMAIN:-}}","OVERWRITEPROTOCOL":"https"},
+				 "volumes":[{"source":"nextcloud-data","target":"/var/www/html"}]}]}`,
+			Variables:  `[{"key":"DOMAIN","label":"Trusted domain","default":"localhost","required":false,"secret":false}]`,
+			IsOfficial: true,
+		},
+		{
+			ID:          "tpl-vaultwarden",
+			Name:        "Vaultwarden + PostgreSQL",
+			Description: "Bitwarden-compatible password manager with managed PostgreSQL",
+			Category:    "stack",
+			Logo:        "https://cdn.simpleicons.org/vaultwarden",
+			Config: `{"version":2,"services":[
+				{"key":"db","type":"database","runtime":"postgresql","environment":{"POSTGRES_DB":"vaultwarden","POSTGRES_USER":"vaultwarden"},"volumes":[{"source":"vaultwarden-db","target":"/var/lib/postgresql/data"}]},
+				{"key":"vaultwarden","type":"web","runtime":"vaultwarden/server:latest","port":80,"health_check":"/alive","depends_on":["db"],
+				 "environment":{"DATABASE_URL":"{{service.db.url}}","ADMIN_TOKEN":"{{secret(48)}}","DOMAIN":"{{DOMAIN:-http://localhost:80}}","SIGNUPS_ALLOWED":"false","WEBSOCKET_ENABLED":"true"},
+				 "volumes":[{"source":"vaultwarden-data","target":"/data"}]}]}`,
+			Variables:  `[{"key":"DOMAIN","label":"Public URL","default":"","required":false,"secret":false}]`,
+			IsOfficial: true,
+		},
+		{
+			ID:          "tpl-umami",
+			Name:        "Umami + PostgreSQL",
+			Description: "Lightweight privacy-first web analytics with managed PostgreSQL",
+			Category:    "stack",
+			Logo:        "https://cdn.simpleicons.org/umami",
+			Config: `{"version":2,"services":[
+				{"key":"db","type":"database","runtime":"postgresql","environment":{"POSTGRES_DB":"umami","POSTGRES_USER":"umami"},"volumes":[{"source":"umami-db","target":"/var/lib/postgresql/data"}]},
+				{"key":"umami","type":"web","runtime":"ghcr.io/umami-software/umami:postgresql-latest","port":3000,"depends_on":["db"],
+				 "environment":{"DATABASE_URL":"{{service.db.url}}","APP_SECRET":"{{secret(32)}}"}}]}`,
+			Variables:  `[]`,
+			IsOfficial: true,
+		},
+		{
+			ID:          "tpl-immich",
+			Name:        "Immich + PostgreSQL + Redis",
+			Description: "Self-hosted photo and video backup with managed PostgreSQL and Redis",
+			Category:    "stack",
+			Logo:        "https://cdn.simpleicons.org/immich",
+			Config: `{"version":2,"services":[
+				{"key":"db","type":"database","runtime":"postgresql","environment":{"POSTGRES_DB":"immich","POSTGRES_USER":"immich"},"volumes":[{"source":"immich-db","target":"/var/lib/postgresql/data"}]},
+				{"key":"redis","type":"database","runtime":"redis"},
+				{"key":"ml","name":"immich-machine-learning","type":"worker","runtime":"ghcr.io/immich-app/immich-machine-learning:release",
+				 "environment":{"DB_DATABASE_NAME":"{{service.db.database}}","DB_HOSTNAME":"{{service.db.host}}","DB_USERNAME":"{{service.db.user}}","DB_PASSWORD":"{{service.db.password}}","REDIS_HOSTNAME":"{{service.redis.host}}","REDIS_PASSWORD":"{{service.redis.password}}"},
+				 "volumes":[{"source":"immich-model-cache","target":"/cache"}]},
+				{"key":"immich","name":"immich-server","type":"web","runtime":"ghcr.io/immich-app/immich-server:release","port":2283,"health_check":"/api/server/ping","depends_on":["db","redis","ml"],
+				 "environment":{"DB_DATABASE_NAME":"{{service.db.database}}","DB_HOSTNAME":"{{service.db.host}}","DB_USERNAME":"{{service.db.user}}","DB_PASSWORD":"{{service.db.password}}","REDIS_HOSTNAME":"{{service.redis.host}}","REDIS_PASSWORD":"{{service.redis.password}}"},
+				 "volumes":[{"source":"immich-upload","target":"/usr/src/app/upload"}]}]}`,
+			Variables:  `[]`,
+			IsOfficial: true,
+		},
 	}
 	return templates
 }

app/backend/internal/api/templates_test.go

@@ -1,6 +1,9 @@
 package api
 
-import "testing"
+import (
+	"encoding/json"
+	"testing"
+)
 
 func TestNormalizeTemplateServiceType(t *testing.T) {
 	valid := []string{"web", "worker", "database", "cron"}
@@ -71,3 +74,32 @@ func TestResolveTemplateRuntimeImage(t *testing.T) {
 		t.Fatalf("expected unknown runtime passthrough, got %q", got)
 	}
 }
+
+func TestSeedTemplatesResolveCleanly(t *testing.T) {
+	for _, tpl := range SeedTemplates() {
+		var config TemplateConfig
+		if err := json.Unmarshal([]byte(tpl.Config), &config); err != nil {
+			t.Fatalf("%s: invalid config JSON: %v", tpl.ID, err)
+		}
+		var variables []TemplateVariable
+		if err := json.Unmarshal([]byte(tpl.Variables), &variables); err != nil {
+			t.Fatalf("%s: invalid variables JSON: %v", tpl.ID, err)
+		}
+		if len(config.Services) == 0 {
+			continue // legacy single-service template
+		}
+		sorted, err := topoSortServices(config.Services)
+		if err != nil {
+			t.Fatalf("%s: topo sort: %v", tpl.ID, err)
+		}
+		if err := validateTemplateGraph(sorted); err != nil {
+			t.Fatalf("%s: graph validation: %v", tpl.ID, err)
+		}
+		// User vars left empty — every expression must still resolve via
+		// defaults, secrets, or service refs.
+		graph := resolveTemplateGraph(sorted, map[string]string{})
+		if len(graph.unresolved) > 0 {
+			t.Fatalf("%s: unresolved expressions: %v", tpl.ID, graph.unresolved)
+		}
+	}
+}

app/backend/internal/api/terminal.go

@@ -0,0 +1,212 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"containr/internal/database"
+	"containr/internal/docker"
+
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"github.com/gorilla/websocket"
+)
+
+// Interactive terminal: a WebSocket bridged to a `docker exec` pty in the
+// service's container. Protocol is JSON text frames both ways:
+//   client → server: {"type":"stdin","data":"..."} | {"type":"resize","cols":N,"rows":N}
+//   server → client: {"type":"stdout","data":"..."} | {"type":"exit","code":N} | {"type":"error","message":"..."}
+// Shell preference: $SHELL, then bash, then sh.
+
+type terminalFrame struct {
+	Type    string `json:"type"`
+	Data    string `json:"data,omitempty"`
+	Cols    uint   `json:"cols,omitempty"`
+	Rows    uint   `json:"rows,omitempty"`
+	Code    int    `json:"code,omitempty"`
+	Message string `json:"message,omitempty"`
+}
+
+func handleServiceTerminal(c *gin.Context) {
+	db := c.MustGet("db").(*database.DB)
+	serviceID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		respondError(c, http.StatusBadRequest, "INVALID_ID", "invalid service id")
+		return
+	}
+	projectID, found := serviceProjectID(db, serviceID)
+	if !found {
+		respondError(c, http.StatusNotFound, "NOT_FOUND", "service not found")
+		return
+	}
+	if _, allowed := projectManageAccess(c, db, projectID); !allowed {
+		respondError(c, http.StatusNotFound, "NOT_FOUND", "service not found")
+		return
+	}
+	dockerClient, _ := c.Get("docker_client")
+	client, ok := dockerClient.(*docker.Client)
+	if !ok || client == nil {
+		respondError(c, http.StatusServiceUnavailable, "DOCKER_UNAVAILABLE", "Docker is not configured")
+		return
+	}
+
+	ctx := c.Request.Context()
+	containers, err := client.ListContainersFiltered(ctx, filters.NewArgs(
+		filters.Arg("label", "containr.service="+serviceID.String()),
+	), false)
+	if err != nil || len(containers) == 0 {
+		respondError(c, http.StatusConflict, "NO_CONTAINER", "service has no running container")
+		return
+	}
+	// Prefer a running container. With several matches, deterministically
+	// pick the first `containr-<service>-<n>` replica by name — that is the
+	// actual workload naming; auxiliary containers get ignored.
+	target := ""
+	sort.Slice(containers, func(i, j int) bool { return containers[i].Names[0] < containers[j].Names[0] })
+	for _, ctr := range containers {
+		if ctr.State == "running" && strings.HasPrefix(ctr.Names[0], "/containr-") {
+			target = ctr.ID
+			break
+		}
+	}
+	if target == "" {
+		for _, ctr := range containers {
+			if ctr.State == "running" {
+				target = ctr.ID
+				break
+			}
+		}
+	}
+	if target == "" {
+		target = containers[0].ID
+	}
+
+	conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		return
+	}
+	defer conn.Close()
+
+	send := func(f terminalFrame) bool {
+		return conn.WriteJSON(f) == nil
+	}
+
+	// Pick a shell that actually exists — distroless images may have none.
+	// `command -v` can't probe without a shell, so start each candidate and
+	// watch for the OCI "no such file" failure.
+	var stream types.HijackedResponse
+	var execID string
+	attached := false
+	for _, candidate := range []string{"/bin/bash", "/bin/sh", "sh"} {
+		exec, err := client.ExecCreate(ctx, target, docker.ExecConfig{
+			Cmd:          []string{candidate},
+			AttachStdin:  true,
+			AttachStdout: true,
+			AttachStderr: true,
+			Tty:          true,
+			Env:          []string{"TERM=xterm-256color", "COLORTERM=truecolor"},
+		})
+		if err != nil {
+			continue
+		}
+		s, err := client.ExecAttach(ctx, exec.ID)
+		if err != nil {
+			continue
+		}
+		if execStartFailed(ctx, client, exec.ID, s) {
+			s.Close()
+			continue
+		}
+		stream, execID, attached = s, exec.ID, true
+		break
+	}
+	if !attached {
+		send(terminalFrame{Type: "error", Message: "no shell available in this container image"})
+		return
+	}
+	defer stream.Close()
+
+	// The client sends a resize frame with its real size right after
+	// connecting; start at a sane default meanwhile.
+	_ = client.ExecResize(ctx, execID, 80, 24)
+
+	var wsWrite sync.Mutex
+	writeJSON := func(f terminalFrame) {
+		wsWrite.Lock()
+		defer wsWrite.Unlock()
+		_ = conn.WriteJSON(f)
+	}
+
+	// Container → client.
+	go func() {
+		buf := make([]byte, 8192)
+		for {
+			n, err := stream.Reader.Read(buf)
+			if n > 0 {
+				writeJSON(terminalFrame{Type: "stdout", Data: string(buf[:n])})
+			}
+			if err != nil {
+				if err != io.EOF {
+					log.Printf("terminal: exec stream ended: %v", err)
+				}
+				inspect, ierr := client.ExecInspect(context.Background(), execID)
+				code := 0
+				if ierr == nil {
+					code = inspect.ExitCode
+				}
+				writeJSON(terminalFrame{Type: "exit", Code: code})
+				_ = conn.WriteControl(websocket.CloseMessage,
+					websocket.FormatCloseMessage(websocket.CloseNormalClosure, "session ended"),
+					time.Now().Add(time.Second))
+				return
+			}
+		}
+	}()
+
+	// Client → container.
+	for {
+		_, raw, err := conn.ReadMessage()
+		if err != nil {
+			return
+		}
+		var f terminalFrame
+		if err := json.Unmarshal(raw, &f); err != nil {
+			continue
+		}
+		switch f.Type {
+		case "stdin":
+			if _, err := stream.Conn.Write([]byte(f.Data)); err != nil {
+				return
+			}
+		case "resize":
+			_ = client.ExecResize(ctx, execID, f.Cols, f.Rows)
+		case "ping":
+			writeJSON(terminalFrame{Type: "pong"})
+		}
+	}
+}
+
+// execStartFailed reports whether an attached exec failed to launch
+// (missing binary → non-zero exit, not running). The OCI failure takes a
+// moment to surface, so a short grace period elapses before judging.
+func execStartFailed(ctx context.Context, client *docker.Client, execID string, _ types.HijackedResponse) bool {
+	select {
+	case <-ctx.Done():
+		return true
+	case <-time.After(500 * time.Millisecond):
+	}
+	inspect, err := client.ExecInspect(ctx, execID)
+	if err != nil {
+		return false
+	}
+	return !inspect.Running && inspect.ExitCode != 0
+}

app/backend/internal/build/dockerfile.go

@@ -539,12 +539,16 @@ func createBuildContext(sourcePath, dockerfileContent string) (io.ReadCloser, er
 		return nil, err
 	}
 
-	// Add source files to tar
+	// Add source files to tar. The checkout's .git metadata is never build
+	// context — it bloats the tar and ships clone URLs to remote daemons.
 	err = filepath.Walk(sourcePath, func(file string, fi os.FileInfo, err error) error {
 		if err != nil {
 			return err
 		}
 		if fi.IsDir() {
+			if fi.Name() == ".git" {
+				return filepath.SkipDir
+			}
 			return nil
 		}
 

app/backend/internal/build/manager.go

@@ -3,6 +3,8 @@ package build
 import (
 	"context"
 	"fmt"
+	"io"
+	"os"
 	"path/filepath"
 	"time"
 
@@ -92,6 +94,75 @@ func (bm *BuildManager) Build(ctx context.Context, req *types.BuildRequest) (*ty
 	}
 }
 
+// PackageContext produces the same build-context tar Build would hand the
+// local daemon, without building it. Node agents download the tar and run
+// docker build themselves — the Dockerfile lands at the tar root.
+func (bm *BuildManager) PackageContext(ctx context.Context, req *types.BuildRequest) (io.ReadCloser, error) {
+	if req.BuildType == "" {
+		detectedType, err := bm.DetectBuildType(ctx, req.SourcePath)
+		if err != nil {
+			return nil, fmt.Errorf("failed to detect build type: %w", err)
+		}
+		req.BuildType = string(detectedType)
+	}
+
+	var dockerfileContent string
+	switch BuildType(req.BuildType) {
+	case BuildTypeDockerfile:
+		name, err := bm.dockerfileBuilder.DetectDockerfile(ctx, req.SourcePath)
+		if err != nil {
+			return nil, fmt.Errorf("failed to detect Dockerfile: %w", err)
+		}
+		path := filepath.Join(req.SourcePath, name)
+		if optimized, err := bm.dockerfileBuilder.OptimizeDockerfile(ctx, path); err == nil {
+			path = optimized
+		}
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read Dockerfile: %w", err)
+		}
+		dockerfileContent = string(data)
+	case BuildTypeRailpack:
+		if err := bm.railpackBuilder.DetectRailpack(ctx, req.SourcePath); err != nil {
+			return nil, fmt.Errorf("Railpack cannot build this project: %w", err)
+		}
+		content, err := bm.railpackBuilder.generateDockerfile(ctx, req.SourcePath, &RailpackConfig{
+			BuildCmd: req.BuildCommand,
+			StartCmd: req.StartCommand,
+			Env:      req.Environment,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to generate Dockerfile with Railpack: %w", err)
+		}
+		dockerfileContent = content
+	case BuildTypeNixpacks:
+		plan, err := bm.nixpacksBuilder.GeneratePlan(ctx, req.SourcePath, &NixpacksConfig{
+			BuildCmd: req.BuildCommand,
+			StartCmd: req.StartCommand,
+			Env:      req.Environment,
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to generate build plan: %w", err)
+		}
+		path, err := bm.nixpacksBuilder.generateDockerfile(plan)
+		if err != nil {
+			return nil, fmt.Errorf("failed to generate Dockerfile: %w", err)
+		}
+		defer os.Remove(path)
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read generated Dockerfile: %w", err)
+		}
+		dockerfileContent = string(data)
+	case BuildTypeStatic:
+		dockerfileContent = staticDockerfile
+	default:
+		return nil, fmt.Errorf("unsupported build type for remote packaging: %s", req.BuildType)
+	}
+
+	return createBuildContext(req.SourcePath, dockerfileContent)
+}
+
 // buildPrebuilt handles prebuilt image deployments
 func (bm *BuildManager) buildPrebuilt(ctx context.Context, req *types.BuildRequest) (*types.BuildResponse, error) {
 	if req.PrebuiltImage == "" {

app/backend/internal/build/nixpacks.go

@@ -476,17 +476,22 @@ func (n *NixpacksBuilder) Build(ctx context.Context, req *types.BuildRequest) (*
 	}
 
 	// Create temporary Dockerfile
-	dockerfile, err := n.generateDockerfile(plan)
+	dockerfilePath, err := n.generateDockerfile(plan)
 	if err != nil {
 		return nil, fmt.Errorf("failed to generate Dockerfile: %w", err)
 	}
-	defer os.Remove(dockerfile)
+	defer os.Remove(dockerfilePath)
 
 	// Build Docker image
 	imageName := fmt.Sprintf("%s:%s", req.ImageName, req.ImageTag)
 
-	// Create build context tar
+	// Create build context tar — createBuildContext takes the Dockerfile
-	buildCtx, err := createBuildContext(req.SourcePath, dockerfile)
+	// contents, not its path.
+	dockerfileData, err := os.ReadFile(dockerfilePath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to read generated Dockerfile: %w", err)
+	}
+	buildCtx, err := createBuildContext(req.SourcePath, string(dockerfileData))
 	if err != nil {
 		return nil, fmt.Errorf("failed to create build context: %w", err)
 	}

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

@@ -0,0 +1,104 @@
+package commands
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/gorilla/websocket"
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+)
+
+// ShellCmd opens an interactive shell inside a service's running container.
+var ShellCmd = &cobra.Command{
+	Use:   "shell <service-id>",
+	Short: "Interactive shell inside the service container",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		serviceID := args[0]
+		cli, err := client()
+		if err != nil {
+			return err
+		}
+		base := strings.TrimRight(cli.BaseURL, "/")
+		wsURL := strings.Replace(base, "http", "ws", 1) + "/services/" + serviceID + "/terminal"
+
+		header := http.Header{}
+		header.Set("Authorization", "Bearer "+cli.Token)
+		conn, _, err := websocket.DefaultDialer.Dial(wsURL, header)
+		if err != nil {
+			return fmt.Errorf("terminal: %w", err)
+		}
+		defer conn.Close()
+
+		fd := int(os.Stdin.Fd())
+		raw := term.IsTerminal(fd)
+		var oldState *term.State
+		if raw {
+			oldState, err = term.MakeRaw(fd)
+			if err == nil {
+				defer term.Restore(fd, oldState)
+			}
+			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{})
+		// stdin → ws
+		go func() {
+			buf := make([]byte, 4096)
+			for {
+				n, err := os.Stdin.Read(buf)
+				if n > 0 {
+					if werr := conn.WriteJSON(map[string]interface{}{
+						"type": "stdin", "data": string(buf[:n]),
+					}); werr != nil {
+						return
+					}
+				}
+				if err != nil {
+					return
+				}
+			}
+		}()
+		// ws → stdout
+		go func() {
+			defer close(done)
+			for {
+				var frame struct {
+					Type    string `json:"type"`
+					Data    string `json:"data"`
+					Code    int    `json:"code"`
+					Message string `json:"message"`
+				}
+				if err := conn.ReadJSON(&frame); err != nil {
+					return
+				}
+				switch frame.Type {
+				case "stdout":
+					_, _ = os.Stdout.WriteString(frame.Data)
+				case "exit":
+					fmt.Fprintf(os.Stderr, "\r\n[session ended — exit %d]\r\n", frame.Code)
+					return
+				case "error":
+					fmt.Fprintf(os.Stderr, "\r\nerror: %s\r\n", frame.Message)
+					return
+				}
+			}
+		}()
+
+		select {
+		case <-done:
+		case <-time.After(24 * time.Hour):
+		}
+		return nil
+	},
+}

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

@@ -2,6 +2,7 @@ package commands
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/spf13/cobra"
 )
@@ -81,6 +82,161 @@ var nodesDeleteCmd = &cobra.Command{
 	},
 }
 
+var nodesUpdateCmd = &cobra.Command{
+	Use:   "update <id>",
+	Short: "Update a node agent (--name, --auto-prune, --tags)",
+	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 cmd.Flags().Changed("tags") {
+			raw, _ := cmd.Flags().GetString("tags")
+			tags := []string{}
+			for _, t := range strings.Split(raw, ",") {
+				if t = strings.TrimSpace(t); t != "" {
+					tags = append(tags, t)
+				}
+			}
+			body["tags"] = tags
+		}
+		if len(body) == 0 {
+			return &APIError{Message: "nothing to update — pass --name, --auto-prune or --tags", 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 nodesUpgradeCmd = &cobra.Command{
+	Use:   "upgrade <id>",
+	Short: "Upgrade the node agent to the server's bundled binary",
+	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]+"/upgrade", 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 +301,11 @@ 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")
+	nodesUpdateCmd.Flags().String("tags", "", "comma-separated placement tags (services with placement_tags only schedule onto matching nodes)")
+	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, nodesUpgradeCmd, 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
 			}
@@ -112,6 +114,26 @@ var servicesCreateCmd = &cobra.Command{
 		if v, _ := cmd.Flags().GetInt("replicas"); v > 0 {
 			body["replicas"] = v
 		}
+		if v, _ := cmd.Flags().GetBool("spread"); v {
+			body["spread"] = v
+		}
+		if cmd.Flags().Changed("sleep") {
+			v, _ := cmd.Flags().GetBool("sleep")
+			body["sleep_enabled"] = v
+		}
+		if cmd.Flags().Changed("sleep-idle") {
+			v, _ := cmd.Flags().GetInt("sleep-idle")
+			body["sleep_idle_minutes"] = v
+		}
+		if v, _ := cmd.Flags().GetString("placement-tags"); v != "" {
+			tags := []string{}
+			for _, t := range strings.Split(v, ",") {
+				if t = strings.TrimSpace(t); t != "" {
+					tags = append(tags, t)
+				}
+			}
+			body["placement_tags"] = tags
+		}
 		data, err := c.Do("POST", "/projects/"+args[0]+"/services", body)
 		if err != nil {
 			return err
@@ -159,7 +181,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 +197,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
@@ -199,6 +223,20 @@ var servicesUpdateCmd = &cobra.Command{
 			v, _ := cmd.Flags().GetBool("sleep")
 			body["sleep_enabled"] = v
 		}
+		if cmd.Flags().Changed("spread") {
+			v, _ := cmd.Flags().GetBool("spread")
+			body["spread"] = v
+		}
+		if cmd.Flags().Changed("placement-tags") {
+			v, _ := cmd.Flags().GetString("placement-tags")
+			tags := []string{}
+			for _, t := range strings.Split(v, ",") {
+				if t = strings.TrimSpace(t); t != "" {
+					tags = append(tags, t)
+				}
+			}
+			body["placement_tags"] = tags
+		}
 		if cmd.Flags().Changed("sleep-idle") {
 			v, _ := cmd.Flags().GetInt("sleep-idle")
 			body["sleep_idle_minutes"] = v
@@ -490,6 +528,11 @@ 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")
+	f.Bool("spread", false, "distribute replicas across all online schedulable nodes")
+	f.Bool("sleep", false, "enable scale-to-zero on idle (sleep mode)")
+	f.Int("sleep-idle", 0, "idle minutes before sleeping (1-1440)")
+	f.String("placement-tags", "", "comma-separated node tags required for remote placement (auto/spread only)")
 
 	uf := servicesUpdateCmd.Flags()
 	uf.String("name", "", "service name")
@@ -514,6 +557,9 @@ 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")
+	uf.Bool("spread", false, "spread replicas across all online schedulable nodes (--spread=false to disable)")
+	uf.String("placement-tags", "", "comma-separated node tags required for remote placement (empty clears)")
 
 	for _, a := range []string{"start", "stop", "restart", "redeploy", "sleep", "wake"} {
 		verb := a

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

@@ -194,6 +194,32 @@ var templatesImportComposeCmd = &cobra.Command{
 	},
 }
 
+var templatesImportGitCmd = &cobra.Command{
+	Use:   "import-git <repo> [path]",
+	Short: "Fetch a compose file from a git repo and convert it into a template graph config",
+	Long:  "repo accepts a clone URL, ssh remote, or owner/repo shorthand resolved via connected git providers (private repos included). path defaults to compose.yaml/yml or docker-compose.yml/yaml. --ref selects a branch or commit.",
+	Args:  cobra.RangeArgs(1, 2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		body := map[string]string{"repo": args[0]}
+		if len(args) > 1 {
+			body["path"] = args[1]
+		}
+		if v, _ := cmd.Flags().GetString("ref"); v != "" {
+			body["ref"] = v
+		}
+		c, err := client()
+		if err != nil {
+			return err
+		}
+		data, err := c.Do("POST", "/templates/import/git", body)
+		if err != nil {
+			return err
+		}
+		PrintRaw(data)
+		return nil
+	},
+}
+
 var templatesDeployGraphCmd = &cobra.Command{
 	Use:   "deploy-graph <project-id> <config.json|->",
 	Short: "Deploy an ad-hoc service graph (v2 config with services[]) without a stored template",
@@ -257,5 +283,6 @@ func init() {
 	templatesDeployCmd.Flags().StringArrayVar(&tplDeployVars, "var", nil, "Template variable override (KEY=VALUE, repeatable)")
 	templatesPlanCmd.Flags().StringArrayVar(&tplDeployVars, "var", nil, "Template variable override (KEY=VALUE, repeatable)")
 	templatesDeployGraphCmd.Flags().StringArrayVar(&tplDeployVars, "var", nil, "Template variable override (KEY=VALUE, repeatable)")
-	TemplatesCmd.AddCommand(templatesListCmd, templatesGetCmd, templatesCreateCmd, templatesDeleteCmd, templatesDeployCmd, templatesPlanCmd, templatesImportComposeCmd, templatesDeployGraphCmd)
+	templatesImportGitCmd.Flags().String("ref", "", "git branch or commit (default: remote HEAD)")
+	TemplatesCmd.AddCommand(templatesListCmd, templatesGetCmd, templatesCreateCmd, templatesDeleteCmd, templatesDeployCmd, templatesPlanCmd, templatesImportComposeCmd, templatesImportGitCmd, templatesDeployGraphCmd)
 }

app/backend/internal/cli/root.go

@@ -90,9 +90,11 @@ func init() {
 	rootCmd.AddCommand(commands.WebhooksCmd)
 	rootCmd.AddCommand(commands.OperationsCmd)
 	rootCmd.AddCommand(commands.ActivityCmd)
+	rootCmd.AddCommand(commands.ShellCmd)
 	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, tags
 `
 
 type CreateAgentParams struct {
@@ -109,6 +121,9 @@ func (q *Queries) CreateAgent(ctx context.Context, arg CreateAgentParams) (NodeA
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
+		&i.Tags,
 	)
 	return i, err
 }
@@ -228,8 +243,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, tags FROM node_agents WHERE id = $1
 `
 
 func (q *Queries) GetAgent(ctx context.Context, id string) (NodeAgent, error) {
@@ -249,12 +278,15 @@ func (q *Queries) GetAgent(ctx context.Context, id string) (NodeAgent, error) {
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
+		&i.Tags,
 	)
 	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, tags FROM node_agents
 WHERE hostname = $1 AND ip_address = $2
 LIMIT 1
 `
@@ -281,6 +313,9 @@ func (q *Queries) GetAgentByHostAndIP(ctx context.Context, arg GetAgentByHostAnd
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
+		&i.Tags,
 	)
 	return i, err
 }
@@ -378,6 +413,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 +523,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, tags FROM node_agents ORDER BY created_at ASC
 `
 
 func (q *Queries) ListAgents(ctx context.Context) ([]NodeAgent, error) {
@@ -484,6 +549,9 @@ func (q *Queries) ListAgents(ctx context.Context) ([]NodeAgent, error) {
 			&i.CreatedAt,
 			&i.UpdatedAt,
 			&i.Metadata,
+			&i.AutoPrune,
+			&i.Schedulable,
+			&i.Tags,
 		); err != nil {
 			return nil, err
 		}
@@ -627,6 +695,249 @@ func (q *Queries) ListPendingCommands(ctx context.Context, nodeAgentID string) (
 	return items, nil
 }
 
+const listSchedulableAgents = `-- name: ListSchedulableAgents :many
+SELECT id, name FROM node_agents
+WHERE status = 'online' AND schedulable
+ORDER BY id
+`
+
+type ListSchedulableAgentsRow struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+func (q *Queries) ListSchedulableAgents(ctx context.Context) ([]ListSchedulableAgentsRow, error) {
+	rows, err := q.db.QueryContext(ctx, listSchedulableAgents)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListSchedulableAgentsRow{}
+	for rows.Next() {
+		var i ListSchedulableAgentsRow
+		if err := rows.Scan(&i.ID, &i.Name); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listSchedulableAgentsMatching = `-- name: ListSchedulableAgentsMatching :many
+SELECT id, name FROM node_agents
+WHERE status = 'online' AND schedulable
+  AND tags @> $1::jsonb
+ORDER BY id
+`
+
+type ListSchedulableAgentsMatchingRow struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+}
+
+// Only agents carrying every required placement tag (jsonb array containment).
+func (q *Queries) ListSchedulableAgentsMatching(ctx context.Context, dollar_1 json.RawMessage) ([]ListSchedulableAgentsMatchingRow, error) {
+	rows, err := q.db.QueryContext(ctx, listSchedulableAgentsMatching, dollar_1)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListSchedulableAgentsMatchingRow{}
+	for rows.Next() {
+		var i ListSchedulableAgentsMatchingRow
+		if err := rows.Scan(&i.ID, &i.Name); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listServiceAgents = `-- name: ListServiceAgents :many
+SELECT DISTINCT node_agent_id FROM container_instances WHERE service_id = $1
+`
+
+// Distinct agents holding inventory rows for a service.
+func (q *Queries) ListServiceAgents(ctx context.Context, serviceID string) ([]string, error) {
+	rows, err := q.db.QueryContext(ctx, listServiceAgents, serviceID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []string{}
+	for rows.Next() {
+		var node_agent_id string
+		if err := rows.Scan(&node_agent_id); err != nil {
+			return nil, err
+		}
+		items = append(items, node_agent_id)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listServiceContainers = `-- name: ListServiceContainers :many
+SELECT id, name, node_agent_id, status, ports, resources FROM container_instances
+WHERE service_id = $1
+`
+
+type ListServiceContainersRow struct {
+	ID          string                `json:"id"`
+	Name        string                `json:"name"`
+	NodeAgentID string                `json:"node_agent_id"`
+	Status      pqtype.NullRawMessage `json:"status"`
+	Ports       pqtype.NullRawMessage `json:"ports"`
+	Resources   pqtype.NullRawMessage `json:"resources"`
+}
+
+func (q *Queries) ListServiceContainers(ctx context.Context, serviceID string) ([]ListServiceContainersRow, error) {
+	rows, err := q.db.QueryContext(ctx, listServiceContainers, serviceID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := []ListServiceContainersRow{}
+	for rows.Next() {
+		var i ListServiceContainersRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.Name,
+			&i.NodeAgentID,
+			&i.Status,
+			&i.Ports,
+			&i.Resources,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Close(); err != nil {
+		return nil, err
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	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(
+        (a.resources->'memory'->>'used')::double precision
+        / NULLIF((a.resources->'memory'->>'total')::double precision, 0),
+        1.0
+    ) ASC,
+    COALESCE((a.resources->'cpu'->>'usage')::double precision, 100.0) ASC,
+    COALESCE(h.container_count, 0) ASC,
+    a.created_at ASC
+LIMIT 1
+`
+
+// Resource-aware: lowest memory utilisation first, then cpu, then container
+// count. Agents without telemetry sort last (NULL → worst score).
+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 pickLeastLoadedAgentMatching = `-- name: PickLeastLoadedAgentMatching :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
+  AND a.tags @> $1::jsonb
+ORDER BY
+    COALESCE(
+        (a.resources->'memory'->>'used')::double precision
+        / NULLIF((a.resources->'memory'->>'total')::double precision, 0),
+        1.0
+    ) ASC,
+    COALESCE((a.resources->'cpu'->>'usage')::double precision, 100.0) ASC,
+    COALESCE(h.container_count, 0) ASC,
+    a.created_at ASC
+LIMIT 1
+`
+
+// Same resource-aware ordering as PickLeastLoadedAgent, restricted to agents
+// carrying every required placement tag.
+func (q *Queries) PickLeastLoadedAgentMatching(ctx context.Context, dollar_1 json.RawMessage) (string, error) {
+	row := q.db.QueryRowContext(ctx, pickLeastLoadedAgentMatching, dollar_1)
+	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 setAgentTags = `-- name: SetAgentTags :exec
+UPDATE node_agents SET tags = $2::jsonb, updated_at = NOW() WHERE id = $1
+`
+
+type SetAgentTagsParams struct {
+	ID      string          `json:"id"`
+	Column2 json.RawMessage `json:"column_2"`
+}
+
+func (q *Queries) SetAgentTags(ctx context.Context, arg SetAgentTagsParams) error {
+	_, err := q.db.ExecContext(ctx, setAgentTags, arg.ID, arg.Column2)
+	return err
+}
+
 const updateAgent = `-- name: UpdateAgent :one
 UPDATE node_agents SET
     name = $2,
@@ -639,9 +950,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, tags
 `
 
 type UpdateAgentParams struct {
@@ -656,6 +969,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 +986,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 +1004,9 @@ func (q *Queries) UpdateAgent(ctx context.Context, arg UpdateAgentParams) (NodeA
 		&i.CreatedAt,
 		&i.UpdatedAt,
 		&i.Metadata,
+		&i.AutoPrune,
+		&i.Schedulable,
+		&i.Tags,
 	)
 	return i, err
 }
@@ -717,6 +1037,53 @@ func (q *Queries) UpdateAgentHeartbeat(ctx context.Context, arg UpdateAgentHeart
 	return err
 }
 
+const updateContainerPorts = `-- name: UpdateContainerPorts :exec
+UPDATE container_instances SET status = $2, ports = $3, updated_at = NOW()
+WHERE id = $1
+`
+
+type UpdateContainerPortsParams struct {
+	ID     string                `json:"id"`
+	Status pqtype.NullRawMessage `json:"status"`
+	Ports  pqtype.NullRawMessage `json:"ports"`
+}
+
+// Agent reports the real host bindings after create — persist them with
+// the status flip so ingress can route to the assigned port.
+func (q *Queries) UpdateContainerPorts(ctx context.Context, arg UpdateContainerPortsParams) error {
+	_, err := q.db.ExecContext(ctx, updateContainerPorts, arg.ID, arg.Status, arg.Ports)
+	return err
+}
+
+const updateContainerStateByName = `-- name: UpdateContainerStateByName :exec
+UPDATE container_instances SET
+    status = jsonb_set(status, '{state}', $3::jsonb),
+    resources = jsonb_set(COALESCE(resources, '{}'::jsonb), '{net_bytes}', $4::jsonb),
+    updated_at = NOW()
+WHERE name = $1 AND node_agent_id = $2
+  AND status->>'state' IS DISTINCT FROM 'removed'
+`
+
+type UpdateContainerStateByNameParams struct {
+	Name        string          `json:"name"`
+	NodeAgentID string          `json:"node_agent_id"`
+	Column3     json.RawMessage `json:"column_3"`
+	Column4     json.RawMessage `json:"column_4"`
+}
+
+// Agent heartbeat reports real docker state + net counters; reconcile
+// inventory for rows this node owns. Tombstones win — never resurrect a
+// removed replica. $4 is the cumulative rx+tx byte counter.
+func (q *Queries) UpdateContainerStateByName(ctx context.Context, arg UpdateContainerStateByNameParams) error {
+	_, err := q.db.ExecContext(ctx, updateContainerStateByName,
+		arg.Name,
+		arg.NodeAgentID,
+		arg.Column3,
+		arg.Column4,
+	)
+	return err
+}
+
 const updateContainerStatus = `-- name: UpdateContainerStatus :exec
 UPDATE container_instances SET status = $2, updated_at = NOW()
 WHERE id = $1
@@ -731,3 +1098,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,9 @@ 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"`
+	Tags          json.RawMessage       `json:"tags"`
 }
 
 type Notification struct {
@@ -273,6 +276,9 @@ 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"`
+	Spread          bool            `json:"spread"`
+	PlacementTags   json.RawMessage `json:"placement_tags"`
 }
 
 type ServiceDomain struct {

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

@@ -7,11 +7,13 @@ package sqlcdb
 import (
 	"context"
 	"database/sql"
+	"encoding/json"
 
 	"github.com/google/uuid"
 )
 
 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 +45,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 +61,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)
@@ -91,6 +95,12 @@ type Querier interface {
 	// display, when the caller owns or is a member of it, or when the caller is a
 	// platform admin. Anonymous callers pass user_id = uuid.Nil, is_admin = false.
 	ListProjectsWithStatsByUser(ctx context.Context, arg ListProjectsWithStatsByUserParams) ([]ListProjectsWithStatsByUserRow, error)
+	ListSchedulableAgents(ctx context.Context) ([]ListSchedulableAgentsRow, error)
+	// Only agents carrying every required placement tag (jsonb array containment).
+	ListSchedulableAgentsMatching(ctx context.Context, dollar_1 json.RawMessage) ([]ListSchedulableAgentsMatchingRow, error)
+	// Distinct agents holding inventory rows for a service.
+	ListServiceAgents(ctx context.Context, serviceID string) ([]string, error)
+	ListServiceContainers(ctx context.Context, serviceID string) ([]ListServiceContainersRow, error)
 	ListServiceTemplatesByCategoryForUser(ctx context.Context, arg ListServiceTemplatesByCategoryForUserParams) ([]ServiceTemplate, error)
 	ListServiceTemplatesForUser(ctx context.Context, ownerID uuid.NullUUID) ([]ServiceTemplate, error)
 	ListUserInvites(ctx context.Context) ([]UserInvite, error)
@@ -99,8 +109,17 @@ type Querier interface {
 	MarkAllNotificationsReadByUser(ctx context.Context, arg MarkAllNotificationsReadByUserParams) error
 	MarkNotificationReadByIDAndUser(ctx context.Context, arg MarkNotificationReadByIDAndUserParams) error
 	MarkUserInviteUsed(ctx context.Context, arg MarkUserInviteUsedParams) error
+	// Resource-aware: lowest memory utilisation first, then cpu, then container
+	// count. Agents without telemetry sort last (NULL → worst score).
+	PickLeastLoadedAgent(ctx context.Context) (string, error)
+	// Same resource-aware ordering as PickLeastLoadedAgent, restricted to agents
+	// carrying every required placement tag.
+	PickLeastLoadedAgentMatching(ctx context.Context, dollar_1 json.RawMessage) (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
+	SetAgentTags(ctx context.Context, arg SetAgentTagsParams) error
 	SetDatabaseBackupRemoteKeyByID(ctx context.Context, arg SetDatabaseBackupRemoteKeyByIDParams) error
 	SetDatabaseBackupScheduleByIDAndUser(ctx context.Context, arg SetDatabaseBackupScheduleByIDAndUserParams) error
 	SetDatabaseBackupStatusByID(ctx context.Context, arg SetDatabaseBackupStatusByIDParams) error
@@ -117,6 +136,13 @@ type Querier interface {
 	UpdateAgentHeartbeat(ctx context.Context, arg UpdateAgentHeartbeatParams) error
 	UpdateBackupTargetByIDAndUser(ctx context.Context, arg UpdateBackupTargetByIDAndUserParams) error
 	UpdateBanner(ctx context.Context, arg UpdateBannerParams) (Banner, error)
+	// Agent reports the real host bindings after create — persist them with
+	// the status flip so ingress can route to the assigned port.
+	UpdateContainerPorts(ctx context.Context, arg UpdateContainerPortsParams) error
+	// Agent heartbeat reports real docker state + net counters; reconcile
+	// inventory for rows this node owns. Tombstones win — never resurrect a
+	// removed replica. $4 is the cumulative rx+tx byte counter.
+	UpdateContainerStateByName(ctx context.Context, arg UpdateContainerStateByNameParams) error
 	UpdateContainerStatus(ctx context.Context, arg UpdateContainerStatusParams) error
 	UpdateDatabaseServiceNameAndPlanByIDAndUser(ctx context.Context, arg UpdateDatabaseServiceNameAndPlanByIDAndUserParams) error
 	UpdateDatabaseServiceNameByIDAndUser(ctx context.Context, arg UpdateDatabaseServiceNameByIDAndUserParams) error
@@ -126,6 +152,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,37 @@ 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)
+	// ReconcileSpread distributes the service's replicas across every online,
+	// schedulable agent — replica i lands on agents[i % len].
+	ReconcileSpread(ctx context.Context, spec RuntimeSpec) (*RuntimeState, error)
+	// ReconcileAuto picks the least-loaded online agent carrying every tag in
+	// spec.PlacementTags and reconciles all replicas onto it. Re-resolved on
+	// every reconcile — the service follows the tag, not a stored node.
+	ReconcileAuto(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
+	// RemoteRuntimeState reads the service's remote replicas from inventory
+	// across all agents. nil/empty means nothing runs remotely.
+	RemoteRuntimeState(ctx context.Context, serviceID string) (*RuntimeState, error)
+	// RetireService removes every remote replica of the service across all
+	// agents — used when a service returns to local placement.
+	RetireService(ctx context.Context, serviceID string) error
+}
+
 type DeploymentEngine struct {
 	buildManager  *build.BuildManager
 	dockerClient  *docker.Client
 	scheduler     *Scheduler
+	nodeRunner    NodeRunner
 	deployments   map[string]*Deployment
 	deploymentLog chan *DeploymentEvent
 }
@@ -67,6 +94,30 @@ 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.
+	NodeID string `json:"node_id,omitempty"`
+	// Spread distributes replicas across every online, schedulable agent.
+	Spread bool `json:"spread,omitempty"`
+	// RemoteBuild, when set, makes each target node docker-build the image
+	// itself from a packaged context artifact instead of pulling a registry
+	// tag. The image name comes from the deployment, not the spec.
+	RemoteBuild *RemoteBuildSpec `json:"remote_build,omitempty"`
+	// RemoteLoad ships a docker-save tarball to each target node — used for
+	// rollbacks of locally-built tags that no registry can serve.
+	RemoteLoad *RemoteLoadSpec `json:"remote_load,omitempty"`
+}
+
+// RemoteBuildSpec is the agent-side docker build request.
+type RemoteBuildSpec struct {
+	ArtifactID string            `json:"artifact_id"`
+	BuildArgs  map[string]string `json:"build_args,omitempty"`
+	NoCache    bool              `json:"no_cache,omitempty"`
+}
+
+// RemoteLoadSpec asks the agent to docker-load an image tarball artifact.
+type RemoteLoadSpec struct {
+	ArtifactID string `json:"artifact_id"`
 }
 
 type PortMapping struct {
@@ -177,6 +228,17 @@ func (de *DeploymentEngine) DockerClient() *docker.Client {
 	return de.dockerClient
 }
 
+// BuildManager exposes the engine's builders for context packaging — remote
+// nodes build the tar this produces themselves.
+func (de *DeploymentEngine) BuildManager() *build.BuildManager {
+	return de.buildManager
+}
+
+// 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,
@@ -287,11 +349,19 @@ func (de *DeploymentEngine) executeDeployment(ctx context.Context, deployment *D
 	})
 }
 
-// buildImage builds the container image
+// buildImage builds the container image. "remote" build types produce no
+// local image — the target node builds or loads it from an artifact; the
+// deployment still needs a deterministic tag so every node names it alike.
 func (de *DeploymentEngine) buildImage(ctx context.Context, deployment *Deployment, buildConfig *BuildConfig) (string, error) {
 	if buildConfig == nil {
 		return "", fmt.Errorf("build config is required")
 	}
+	if buildConfig.BuildType == "remote" {
+		if buildConfig.PrebuiltImage != "" {
+			return buildConfig.PrebuiltImage, nil
+		}
+		return fmt.Sprintf("containr-%s-%s:%s", deployment.ServiceID, deployment.Environment, deployment.ID), nil
+	}
 
 	buildReq := &types.BuildRequest{
 		BuildType:     buildConfig.BuildType,
@@ -352,6 +422,10 @@ func (de *DeploymentEngine) deployService(ctx context.Context, deployment *Deplo
 		Maintenance:    cfg.Maintenance,
 		MaintenanceURL: cfg.MaintenanceURL,
 		BasicAuthUsers: cfg.BasicAuthUsers,
+		NodeID:         cfg.NodeID,
+		Spread:         cfg.Spread,
+		RemoteBuild:    cfg.RemoteBuild,
+		RemoteLoad:     cfg.RemoteLoad,
 	}
 	for _, pm := range cfg.PortMappings {
 		if spec.Port == 0 {

app/backend/internal/deployment/runtime.go

@@ -55,6 +55,20 @@ 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
+	// Spread distributes replicas across all online, schedulable agents
+	// instead of a single node. Mutually exclusive with NodeID.
+	Spread bool
+	// PlacementTags restricts auto/spread candidates to agents carrying
+	// every listed tag. An explicit NodeID pin bypasses tag filtering.
+	PlacementTags []string
+	// RemoteBuild makes target nodes docker-build Image from a packaged
+	// context artifact before replicas start (git-sourced remote deploys).
+	RemoteBuild *RemoteBuildSpec
+	// RemoteLoad makes target nodes docker-load a saved image tarball —
+	// remote rollbacks of locally-built tags.
+	RemoteLoad *RemoteLoadSpec
 }
 
 // RuntimeContainer describes one live replica.
@@ -151,8 +165,35 @@ 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.Spread && spec.NodeID == "" {
+		if de.nodeRunner == nil {
+			return nil, fmt.Errorf("service has spread placement but remote dispatch is unavailable")
+		}
+		return de.nodeRunner.ReconcileSpread(ctx, spec)
+	}
+	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)
+	}
+	// Placement tags without a pin/spread resolve to the least-loaded
+	// matching agent on every reconcile — soft affinity, re-evaluated.
+	if len(spec.PlacementTags) > 0 {
+		if de.nodeRunner == nil {
+			return nil, fmt.Errorf("service has placement tags but remote dispatch is unavailable")
+		}
+		return de.nodeRunner.ReconcileAuto(ctx, spec)
+	}
+	// Local placement: retire any remote leftovers from a previous pin,
+	// spread, or tag affinity before reconciling local replicas.
+	if de.nodeRunner != nil {
+		_ = de.nodeRunner.RetireService(ctx, spec.ServiceID)
+	}
+
 	if spec.Replicas < 1 {
 		spec.Replicas = 1
 	}
@@ -498,6 +539,34 @@ 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)
+}
+
+// RemoteRuntimeState exposes inventory-backed remote container state; nil
+// runner means no node support was wired at boot.
+func (de *DeploymentEngine) RemoteRuntimeState(ctx context.Context, serviceID string) (*RuntimeState, error) {
+	if de.nodeRunner == nil {
+		return nil, nil
+	}
+	return de.nodeRunner.RemoteRuntimeState(ctx, serviceID)
+}
+
 // 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/docker/client.go

@@ -336,6 +336,13 @@ func (c *Client) BuildImage(ctx context.Context, buildContext io.Reader, options
 	return resp, nil
 }
 
+// SaveImage streams refs as a docker-save tarball. Remote nodes receive
+// these through the artifact endpoint and docker load them — that is how
+// locally-built rollback tags reach nodes without a registry.
+func (c *Client) SaveImage(ctx context.Context, refs ...string) (io.ReadCloser, error) {
+	return c.cli.ImageSave(ctx, refs)
+}
+
 // RemoveImage removes an image
 func (c *Client) RemoveImage(ctx context.Context, imageID string, force bool) ([]image.DeleteResponse, error) {
 	return c.cli.ImageRemove(ctx, imageID, image.RemoveOptions{
@@ -516,6 +523,21 @@ func (c *Client) ExecRun(ctx context.Context, containerID string, cmd []string)
 	return buf.String(), inspect.ExitCode, nil
 }
 
+// ExecAttach attaches to a running exec instance, returning the hijacked
+// bidirectional stream. With Tty enabled the stream carries raw pty data
+// (no stdcopy multiplexing).
+func (c *Client) ExecAttach(ctx context.Context, execID string) (types.HijackedResponse, error) {
+	return c.cli.ContainerExecAttach(ctx, execID, container.ExecAttachOptions{})
+}
+
+// ExecResize resizes the pty of a running exec instance.
+func (c *Client) ExecResize(ctx context.Context, execID string, cols, rows uint) error {
+	return c.cli.ContainerExecResize(ctx, execID, container.ResizeOptions{
+		Height: rows,
+		Width:  cols,
+	})
+}
+
 // GetImageInfo returns information about a Docker image
 func (c *Client) GetImageInfo(ctx context.Context, imageName string) (*ImageInfo, error) {
 	images, err := c.cli.ImageList(ctx, image.ListOptions{})

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, sleep_enabled (bool — scale to zero on idle), sleep_idle_minutes (1-1440, default 15), node_id (agent id | 'auto' = least-loaded online node; git services build on the node itself), spread (bool — distribute replicas across every online schedulable node; mutually exclusive with a node pin), placement_tags (string array — remote placement only onto nodes carrying every tag; re-resolved per reconcile, pin overrides).", "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). spread (bool) distributes replicas across every online schedulable node; mutually exclusive with a pin — clear node_id to 'local' first if pinned. placement_tags (string array; [] clears) restricts auto/spread placement to nodes carrying every tag; mutually exclusive with an explicit pin — clear the pin first.", "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})
@@ -133,6 +133,7 @@ func init() {
 	register(spec{"containr_templates_deploy", "Deploy a template into a project. Args: id (template), project_id.", "POST", "/templates/{id}/deploy", []string{"id"}, []string{"project_id"}, false})
 	register(spec{"containr_templates_plan", "Dry-resolve a template: expanded expressions, service refs, missing variables. Args: id, variables (object).", "POST", "/templates/{id}/plan", []string{"id"}, nil, false})
 	register(spec{"containr_templates_import_compose", "Convert docker-compose YAML into a v2 template graph config. Args: compose_yaml.", "POST", "/templates/import/compose", nil, []string{"compose_yaml"}, false})
+	register(spec{"containr_templates_import_git", "Fetch a compose file from a git repo (clone URL, ssh remote, or owner/repo via connected providers) and convert it into a v2 template graph config. Args: repo (required), path (default: compose.yaml/yml or docker-compose.yml/yaml), ref (branch or commit).", "POST", "/templates/import/git", nil, []string{"repo", "path", "ref"}, false})
 	register(spec{"containr_templates_deploy_graph", "Deploy an ad-hoc service graph without a stored template. Args: project_id, config ({services:[...]}), variables, plan, region.", "POST", "/templates/deploy", nil, []string{"project_id", "config", "variables", "plan", "region"}, false})
 	register(spec{"containr_projects_import_compose", "Deploy a docker-compose file straight into a project. Args: id (project), compose_yaml, variables, plan, region.", "POST", "/projects/{id}/import-compose", []string{"id"}, []string{"compose_yaml", "variables", "plan", "region"}, false})
 
@@ -173,6 +174,13 @@ 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, tags (string array — placement labels services can require via placement_tags; [] clears).", "PUT", "/agents/{id}", []string{"id"}, []string{"auto_prune", "name", "tags"}, 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_upgrade", "Upgrade a node's agent to the server's bundled binary: downloads over the API, verifies sha256, swaps atomically, re-execs. Node must be online (admin). Args: id.", "POST", "/agents/{id}/upgrade", []string{"id"}, nil, 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/internal/security/scanner.go

@@ -54,6 +54,9 @@ type ScanSummary struct {
 // Scanner handles security scanning operations
 type Scanner struct {
 	db *database.DB
+	// OnScanComplete fires after a scan finishes (goroutine context) —
+	// wired by the api layer for notifications. Optional.
+	OnScanComplete func(scan *SecurityScan)
 }
 
 // NewScanner creates a new security scanner
@@ -115,8 +118,11 @@ func (s *Scanner) performScan(scan *SecurityScan) {
 
 	// Update scan with results
 	completedAt := time.Now()
+	scan.CompletedAt = &completedAt
+	scan.Summary = summary
+	scan.Status = "completed"
 	_, err := s.db.Exec(`
-		UPDATE security_scans 
+		UPDATE security_scans
 		SET status = $1, completed_at = $2, summary = $3
 		WHERE id = $4
 	`, "completed", completedAt, summaryToJSON(summary), scan.ID)
@@ -137,6 +143,10 @@ func (s *Scanner) performScan(scan *SecurityScan) {
 			log.Printf("Failed to store vulnerability %s: %v", vuln.ID, err)
 		}
 	}
+
+	if s.OnScanComplete != nil {
+		s.OnScanComplete(scan)
+	}
 }
 
 // scanDependencies scans for known vulnerable dependencies

app/backend/internal/source/source.go

@@ -0,0 +1,190 @@
+// Package source materializes git checkouts for builds. Services reference
+// a repository by URL (or owner/repo); deployments fetch the exact branch or
+// commit into an isolated workdir, then point the builders at build_path
+// inside it. Credentials travel through GIT_ASKPASS so tokens never land in
+// argv, .git/config, logs, or the build context.
+package source
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+)
+
+// Spec describes one checkout.
+type Spec struct {
+	CloneURL  string // https URL (NormalizeCloneURL output); local paths allowed for tests
+	Branch    string // ref to fetch when Commit is empty
+	Commit    string // optional SHA pinned over Branch
+	BuildPath string // subdirectory inside the repo; "" or "." = repo root
+	Token     string // optional http credential
+	User      string // credential username; defaults per provider in ResolveUser
+}
+
+// NormalizeCloneURL converts the forms services store into an https clone
+// URL: ssh remotes (git@host:org/repo, ssh://git@host/org/repo) map onto
+// https so token auth works uniformly. A bare "owner/repo" is returned
+// unchanged — the caller resolves the host through git_repositories.
+func NormalizeCloneURL(raw string) (string, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "", fmt.Errorf("empty repository reference")
+	}
+	// scp-style ssh remote: [email protected]:org/repo(.git)
+	if strings.HasPrefix(raw, "git@") && strings.Contains(raw, ":") {
+		host := raw[len("git@"):strings.Index(raw, ":")]
+		path := strings.TrimPrefix(raw[strings.Index(raw, ":")+1:], "/")
+		return "https://" + host + "/" + path, nil
+	}
+	if strings.HasPrefix(raw, "ssh://") {
+		u, err := url.Parse(raw)
+		if err != nil {
+			return "", fmt.Errorf("invalid ssh remote %q", raw)
+		}
+		return "https://" + u.Host + u.Path, nil
+	}
+	if strings.HasPrefix(raw, "http://") || strings.HasPrefix(raw, "https://") {
+		return raw, nil
+	}
+	if strings.Contains(raw, "://") {
+		return "", fmt.Errorf("unsupported repository scheme in %q", raw)
+	}
+	if strings.Count(raw, "/") == 1 && !strings.ContainsAny(raw, " @:") {
+		return raw, nil // owner/repo — resolved against git_repositories upstream
+	}
+	return "", fmt.Errorf("unsupported repository reference %q", raw)
+}
+
+// ValidateRemoteURL rejects non-http(s) clones before a deploy accepts them.
+// Local checkouts (tests, mounted workspaces) bypass this via Checkout.
+func ValidateRemoteURL(cloneURL string) error {
+	if strings.HasPrefix(cloneURL, "http://") || strings.HasPrefix(cloneURL, "https://") {
+		return nil
+	}
+	return fmt.Errorf("clone URL must be http(s), got %q", cloneURL)
+}
+
+// Checkout fetches spec into destDir/repo and returns the directory the
+// builders should consume (checkout root + build_path). Callers
+// RemoveAll(destDir) — the checkout is a per-deployment workspace, never
+// shared. The askpass helper lives outside repo so it can't leak into the
+// build context.
+func Checkout(ctx context.Context, destDir string, spec Spec) (string, error) {
+	repoDir := filepath.Join(destDir, "repo")
+	if err := os.MkdirAll(repoDir, 0o755); err != nil {
+		return "", err
+	}
+
+	env := append(os.Environ(), "GIT_TERMINAL_PROMPT=0")
+	if spec.Token != "" {
+		// Askpass keeps the token out of argv and .git/config.
+		askpass := filepath.Join(destDir, ".git-askpass")
+		script := "#!/bin/sh\ncase \"$1\" in\n*sername*) printf '%s' \"$CONTAINR_GIT_USER\" ;;\n*) printf '%s' \"$CONTAINR_GIT_TOKEN\" ;;\nesac\n"
+		if err := os.WriteFile(askpass, []byte(script), 0o700); err != nil {
+			return "", fmt.Errorf("write askpass: %w", err)
+		}
+		user := spec.User
+		if user == "" {
+			user = "x-access-token"
+		}
+		env = append(env,
+			"GIT_ASKPASS="+askpass,
+			"CONTAINR_GIT_USER="+user,
+			"CONTAINR_GIT_TOKEN="+spec.Token,
+		)
+	}
+
+	run := func(args ...string) error {
+		cmd := exec.CommandContext(ctx, "git", args...)
+		cmd.Dir = repoDir
+		cmd.Env = env
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			return fmt.Errorf("git %s: %s", args[0], strings.TrimSpace(string(out)))
+		}
+		return nil
+	}
+
+	if err := run("init", "-q"); err != nil {
+		return "", err
+	}
+	if err := run("remote", "add", "origin", spec.CloneURL); err != nil {
+		return "", err
+	}
+
+	ref := spec.Commit
+	if ref == "" {
+		ref = spec.Branch
+	}
+	if ref == "" {
+		ref = "HEAD"
+	}
+	// Cheap path first, widening on failure: dumb transports reject
+	// --depth outright, and some hosts refuse direct SHA fetches so a
+	// pinned commit may only be reachable through its branch.
+	attempts := [][]string{
+		{"fetch", "--depth", "1", "origin", ref},
+		{"fetch", "origin", ref},
+	}
+	if spec.Commit != "" {
+		branchRef := spec.Branch
+		if branchRef == "" {
+			branchRef = "HEAD"
+		}
+		attempts = append(attempts,
+			[]string{"fetch", "--depth", "100", "origin", branchRef},
+			[]string{"fetch", "origin", branchRef},
+		)
+	}
+	var fetchErr error
+	for _, args := range attempts {
+		if fetchErr = run(args...); fetchErr == nil {
+			break
+		}
+	}
+	if fetchErr != nil {
+		return "", fetchErr
+	}
+	if err := run("checkout", "-q", spec.CommitOrFetchHead()); err != nil {
+		return "", err
+	}
+
+	return ResolveBuildPath(repoDir, spec.BuildPath)
+}
+
+// CommitOrFetchHead is the checkout target: the pinned commit or FETCH_HEAD.
+func (s Spec) CommitOrFetchHead() string {
+	if s.Commit != "" {
+		return s.Commit
+	}
+	return "FETCH_HEAD"
+}
+
+// ResolveBuildPath maps build_path onto the checkout and rejects escapes —
+// a path like ../../etc must never leave the workspace.
+func ResolveBuildPath(checkoutDir, buildPath string) (string, error) {
+	bp := strings.TrimSpace(buildPath)
+	if bp == "" || bp == "." {
+		return checkoutDir, nil
+	}
+	if filepath.IsAbs(bp) {
+		return "", fmt.Errorf("build_path must be relative, got %q", bp)
+	}
+	clean := filepath.Clean(bp)
+	if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("build_path escapes the checkout: %q", bp)
+	}
+	resolved := filepath.Join(checkoutDir, clean)
+	info, err := os.Stat(resolved)
+	if err != nil {
+		return "", fmt.Errorf("build_path %q not found in checkout", bp)
+	}
+	if !info.IsDir() {
+		return "", fmt.Errorf("build_path %q is not a directory", bp)
+	}
+	return resolved, nil
+}

app/backend/internal/source/source_test.go

@@ -0,0 +1,152 @@
+package source
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+)
+
+func TestNormalizeCloneURL(t *testing.T) {
+	cases := []struct {
+		in, want string
+		err      bool
+	}{
+		{"https://github.com/org/repo.git", "https://github.com/org/repo.git", false},
+		{"[email protected]:org/repo.git", "https://github.com/org/repo.git", false},
+		{"ssh://[email protected]/org/repo.git", "https://gitlab.example.com/org/repo.git", false},
+		{"org/repo", "org/repo", false},
+		{"  https://gitlab.com/a/b.git  ", "https://gitlab.com/a/b.git", false},
+		{"", "", true},
+		{"ftp://example.com/repo", "", true},
+		{"weird string", "", true},
+	}
+	for _, c := range cases {
+		got, err := NormalizeCloneURL(c.in)
+		if c.err {
+			if err == nil {
+				t.Errorf("%q: expected error, got %q", c.in, got)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("%q: unexpected error %v", c.in, err)
+			continue
+		}
+		if got != c.want {
+			t.Errorf("%q: got %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+func TestValidateRemoteURL(t *testing.T) {
+	if err := ValidateRemoteURL("https://github.com/o/r.git"); err != nil {
+		t.Errorf("https should pass: %v", err)
+	}
+	if err := ValidateRemoteURL("file:///tmp/repo"); err == nil {
+		t.Error("file:// should be rejected")
+	}
+	if err := ValidateRemoteURL("/tmp/repo"); err == nil {
+		t.Error("local path should be rejected")
+	}
+}
+
+// initRepo creates a small git repo with a branch and returns its path.
+func initRepo(t *testing.T) string {
+	t.Helper()
+	dir := t.TempDir()
+	run := func(args ...string) {
+		t.Helper()
+		cmd := exec.Command("git", args...)
+		cmd.Dir = dir
+		cmd.Env = append(os.Environ(),
+			"GIT_AUTHOR_NAME=t", "GIT_AUTHOR_EMAIL=t@t",
+			"GIT_COMMITTER_NAME=t", "GIT_COMMITTER_EMAIL=t@t")
+		if out, err := cmd.CombinedOutput(); err != nil {
+			t.Fatalf("git %v: %s", args, out)
+		}
+	}
+	run("init", "-q", "-b", "main")
+	if err := os.WriteFile(filepath.Join(dir, "app.txt"), []byte("v1"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "sub", "inner.txt"), []byte("sub"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	run("add", ".")
+	run("commit", "-q", "-m", "first")
+	return dir
+}
+
+func TestCheckoutBranch(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	repo := initRepo(t)
+	dest := t.TempDir()
+	dir, err := Checkout(context.Background(), dest, Spec{CloneURL: repo, Branch: "main"})
+	if err != nil {
+		t.Fatalf("checkout: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "app.txt")); err != nil {
+		t.Errorf("expected app.txt in checkout: %v", err)
+	}
+}
+
+func TestCheckoutBuildPath(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	repo := initRepo(t)
+	dest := t.TempDir()
+	dir, err := Checkout(context.Background(), dest, Spec{CloneURL: repo, Branch: "main", BuildPath: "sub"})
+	if err != nil {
+		t.Fatalf("checkout: %v", err)
+	}
+	if filepath.Base(dir) != "sub" {
+		t.Errorf("expected sub build path, got %s", dir)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "inner.txt")); err != nil {
+		t.Errorf("expected inner.txt under build path: %v", err)
+	}
+}
+
+func TestCheckoutCommit(t *testing.T) {
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available")
+	}
+	repo := initRepo(t)
+	out, err := exec.Command("git", "-C", repo, "rev-parse", "HEAD").Output()
+	if err != nil {
+		t.Fatal(err)
+	}
+	sha := string(out[:len(out)-1])
+	dest := t.TempDir()
+	dir, err := Checkout(context.Background(), dest, Spec{CloneURL: repo, Commit: sha, Branch: "main"})
+	if err != nil {
+		t.Fatalf("checkout commit: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "app.txt")); err != nil {
+		t.Errorf("expected app.txt in pinned checkout: %v", err)
+	}
+}
+
+func TestResolveBuildPathEscapes(t *testing.T) {
+	root := t.TempDir()
+	if _, err := ResolveBuildPath(root, "../../etc"); err == nil {
+		t.Error("escape should be rejected")
+	}
+	if _, err := ResolveBuildPath(root, "/abs/path"); err == nil {
+		t.Error("absolute path should be rejected")
+	}
+	if _, err := ResolveBuildPath(root, "missing"); err == nil {
+		t.Error("missing dir should be rejected")
+	}
+	if got, err := ResolveBuildPath(root, "."); err != nil || got != root {
+		t.Errorf("dot should resolve to root, got %q err=%v", got, err)
+	}
+}

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/migrations_goose/20261110000000_service_spread.sql

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

app/backend/migrations_goose/20261112000000_placement_tags.sql

@@ -0,0 +1,11 @@
+-- +goose Up
+-- Placement tags: operators label node_agents (tags jsonb array of strings),
+-- services require a tag set (placement_tags). "auto" and spread placement
+-- only consider online schedulable agents carrying every required tag.
+-- Explicit node_id pins bypass tag filtering — the pin is an operator override.
+ALTER TABLE services ADD COLUMN IF NOT EXISTS placement_tags jsonb NOT NULL DEFAULT '[]';
+ALTER TABLE node_agents ADD COLUMN IF NOT EXISTS tags jsonb NOT NULL DEFAULT '[]';
+
+-- +goose Down
+ALTER TABLE services DROP COLUMN IF EXISTS placement_tags;
+ALTER TABLE node_agents DROP COLUMN IF EXISTS tags;

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,114 @@ RETURNING *;
 -- name: UpdateContainerStatus :exec
 UPDATE container_instances SET status = $2, updated_at = NOW()
 WHERE id = $1;
+
+-- name: UpdateContainerPorts :exec
+-- Agent reports the real host bindings after create — persist them with
+-- the status flip so ingress can route to the assigned port.
+UPDATE container_instances SET status = $2, ports = $3, 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
+-- Resource-aware: lowest memory utilisation first, then cpu, then container
+-- count. Agents without telemetry sort last (NULL → worst score).
+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(
+        (a.resources->'memory'->>'used')::double precision
+        / NULLIF((a.resources->'memory'->>'total')::double precision, 0),
+        1.0
+    ) ASC,
+    COALESCE((a.resources->'cpu'->>'usage')::double precision, 100.0) ASC,
+    COALESCE(h.container_count, 0) ASC,
+    a.created_at ASC
+LIMIT 1;
+
+-- name: ListSchedulableAgents :many
+SELECT id, name FROM node_agents
+WHERE status = 'online' AND schedulable
+ORDER BY id;
+
+-- name: ListSchedulableAgentsMatching :many
+-- Only agents carrying every required placement tag (jsonb array containment).
+SELECT id, name FROM node_agents
+WHERE status = 'online' AND schedulable
+  AND tags @> $1::jsonb
+ORDER BY id;
+
+-- name: PickLeastLoadedAgentMatching :one
+-- Same resource-aware ordering as PickLeastLoadedAgent, restricted to agents
+-- carrying every required placement tag.
+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
+  AND a.tags @> $1::jsonb
+ORDER BY
+    COALESCE(
+        (a.resources->'memory'->>'used')::double precision
+        / NULLIF((a.resources->'memory'->>'total')::double precision, 0),
+        1.0
+    ) ASC,
+    COALESCE((a.resources->'cpu'->>'usage')::double precision, 100.0) ASC,
+    COALESCE(h.container_count, 0) ASC,
+    a.created_at ASC
+LIMIT 1;
+
+-- name: SetAgentTags :exec
+UPDATE node_agents SET tags = $2::jsonb, updated_at = NOW() WHERE id = $1;
+
+-- name: ListServiceContainers :many
+SELECT id, name, node_agent_id, status, ports, resources FROM container_instances
+WHERE service_id = $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: UpdateContainerStateByName :exec
+-- Agent heartbeat reports real docker state + net counters; reconcile
+-- inventory for rows this node owns. Tombstones win — never resurrect a
+-- removed replica. $4 is the cumulative rx+tx byte counter.
+UPDATE container_instances SET
+    status = jsonb_set(status, '{state}', $3::jsonb),
+    resources = jsonb_set(COALESCE(resources, '{}'::jsonb), '{net_bytes}', $4::jsonb),
+    updated_at = NOW()
+WHERE name = $1 AND node_agent_id = $2
+  AND status->>'state' IS DISTINCT FROM 'removed';
+
+-- name: ListServiceAgents :many
+-- Distinct agents holding inventory rows for a service.
+SELECT DISTINCT node_agent_id FROM container_instances WHERE service_id = $1;
+
+-- name: ScrubCommandPayload :exec
+UPDATE agent_commands SET payload = $2, updated_at = NOW() WHERE id = $1;

app/backend/sqlc/schema.sql

@@ -66,7 +66,10 @@ 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),
+    spread BOOLEAN NOT NULL DEFAULT false,
+    placement_tags JSONB NOT NULL DEFAULT '[]'
 );
 
 CREATE TABLE registries (
@@ -192,7 +195,10 @@ 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,
+    tags JSONB NOT NULL DEFAULT '[]'
 );
 
 CREATE TABLE container_instances (

app/frontend/Dockerfile

@@ -1,5 +1,7 @@
 # Build stage
-FROM node:22-alpine AS builder
+ARG NODE_IMAGE=node:22-alpine
+ARG NGINX_IMAGE=nginx:alpine
+FROM ${NODE_IMAGE} AS builder
 
 # Set working directory
 WORKDIR /app
@@ -24,7 +26,7 @@ ENV VITE_AUTH_URL=${VITE_AUTH_URL}
 RUN npm run build
 
 # Production stage
-FROM nginx:alpine
+FROM ${NGINX_IMAGE}
 
 # Copy custom nginx config
 COPY nginx.conf /etc/nginx/nginx.conf

app/frontend/package-lock.json

@@ -33,6 +33,8 @@
         "@tailwindcss/typography": "^0.5.19",
         "@tanstack/react-query": "^5.66.0",
         "@types/dompurify": "^3.0.5",
+        "@xterm/addon-fit": "^0.11.0",
+        "@xterm/xterm": "^6.0.0",
         "@xyflow/react": "^12.10.0",
         "autoprefixer": "^10.4.24",
         "axios": "^1.7.9",
@@ -4262,6 +4264,21 @@
         "url": "https://opencollective.com/vitest"
       }
     },
+    "node_modules/@xterm/addon-fit": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@xterm/addon-fit/-/addon-fit-0.11.0.tgz",
+      "integrity": "sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==",
+      "license": "MIT"
+    },
+    "node_modules/@xterm/xterm": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-6.0.0.tgz",
+      "integrity": "sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg==",
+      "license": "MIT",
+      "workspaces": [
+        "addons/*"
+      ]
+    },
     "node_modules/@xyflow/react": {
       "version": "12.10.1",
       "resolved": "https://registry.npmjs.org/@xyflow/react/-/react-12.10.1.tgz",

app/frontend/package.json

@@ -44,6 +44,8 @@
     "@tailwindcss/typography": "^0.5.19",
     "@tanstack/react-query": "^5.66.0",
     "@types/dompurify": "^3.0.5",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
     "@xyflow/react": "^12.10.0",
     "autoprefixer": "^10.4.24",
     "axios": "^1.7.9",

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/activity/pages/ActivityPage.tsx

@@ -2,8 +2,10 @@ import { useQuery } from '@tanstack/react-query';
 import { useState } from 'react';
 import { listActivity, type ActivityEntry } from '@/lib/api-client';
 import { useDemoMode } from '@/lib/demo-mode';
+import { type FilterConfig } from '@/lib/dynamic-filter';
+import { useDynamicFilter, useFilterState } from '@/lib/use-dynamic-filter';
 import { formatRelative } from '@/lib/time';
-import { DemoRestricted } from '@/shared/components';
+import { DemoRestricted, FilterBar } from '@/shared/components';
 import {
   Activity, AlertCircle, CheckCircle2, Database, GitBranch, Info, Key,
   Loader2, Package, Projector, Rocket, Shield, User, Users, Wrench,
@@ -22,23 +24,37 @@ const SEVERITY_STYLE: Record<string, { icon: typeof Info; cls: string; dot: stri
   info:    { icon: Info,          cls: 'text-[var(--accent-primary)]', dot: 'bg-[var(--accent-primary)]' },
 };
 
-const SEVERITIES = ['', 'error', 'warning', 'success', 'info'] as const;
+const SCHEMA: FilterConfig<ActivityEntry>[] = [
+  { key: 'q', label: 'Search', type: 'search', searchFields: ['label', 'action', 'user_email'] },
+  {
+    key: 'severity', label: 'Severity', type: 'select',
+    options: [
+      { value: 'error', label: 'Error' },
+      { value: 'warning', label: 'Warning' },
+      { value: 'success', label: 'Success' },
+      { value: 'info', label: 'Info' },
+    ],
+  },
+  { key: 'category', label: 'Category', type: 'select' },
+];
 
 export function ActivityPage() {
   const isDemoMode = useDemoMode();
-  const [severity, setSeverity] = useState('');
   const [page, setPage] = useState(1);
+  const { filters } = useFilterState(SCHEMA);
+  const severityParam = filters.severity === 'all' ? '' : String(filters.severity ?? '');
 
   const query = useQuery({
-    queryKey: ['activity-feed', severity, page],
+    queryKey: ['activity-feed', severityParam, page],
-    queryFn: () => listActivity({ severity: severity || undefined, page, limit: 50 }),
+    queryFn: () => listActivity({ severity: severityParam || undefined, page, limit: 50 }),
     enabled: !isDemoMode,
     refetchInterval: 15000,
   });
+  const filter = useDynamicFilter<ActivityEntry>({ data: query.data?.activity ?? [], schema: SCHEMA });
 
   if (isDemoMode) return <DemoRestricted feature="Activity" />;
 
-  const entries = query.data?.activity ?? [];
+  const entries = filter.filteredData;
 
   return (
     <div className="min-h-screen">
@@ -52,21 +68,11 @@ export function ActivityPage() {
       </div>
 
       <div className="px-8 py-6 space-y-4">
-        <div className="flex items-center gap-2">
+        <div className="flex items-start gap-3">
-          {SEVERITIES.map((s) => (
+          <div className="flex-1">
-            <button
+            <FilterBar {...filter} />
-              key={s || 'all'}
+          </div>
-              onClick={() => { setSeverity(s); setPage(1); }}
+          {query.isFetching && <Loader2 size={14} className="animate-spin text-[var(--text-muted)] mt-3" />}
-              className={`v-mono text-[10px] uppercase px-3 py-1.5 rounded-md border transition-colors ${
-                severity === s
-                  ? 'border-[var(--accent-primary)] text-[var(--accent-primary)] bg-[var(--accent-primary)]/10'
-                  : 'border-[var(--border-subtle)] text-[var(--text-muted)] hover:text-[var(--text-primary)]'
-              }`}
-            >
-              {s || 'all'}
-            </button>
-          ))}
-          {query.isFetching && <Loader2 size={14} className="animate-spin text-[var(--text-muted)]" />}
         </div>
 
         <div className="panel p-0 divide-y divide-[var(--border-subtle)]">

app/frontend/src/features/audit/pages/AuditLogsPage.tsx

@@ -2,8 +2,10 @@ import { useDeferredValue, useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { listAuditLogs } from '@/lib/api-client';
 import { useDemoMode } from '@/lib/demo-mode';
+import { type FilterConfig } from '@/lib/dynamic-filter';
+import { useDynamicFilter } from '@/lib/use-dynamic-filter';
 import { formatDate, formatRelative } from '@/lib/time';
-import { DemoRestricted } from '@/shared/components';
+import { DemoRestricted, FilterBar } from '@/shared/components';
 import { ScrollText, ChevronLeft, ChevronRight, Loader2 } from 'lucide-react';
 
 const PAGE_SIZE = 50;
@@ -15,20 +17,34 @@ const rangeOptions = [
   { value: '30d', label: 'Last 30 days', ms: 30 * 24 * 60 * 60 * 1000 },
 ] as const;
 
-const inputClass =
+// Server-backed filters — the engine runs over empty data; values map to
-  'h-9 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm text-[var(--text-primary)] placeholder:text-[var(--text-muted)] focus:border-[var(--accent-primary)] focus:ring-1 focus:ring-[var(--accent-primary)] transition-all';
+// API params. URL state makes filtered views shareable.
+const AUDIT_SCHEMA: FilterConfig<unknown>[] = [
+  { key: 'resource', label: 'Resource', type: 'search' },
+  { key: 'action', label: 'Action', type: 'search' },
+  { key: 'actor', label: 'Actor', type: 'search' },
+  {
+    key: 'range', label: 'Time', type: 'select',
+    options: rangeOptions.filter((o) => o.value !== '').map((o) => ({ value: o.value, label: o.label })),
+  },
+];
 
 export function AuditLogsPage() {
   const isDemoMode = useDemoMode();
-  const [resource, setResource] = useState('');
+  const filter = useDynamicFilter<unknown>({ data: [], schema: AUDIT_SCHEMA });
-  const [action, setAction] = useState('');
-  const [actor, setActor] = useState('');
-  const [range, setRange] = useState('');
   const [page, setPage] = useState(1);
+  // Back to page 1 whenever the filter set changes.
+  const filtersJson = JSON.stringify(filter.filters);
+  const [prevFiltersJson, setPrevFiltersJson] = useState(filtersJson);
+  if (prevFiltersJson !== filtersJson) {
+    setPrevFiltersJson(filtersJson);
+    setPage(1);
+  }
 
-  const deferredResource = useDeferredValue(resource);
+  const deferredResource = useDeferredValue(String(filter.filters.resource ?? ''));
-  const deferredAction = useDeferredValue(action);
+  const deferredAction = useDeferredValue(String(filter.filters.action ?? ''));
-  const deferredActor = useDeferredValue(actor);
+  const deferredActor = useDeferredValue(String(filter.filters.actor ?? ''));
+  const range = filter.filters.range === 'all' ? '' : String(filter.filters.range ?? '');
 
   const filters = {
     resource: deferredResource.trim() || undefined,
@@ -54,15 +70,7 @@ export function AuditLogsPage() {
 
   const logs = logsQuery.data ?? [];
   const hasNext = logs.length === PAGE_SIZE;
-  const hasFilters = Boolean(resource || action || actor || range);
+  const hasFilters = filter.activeCount > 0;
-
-  const resetFilters = () => {
-    setResource('');
-    setAction('');
-    setActor('');
-    setRange('');
-    setPage(1);
-  };
 
   return (
     <div className="min-h-screen">
@@ -79,63 +87,7 @@ export function AuditLogsPage() {
 
       <div className="w-full px-8 py-6">
         <section className="panel p-6">
-          <div className="flex flex-wrap items-end gap-3 mb-5">
+          <FilterBar {...filter} />
-            <div>
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-1.5">
-                Resource
-              </label>
-              <input
-                value={resource}
-                onChange={(e) => { setResource(e.target.value); setPage(1); }}
-                placeholder="service, project…"
-                className={`${inputClass} w-44`}
-              />
-            </div>
-            <div>
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-1.5">
-                Action
-              </label>
-              <input
-                value={action}
-                onChange={(e) => { setAction(e.target.value); setPage(1); }}
-                placeholder="create, deploy…"
-                className={`${inputClass} w-44`}
-              />
-            </div>
-            <div>
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-1.5">
-                Actor
-              </label>
-              <input
-                value={actor}
-                onChange={(e) => { setActor(e.target.value); setPage(1); }}
-                placeholder="user email"
-                className={`${inputClass} w-52`}
-              />
-            </div>
-            <div>
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-1.5">
-                Time
-              </label>
-              <select
-                value={range}
-                onChange={(e) => { setRange(e.target.value); setPage(1); }}
-                className={`${inputClass} w-40`}
-              >
-                {rangeOptions.map((o) => (
-                  <option key={o.value} value={o.value}>{o.label}</option>
-                ))}
-              </select>
-            </div>
-            {hasFilters && (
-              <button
-                onClick={resetFilters}
-                className="h-9 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] text-xs font-medium text-[var(--text-secondary)] hover:border-[var(--border-default)] transition-colors"
-              >
-                Clear
-              </button>
-            )}
-          </div>
 
           <div className="overflow-x-auto">
             <table className="w-full text-sm">

app/frontend/src/features/builds/pages/BuildsPage.tsx

@@ -9,6 +9,9 @@ import {
 } from '@/lib/api-client';
 import { useBuildUpdates } from '@/lib/use-build-updates';
 import { useDemoMode } from '@/lib/demo-mode';
+import { type FilterConfig } from '@/lib/dynamic-filter';
+import { useDynamicFilter, useFilterState } from '@/lib/use-dynamic-filter';
+import { FilterBar } from '@/shared/components';
 import { demoBuilds } from '@/lib/demo-data';
 import { formatRelative } from '@/lib/time';
 import {
@@ -34,6 +37,19 @@ const statusOptions: Array<{ value: '' | BuildStatus; label: string }> = [
   { value: 'cancelled', label: 'Cancelled' },
 ];
 
+const BUILD_SCHEMA: FilterConfig<BuildEntity>[] = [
+  {
+    key: 'status', label: 'Status', type: 'select',
+    options: statusOptions.filter((o) => o.value !== '').map((o) => ({ value: o.value, label: o.label })),
+  },
+  { key: 'project', label: 'Project ID', type: 'search', searchFields: ['projectId'] },
+  { key: 'service', label: 'Service ID', type: 'search', searchFields: ['serviceId'] },
+  {
+    key: 'created', label: 'Time', type: 'date-range',
+    accessor: (b) => b.startedAt ?? b.completedAt,
+  },
+];
+
 function StatusBadge({ status }: { status: BuildStatus }) {
   const config = {
     success: { color: 'var(--success)', bg: 'var(--success-soft)', Icon: Check, animate: false },
@@ -72,9 +88,10 @@ export function BuildsPage() {
   const queryClient = useQueryClient();
   const isDemoMode = useDemoMode();
 
-  const [projectFilter, setProjectFilter] = useState('');
+  const { filters } = useFilterState(BUILD_SCHEMA);
-  const [serviceFilter, setServiceFilter] = useState('');
+  const projectFilter = String(filters.project ?? '');
-  const [statusFilter, setStatusFilter] = useState<'' | BuildStatus>('');
+  const serviceFilter = String(filters.service ?? '');
+  const statusFilter = filters.status === 'all' ? '' : String(filters.status ?? '');
   const [limit, setLimit] = useState(50);
   const [selectedBuild, setSelectedBuild] = useState<BuildEntity | null>(null);
 
@@ -85,20 +102,22 @@ export function BuildsPage() {
       listBuilds({
         projectId: projectFilter || undefined,
         serviceId: serviceFilter || undefined,
-        status: statusFilter || undefined,
+        status: (statusFilter || undefined) as BuildStatus | undefined,
         page: 1,
         limit,
       }),
   });
 
-  const builds = useMemo(
+  const rawBuilds = useMemo(
     () => (isDemoMode ? demoBuilds : buildsQuery.data?.builds ?? []),
     [isDemoMode, buildsQuery.data?.builds],
   );
+  const filter = useDynamicFilter<BuildEntity>({ data: rawBuilds, schema: BUILD_SCHEMA });
+  const builds = filter.filteredData;
 
   const subscribedBuildIds = useMemo(
-    () => (isDemoMode ? [] : builds.map((build) => build.id)),
+    () => (isDemoMode ? [] : rawBuilds.map((build) => build.id)),
-    [isDemoMode, builds],
+    [isDemoMode, rawBuilds],
   );
   const liveStatus = useBuildUpdates(subscribedBuildIds, ({ channel }) => {
     queryClient.invalidateQueries({ queryKey: ['builds-page'] });
@@ -217,46 +236,13 @@ export function BuildsPage() {
       {/* Filters */}
       <div className="w-full px-8">
         <div className="panel p-4">
-          <div className="flex items-center gap-2 mb-4">
+          <div className="flex items-center gap-2">
             <Filter size={16} className="text-[var(--text-tertiary)]" />
             <span className="text-sm font-medium text-[var(--text-secondary)]">Filters</span>
           </div>
-          <div className="grid grid-cols-2 lg:grid-cols-4 gap-4">
+          <div className="flex flex-wrap items-end gap-3 mt-3">
-            <div>
+            <div className="flex-1">
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-2">
+              <FilterBar {...filter} />
-                Status
-              </label>
-              <select
-                value={statusFilter}
-                onChange={(e) => setStatusFilter(e.target.value as '' | BuildStatus)}
-                className="w-full h-10 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm focus:border-[var(--accent-primary)] transition-colors"
-              >
-                {statusOptions.map((option) => (
-                  <option key={option.label} value={option.value}>{option.label}</option>
-                ))}
-              </select>
-            </div>
-            <div>
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-2">
-                Project ID
-              </label>
-              <input
-                value={projectFilter}
-                onChange={(e) => setProjectFilter(e.target.value)}
-                className="w-full h-10 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm focus:border-[var(--accent-primary)] transition-colors"
-                placeholder="project-123"
-              />
-            </div>
-            <div>
-              <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-2">
-                Service ID
-              </label>
-              <input
-                value={serviceFilter}
-                onChange={(e) => setServiceFilter(e.target.value)}
-                className="w-full h-10 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm focus:border-[var(--accent-primary)] transition-colors"
-                placeholder="service-abc"
-              />
             </div>
             <div>
               <label className="block text-xs font-medium uppercase tracking-wider text-[var(--text-muted)] mb-2">

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

@@ -0,0 +1,496 @@
+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,
+  upgradeAgent,
+  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 [tagDraft, setTagDraft] = useState<string | null>(null);
+
+  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; tags?: string[] }) => updateAgent(id, body),
+    onSuccess: () => { setRename(null); setTagDraft(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 upgradeMutation = useMutation({
+    mutationFn: () => upgradeAgent(id),
+    onSuccess: 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>
+              )}
+              <p className="v-mono mt-1 text-[11px] text-[var(--text-tertiary)] flex items-center gap-1.5 flex-wrap">
+                tags:
+                {tagDraft === null ? (
+                  <>
+                    {agent.tags.length > 0
+                      ? agent.tags.map((t) => (
+                          <span key={t} className="px-1.5 py-0.5 rounded border border-[var(--border-subtle)] text-[var(--text-secondary)]">{t}</span>
+                        ))
+                      : <span className="text-[var(--text-muted)]">none</span>}
+                    {isAdmin && (
+                      <button
+                        onClick={() => setTagDraft(agent.tags.join(', '))}
+                        className="text-[var(--text-muted)] hover:text-[var(--text-primary)]"
+                        title="Edit placement tags — services can require them via placement_tags"
+                      >
+                        <Pencil size={11} />
+                      </button>
+                    )}
+                  </>
+                ) : (
+                  <>
+                    <input
+                      value={tagDraft}
+                      onChange={(e) => setTagDraft(e.target.value)}
+                      onKeyDown={(e) => {
+                        if (e.key === 'Enter') updateMutation.mutate({ tags: tagDraft.split(',').map((t) => t.trim()).filter(Boolean) });
+                        if (e.key === 'Escape') setTagDraft(null);
+                      }}
+                      autoFocus
+                      placeholder="eu-west, gpu"
+                      className="rounded-md border border-[var(--border-subtle)] bg-[var(--bg-tertiary)] px-2 py-0.5 text-[11px] text-[var(--text-primary)] w-52"
+                    />
+                    <button
+                      onClick={() => updateMutation.mutate({ tags: tagDraft.split(',').map((t) => t.trim()).filter(Boolean) })}
+                      className="text-[var(--accent-primary)] hover:underline"
+                    >save</button>
+                    <button onClick={() => setTagDraft(null)} className="text-[var(--text-muted)] hover:underline">cancel</button>
+                  </>
+                )}
+              </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={() => upgradeMutation.mutate()}
+                    disabled={upgradeMutation.isPending || !online}
+                    title={online
+                      ? `Upgrade agent to the server's bundled binary (server ${upgradeMutation.data?.version ?? 'build'}) — the agent restarts itself`
+                      : 'Node must be online to upgrade'}
+                    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"
+                  >
+                    {upgradeMutation.isPending ? 'upgrading…' : 'upgrade agent'}
+                  </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$/, '')} \\
+  const apiBase = getApiBaseUrl().replace(/\/api\/v1$/, '');
-CONTAINR_AGENT_AUTH_TOKEN=${issuedToken?.token ?? '<token>'} \\
+  const installCommand = `curl -fsSL ${apiBase}/api/agents/install.sh | bash -s -- --url ${apiBase} --token ${issuedToken?.token ?? '<token>'}`;
-containr-agent`;
+  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">
+                          <div className="flex items-center gap-3">
-                            <p className="text-xs font-semibold text-[var(--text-primary)]">{agent.status}</p>
+                            {isAdmin && (
-                            <p className="text-xs text-[var(--text-tertiary)]">{formatBytes(agent.resources.memory.available)} free</p>
+                              <>
+                                <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/components/ServiceTerminal.tsx

@@ -0,0 +1,107 @@
+import { useEffect, useRef, useState } from 'react';
+import { Terminal } from '@xterm/xterm';
+import { FitAddon } from '@xterm/addon-fit';
+import '@xterm/xterm/css/xterm.css';
+import { Loader2 } from 'lucide-react';
+import { getApiBaseUrl } from '@/lib/api-client';
+
+type Frame = {
+  type: 'stdin' | 'resize' | 'stdout' | 'exit' | 'error' | 'ping' | 'pong';
+  data?: string;
+  cols?: number;
+  rows?: number;
+  code?: number;
+  message?: string;
+};
+
+// Interactive shell: WebSocket → docker exec pty in the service container.
+export function ServiceTerminal({ serviceId }: { serviceId: string }) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  const [status, setStatus] = useState<'connecting' | 'live' | 'ended' | 'error'>('connecting');
+
+  useEffect(() => {
+    if (!hostRef.current) return;
+
+    const term = new Terminal({
+      fontFamily: 'var(--font-mono, ui-monospace, monospace)',
+      fontSize: 13,
+      cursorBlink: true,
+      convertEol: false,
+      theme: {
+        background: '#0a0a0c',
+        foreground: '#d4d4d8',
+        cursor: '#a1a1aa',
+        selectionBackground: '#3f3f46',
+      },
+    });
+    const fit = new FitAddon();
+    term.loadAddon(fit);
+    term.open(hostRef.current);
+    fit.fit();
+
+    const wsUrl = getApiBaseUrl().replace(/^http/, 'ws');
+    const ws = new WebSocket(`${wsUrl}/services/${serviceId}/terminal`);
+
+    ws.onopen = () => {
+      setStatus('live');
+      const { cols, rows } = term;
+      const frame: Frame = { type: 'resize', cols, rows };
+      ws.send(JSON.stringify(frame));
+    };
+    ws.onmessage = (ev) => {
+      let f: Frame;
+      try {
+        f = JSON.parse(ev.data);
+      } catch {
+        return;
+      }
+      if (f.type === 'stdout' && f.data) term.write(f.data);
+      else if (f.type === 'exit') {
+        setStatus('ended');
+        term.write(`\r\n\x1b[90m[session ended — exit ${f.code ?? 0}]\x1b[0m\r\n`);
+      } else if (f.type === 'error') {
+        setStatus('error');
+        term.write(`\r\n\x1b[31m${f.message ?? 'terminal error'}\x1b[0m\r\n`);
+      }
+    };
+    ws.onerror = () => setStatus((s) => (s === 'live' ? s : 'error'));
+    ws.onclose = () => setStatus((s) => (s === 'error' ? s : 'ended'));
+
+    const dataSub = term.onData((data) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'stdin', data } satisfies Frame));
+      }
+    });
+
+    const observer = new ResizeObserver(() => {
+      fit.fit();
+      if (ws.readyState === WebSocket.OPEN) {
+        const { cols, rows } = term;
+        ws.send(JSON.stringify({ type: 'resize', cols, rows } satisfies Frame));
+      }
+    });
+    observer.observe(hostRef.current);
+
+    return () => {
+      observer.disconnect();
+      dataSub.dispose();
+      ws.close();
+      term.dispose();
+    };
+  }, [serviceId]);
+
+  return (
+    <div className="relative">
+      {status === 'connecting' && (
+        <div className="absolute inset-0 z-10 flex items-center justify-center bg-[#0a0a0c]/80 rounded-[var(--radius-md)]">
+          <Loader2 size={18} className="animate-spin text-[var(--accent-primary)]" />
+        </div>
+      )}
+      <div
+        ref={hostRef}
+        className="rounded-[var(--radius-md)] border border-[var(--border-subtle)] overflow-hidden p-2"
+        style={{ background: '#0a0a0c', height: 420 }}
+      />
+    </div>
+  );
+}

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

@@ -26,7 +26,6 @@ import {
   deleteScalingPolicy,
   getServiceScalingState,
   manualScaleService,
-  execInService,
   rollbackDeployment,
   cancelDeployment,
   updateServiceVariables,
@@ -49,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';
@@ -59,6 +59,7 @@ import { getCurrentUserProfile } from '@/lib/api-client';
 import { parseDotenv, validateVariableRows, type VariableDraft } from '../variable-utils';
 import { formatBytes, formatDate, formatRelative, seededMetric } from '@/lib/time';
 import { EnhancedMetricCard, LineAreaChart, DonutChart } from '@/shared/components';
+import { ServiceTerminal } from '@/features/service/components/ServiceTerminal';
 import {
   Activity,
   FileText,
@@ -338,21 +339,6 @@ export function ServiceDetailPage() {
     },
   });
 
-  // --- Console ---
-  const [consoleInput, setConsoleInput] = useState('');
-  const [consoleHistory, setConsoleHistory] = useState<
-    Array<{ command: string; output: string; exitCode: number; error: string }>
-  >([]);
-  const execMutation = useMutation({
-    mutationFn: (command: string) => execInService(serviceId, command),
-    onSuccess: (result, command) => {
-      setConsoleHistory((prev) => [
-        { command, output: result.output ?? '', exitCode: result.exit_code ?? 0, error: result.error ?? '' },
-        ...prev,
-      ]);
-      setConsoleInput('');
-    },
-  });
   const triggerCronMutation = useMutation({
     mutationFn: (id: string) => triggerCronJob(id),
     onSuccess: () => {
@@ -481,6 +467,7 @@ export function ServiceDetailPage() {
     onSuccess: () => {
       setNetworkForm(null);
       setSleepDraft(null);
+      setNodeDraft(null);
       invalidateService();
     },
   });
@@ -500,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);
@@ -1927,64 +1921,10 @@ export function ServiceDetailPage() {
               </div>
               <div>
                 <h2 className="text-lg font-semibold text-[var(--text-primary)]">Console</h2>
-                <p className="text-sm text-[var(--text-secondary)]">One-off commands via docker exec — 30s limit, 64KB output cap</p>
+                <p className="text-sm text-[var(--text-secondary)]">Interactive shell inside the service container</p>
               </div>
             </div>
-
+            <ServiceTerminal serviceId={serviceId} />
-            <form
-              className="flex items-center gap-2 mb-4"
-              onSubmit={(e) => {
-                e.preventDefault();
-                const cmd = consoleInput.trim();
-                if (cmd && !execMutation.isPending) execMutation.mutate(cmd);
-              }}
-            >
-              <span className="text-sm font-mono text-[var(--accent-primary)]">$</span>
-              <input
-                value={consoleInput}
-                onChange={(e) => setConsoleInput(e.target.value)}
-                placeholder="e.g. env | sort | head -20"
-                disabled={execMutation.isPending}
-                className="flex-1 px-3 py-2 rounded-[var(--radius-md)] bg-[var(--surface-muted)] border border-[var(--border-subtle)] text-sm font-mono text-[var(--text-primary)] disabled:opacity-50"
-              />
-              <button
-                type="submit"
-                disabled={execMutation.isPending || !consoleInput.trim()}
-                className="px-4 py-2 rounded-[var(--radius-md)] bg-[var(--accent-primary)] text-[var(--accent-on)] text-sm font-medium disabled:opacity-50"
-              >
-                {execMutation.isPending ? 'Running…' : 'Run'}
-              </button>
-            </form>
-
-            {execMutation.isError && (
-              <p className="mb-4 text-xs text-[var(--error)]">
-                {(execMutation.error as Error)?.message ?? 'Command failed'}
-              </p>
-            )}
-
-            {consoleHistory.length === 0 ? (
-              <p className="text-xs text-[var(--text-tertiary)]">
-                Commands run inside the service's running container as its default user. No interactive shell — stdout/stderr is captured and returned.
-              </p>
-            ) : (
-              <div className="space-y-3">
-                {consoleHistory.map((entry, i) => (
-                  <div key={i} className="rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] p-3">
-                    <div className="flex items-center justify-between mb-1">
-                      <p className="text-xs font-mono text-[var(--text-primary)]">$ {entry.command}</p>
-                      <span className={`text-xs font-mono ${entry.exitCode === 0 && !entry.error ? 'text-[var(--success)]' : 'text-[var(--error)]'}`}>
-                        {entry.error ? 'error' : `exit ${entry.exitCode}`}
-                      </span>
-                    </div>
-                    {(entry.output || entry.error) && (
-                      <pre className="text-xs font-mono text-[var(--text-secondary)] whitespace-pre-wrap break-all max-h-64 overflow-y-auto">
-                        {entry.output}{entry.error ? `\n${entry.error}` : ''}
-                      </pre>
-                    )}
-                  </div>
-                ))}
-              </div>
-            )}
           </div>
         )}
 
@@ -2453,6 +2393,95 @@ 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={service.spread ? '__spread__' : (nodeDraft ?? (service.nodeId || 'local'))}
+                    disabled={service.spread}
+                    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)] disabled:opacity-50"
+                  >
+                    {service.spread && <option value="__spread__">All nodes (spread)</option>}
+                    <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>
+                  <label className="flex items-center gap-1.5 text-[var(--text-secondary)]">
+                    <input
+                      type="checkbox"
+                      checked={service.spread ?? false}
+                      disabled={updateServiceMutation.isPending || (!!service.nodeId && !service.spread)}
+                      title={service.nodeId && !service.spread ? 'Clear the node pin first (choose "This server")' : undefined}
+                      onChange={(e) => updateServiceMutation.mutate({ spread: e.target.checked })}
+                      className="accent-[var(--accent-primary)]"
+                    />
+                    spread replicas across nodes
+                  </label>
+                  {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>
+                {!service.nodeId && (
+                  <div className="mt-3 flex items-center gap-2 text-xs">
+                    <label className="text-[var(--text-tertiary)]" htmlFor="placement-tags">
+                      required node tags
+                    </label>
+                    <input
+                      id="placement-tags"
+                      type="text"
+                      placeholder="e.g. eu-west, gpu — empty = any node"
+                      defaultValue={(service.placementTags ?? []).join(', ')}
+                      disabled={updateServiceMutation.isPending}
+                      title="Remote placement only targets nodes carrying every tag. Re-resolved each reconcile — the service follows the tag, not a stored node."
+                      onBlur={(e) => {
+                        const next = e.target.value.split(',').map((t) => t.trim()).filter(Boolean);
+                        const prev = service.placementTags ?? [];
+                        if (next.join('|') !== prev.join('|')) {
+                          updateServiceMutation.mutate({ placement_tags: next });
+                        }
+                      }}
+                      onKeyDown={(e) => { if (e.key === 'Enter') (e.target as HTMLInputElement).blur(); }}
+                      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)] w-72"
+                    />
+                  </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/features/templates/pages/TemplatesPage.tsx

@@ -8,6 +8,7 @@ import {
   getCurrentUserProfile,
   getTemplateById,
   importComposeTemplate,
+  importGitComposeTemplate,
   listProjects,
   listTemplates,
   updateTemplate,
@@ -154,6 +155,10 @@ export function TemplatesPage() {
   const [composeYaml, setComposeYaml] = useState('');
   const [composeWarnings, setComposeWarnings] = useState<string[]>([]);
   const [composeError, setComposeError] = useState<string | null>(null);
+  const [composeMode, setComposeMode] = useState<'paste' | 'git'>('paste');
+  const [gitRepo, setGitRepo] = useState('');
+  const [gitPath, setGitPath] = useState('');
+  const [gitRef, setGitRef] = useState('');
 
   const [lastDeployment, setLastDeployment] = useState<{
     projectId: string;
@@ -364,7 +369,10 @@ export function TemplatesPage() {
   });
 
   const composeImportMutation = useMutation({
-    mutationFn: (yaml: string) => importComposeTemplate(yaml),
+    mutationFn: () =>
+      composeMode === 'git'
+        ? importGitComposeTemplate(gitRepo.trim(), gitPath.trim(), gitRef.trim())
+        : importComposeTemplate(composeYaml),
     onSuccess: (result) => {
       setComposeWarnings(result.warnings);
       setComposeError(null);
@@ -644,6 +652,11 @@ export function TemplatesPage() {
                                   Public
                                 </span>
                               ) : null}
+                              {template.source === 'registry' ? (
+                                <span className="px-1.5 py-0.5 rounded bg-[var(--accent-primary-soft)] text-[var(--accent-primary)] text-[10px] font-semibold">
+                                  Registry
+                                </span>
+                              ) : null}
                             </div>
                             <div className="flex items-center gap-2 mt-1">
                               <span 
@@ -1102,7 +1115,7 @@ export function TemplatesPage() {
               <div>
                 <h2 className="text-[15px] font-semibold text-[var(--text-primary)]">Import docker-compose</h2>
                 <p className="text-xs text-[var(--text-tertiary)]">
-                  Paste a compose file — known database images become managed databases, everything else becomes services.
+                  Paste a compose file or pull one from a git repo — known database images become managed databases.
                 </p>
               </div>
               <button
@@ -1113,13 +1126,67 @@ export function TemplatesPage() {
                 <X size={15} />
               </button>
             </div>
-            <textarea
+            <div className="flex gap-1 border-b border-[var(--border-subtle)] px-5 pt-3">
-              value={composeYaml}
+              {(['paste', 'git'] as const).map((m) => (
-              onChange={(e) => setComposeYaml(e.target.value)}
+                <button
-              spellCheck={false}
+                  key={m}
-              placeholder={'services:\n  db:\n    image: postgres:16\n  web:\n    image: myapp:latest\n    depends_on: [db]'}
+                  type="button"
-              className="mono min-h-[320px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
+                  onClick={() => setComposeMode(m)}
-            />
+                  className={`rounded-t-[var(--radius-md)] px-3 py-1.5 text-xs font-medium ${
+                    composeMode === m
+                      ? 'bg-[var(--surface-muted)] text-[var(--text-primary)]'
+                      : 'text-[var(--text-tertiary)] hover:text-[var(--text-secondary)]'
+                  }`}
+                >
+                  {m === 'paste' ? 'Paste YAML' : 'From git repo'}
+                </button>
+              ))}
+            </div>
+            {composeMode === 'paste' ? (
+              <textarea
+                value={composeYaml}
+                onChange={(e) => setComposeYaml(e.target.value)}
+                spellCheck={false}
+                placeholder={'services:\n  db:\n    image: postgres:16\n  web:\n    image: myapp:latest\n    depends_on: [db]'}
+                className="mono min-h-[320px] flex-1 resize-none bg-[var(--bg-void)] p-4 text-[12.5px] leading-relaxed text-[var(--text-secondary)] outline-none"
+              />
+            ) : (
+              <div className="flex min-h-[320px] flex-1 flex-col gap-3 bg-[var(--bg-void)] p-4">
+                <label className="text-xs text-[var(--text-tertiary)]">
+                  Repository
+                  <input
+                    value={gitRepo}
+                    onChange={(e) => setGitRepo(e.target.value)}
+                    spellCheck={false}
+                    placeholder="owner/repo or https://github.com/owner/repo.git"
+                    className="mono mt-1 w-full rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--bg-base)] px-3 py-2 text-[12.5px] text-[var(--text-secondary)] outline-none focus:border-[var(--accent-primary)]"
+                  />
+                </label>
+                <label className="text-xs text-[var(--text-tertiary)]">
+                  Compose file path <span className="opacity-60">(optional — compose.yaml / docker-compose.yml searched)</span>
+                  <input
+                    value={gitPath}
+                    onChange={(e) => setGitPath(e.target.value)}
+                    spellCheck={false}
+                    placeholder="deploy/compose.yml"
+                    className="mono mt-1 w-full rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--bg-base)] px-3 py-2 text-[12.5px] text-[var(--text-secondary)] outline-none focus:border-[var(--accent-primary)]"
+                  />
+                </label>
+                <label className="text-xs text-[var(--text-tertiary)]">
+                  Branch or commit <span className="opacity-60">(optional)</span>
+                  <input
+                    value={gitRef}
+                    onChange={(e) => setGitRef(e.target.value)}
+                    spellCheck={false}
+                    placeholder="main"
+                    className="mono mt-1 w-full rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--bg-base)] px-3 py-2 text-[12.5px] text-[var(--text-secondary)] outline-none focus:border-[var(--accent-primary)]"
+                  />
+                </label>
+                <p className="text-[11px] text-[var(--text-tertiary)]">
+                  Private repos use your connected git providers for credentials.
+                </p>
+              </div>
+            )}
             {composeError ? (
               <div className="border-t border-[var(--border-subtle)] bg-[var(--error-soft)] px-5 py-2.5 text-xs text-[var(--error)]">
                 {composeError}
@@ -1135,8 +1202,8 @@ export function TemplatesPage() {
               </button>
               <button
                 type="button"
-                onClick={() => composeImportMutation.mutate(composeYaml)}
+                onClick={() => composeImportMutation.mutate()}
-                disabled={!composeYaml.trim() || composeImportMutation.isPending}
+                disabled={(composeMode === 'paste' ? !composeYaml.trim() : !gitRepo.trim()) || composeImportMutation.isPending}
                 className="inline-flex items-center gap-1.5 rounded-[var(--radius-md)] bg-[var(--accent-primary)] px-4 py-2 text-xs font-semibold text-[var(--accent-on)] disabled:opacity-50"
               >
                 {composeImportMutation.isPending ? <Loader2 size={13} className="animate-spin" /> : <FileCode size={13} />}

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

@@ -1056,6 +1056,66 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/services/{id}/terminal": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Interactive terminal (WebSocket)
+         * @description Upgrades to a WebSocket bridged to a `docker exec` PTY in the service's running container (bash if present, else sh). Cookie/bearer auth as usual. Client→server JSON frames: `{"type":"stdin","data":"..."}`, `{"type":"resize","cols":N,"rows":N}`. Server→client frames: `{"type":"stdout","data":"..."}`, `{"type":"exit","code":N}`, `{"type":"error","message":"..."}`.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Switching protocols — WebSocket session established */
+                101: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Service not found or not visible */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Service has no running container */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Docker unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/internal/wake/{id}": {
         parameters: {
             query?: never;
@@ -3183,6 +3243,80 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/templates/import/git": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Import a compose file from a git repository
+         * @description Fetches a compose file out of a git repository and runs it through
+         *     the same conversion as POST /templates/import/compose. `repo`
+         *     accepts a clone URL, ssh remote, or `owner/repo` shorthand —
+         *     connected git providers (including GitHub App installs) supply
+         *     credentials, so private repositories work. `path` defaults to
+         *     `compose.yaml`, `compose.yml`, `docker-compose.yml`, then
+         *     `docker-compose.yaml`; `ref` selects a branch or commit SHA.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description Clone URL, ssh remote, or owner/repo shorthand */
+                        repo: string;
+                        /** @description Repo-relative compose file path (searched by convention when empty) */
+                        path?: string;
+                        /** @description Branch name or 40-char commit SHA */
+                        ref?: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Converted config */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            config?: components["schemas"]["TemplateConfig"];
+                            variables?: Record<string, never>[];
+                            warnings?: string[];
+                        };
+                    };
+                };
+                /** @description Invalid repo reference, compose file missing, or conversion error */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Git fetch failed */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/templates/deploy": {
         parameters: {
             query?: never;
@@ -7917,6 +8051,52 @@ 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;
+                                tags?: string[];
+                            }[];
+                        };
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/agents": {
         parameters: {
             query?: never;
@@ -7999,7 +8179,7 @@ export interface paths {
         };
         /**
          * Update node agent
-         * @description Partial update — accepts any subset of agent fields (name, status, labels, etc.).
+         * @description Partial update — accepts any subset of agent fields (name, status, auto_prune, tags). `tags` sets the node's placement labels; services with placement_tags only schedule onto agents carrying every required tag.
          */
         put: {
             parameters: {
@@ -8303,6 +8483,394 @@ 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}/upgrade": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Upgrade the node agent
+         * @description Enqueues a `self_upgrade` command. The agent downloads its replacement binary from this server's bundled `/agents/download` endpoint, verifies the sha256, atomically swaps the executable, and re-execs itself — the command result reports before the process swaps. The node must be online, and the server must bundle a binary for the node's architecture (`linux-amd64`/`linux-arm64`).
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Node agent ID */
+                    id: components["parameters"]["AgentIdParam"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Upgrade command enqueued */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            command?: Record<string, never>;
+                            platform?: string;
+                            version?: string;
+                        };
+                    };
+                };
+                /** @description Agent not found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Error"];
+                    };
+                };
+                /** @description Node offline or no bundled binary for its architecture */
+                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;
@@ -10445,6 +11013,14 @@ 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. Git-sourced services build on the node itself (build context ships as an agent-token artifact); rollbacks of locally-built tags ship the image via docker save/load. */
+            node_id?: string;
+            /** @description Display name of the pinned node agent (read-only) */
+            node_name?: string;
+            /** @description Replicas are distributed across every online, schedulable node agent (replica i → agents[i mod n]). Mutually exclusive with an explicit node_id pin. */
+            spread?: boolean;
+            /** @description Node tags required for remote placement — auto/spread only consider agents carrying every tag; re-resolved each reconcile. Mutually exclusive with an explicit node_id pin (read-only on responses when a pin is set). */
+            placement_tags?: string[];
             /** @description Computed public URL (published port or domain) */
             public_url?: string;
             /**
@@ -10515,6 +11091,12 @@ 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;
+            /** @description Distribute replicas across every online, schedulable node agent; mutually exclusive with an explicit node_id pin */
+            spread?: boolean;
+            /** @description Restrict remote placement to agents carrying every listed tag; mutually exclusive with an explicit pin or 'local' */
+            placement_tags?: string[];
         };
         UpdateServiceRequest: {
             /** @description Service name */
@@ -10576,6 +11158,12 @@ 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;
+            /** @description Distribute replicas across every online, schedulable node agent; mutually exclusive with an explicit node_id pin — send 'local' first to clear a pin */
+            spread?: boolean;
+            /** @description Restrict remote placement to agents carrying every listed tag; [] clears. Mutually exclusive with a pin or 'local' — clear the pin first */
+            placement_tags?: string[];
         };
         ServiceDomain: {
             /** Format: uuid */
@@ -10883,6 +11471,8 @@ export interface components {
             owner_id?: string | null;
             /** @description Whether a user-created template is published to the public catalog */
             is_public?: boolean;
+            /** @description Catalog origin: absent for local/official templates; "registry" for entries merged from CONTAINR_TEMPLATE_REGISTRY_URL. Deploying a registry template materializes a local copy first. */
+            source?: string;
             /**
              * Format: date-time
              * @description Creation timestamp
@@ -11689,6 +12279,12 @@ 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;
+            /** @description Operator-set placement labels; services with placement_tags require all of them on the target node. */
+            tags?: string[];
             /** Format: date-time */
             last_heartbeat?: string;
             /** Format: date-time */
@@ -11813,6 +12409,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\nbanners list|creatLine 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,25 @@ export type ServiceEntity = {
   staticDir?: string;
   sleepEnabled?: boolean;
   sleepIdleMinutes?: number;
+  nodeId?: string;
+  nodeName?: string;
+  spread?: boolean;
+  placementTags?: string[];
   publicUrl?: string;
 };
 
+export type NodeOption = {
+  id: string;
+  name: string;
+  status: string;
+  tags?: 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;
@@ -181,6 +197,7 @@ export type TemplateEntity = {
   isOfficial: boolean;
   ownerId: string | null;
   isPublic: boolean;
+  source?: string;
   createdAt?: string;
   updatedAt?: string;
 };
@@ -341,6 +358,10 @@ export type NodeAgentEntity = {
   version: string;
   capabilities: AgentCapabilities;
   resources: NodeResources;
+  autoPrune: boolean;
+  schedulable: boolean;
+  tags: string[];
+  metadata: Record<string, unknown>;
   lastHeartbeat?: string;
   createdAt?: string;
   updatedAt?: string;
@@ -677,6 +698,10 @@ 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,
+    spread: service.spread,
+    placementTags: service.placement_tags,
     publicUrl: service.public_url,
   };
 }
@@ -749,6 +774,7 @@ function normalizeTemplate(template: RawServiceTemplate): TemplateEntity | null
     isOfficial: Boolean(template.is_official),
     ownerId: template.owner_id ?? null,
     isPublic: Boolean(template.is_public),
+    source: template.source,
     createdAt: template.created_at,
     updatedAt: template.updated_at,
   };
@@ -1076,6 +1102,10 @@ function normalizeAgent(agent: RawNodeAgent): NodeAgentEntity | null {
       },
     },
     lastHeartbeat: agent.last_heartbeat,
+    autoPrune: agent.auto_prune ?? false,
+    schedulable: agent.schedulable ?? true,
+    tags: Array.isArray(agent.tags) ? agent.tags : [],
+    metadata: (agent.metadata ?? {}) as Record<string, unknown>,
     createdAt: agent.created_at,
     updatedAt: agent.updated_at,
   };
@@ -1114,6 +1144,90 @@ export async function listAgents(): Promise<NodeAgentEntity[]> {
   return normalizeAgentArray(payload.agents);
 }
 
+export async function updateAgent(id: string, body: { name?: string; auto_prune?: boolean; tags?: string[] }): 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 type UpgradeResult = { platform: string; version: string };
+
+export async function upgradeAgent(id: string): Promise<UpgradeResult> {
+  return requestJson<UpgradeResult>(`/agents/${id}/upgrade`, { 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'];
 
@@ -1810,6 +1924,21 @@ export async function importComposeTemplate(composeYaml: string): Promise<Compos
   return { config: payload.config, warnings: payload.warnings ?? [] };
 }
 
+export async function importGitComposeTemplate(
+  repo: string,
+  path: string,
+  ref: string,
+): Promise<ComposeImportResult> {
+  const payload = await requestJson<{ config?: Record<string, unknown>; warnings?: string[] }>(
+    '/templates/import/git',
+    { method: 'POST', body: JSON.stringify({ repo, path: path || undefined, ref: ref || undefined }) },
+  );
+  if (!payload.config || typeof payload.config !== 'object') {
+    throw new ApiError('Git import response is invalid', 500);
+  }
+  return { config: payload.config, warnings: payload.warnings ?? [] };
+}
+
 export type ProjectComposeImportResult = {
   created: Array<{ key: string; kind: string; id: string; name: string; deployment_id?: string }>;
   warnings: string[];

app/frontend/src/lib/dynamic-filter.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import {
+  emptyFilterState,
+  FilterEngine,
+  type FilterConfig,
+} from '@/lib/dynamic-filter';
+
+interface Row {
+  status: string;
+  name: string;
+  labels: string[];
+  createdAt: string;
+}
+
+const ROWS: Row[] = [
+  { status: 'success', name: 'web-api', labels: ['prod'], createdAt: new Date().toISOString() },
+  { status: 'failed', name: 'worker', labels: [], createdAt: '2020-01-01T00:00:00Z' },
+  { status: 'running', name: 'web-admin', labels: ['prod', 'canary'], createdAt: '2020-06-01T00:00:00Z' },
+];
+
+const SCHEMA: FilterConfig<Row>[] = [
+  { key: 'q', label: 'Search', type: 'search', searchFields: ['name'] },
+  { key: 'status', label: 'Status', type: 'select' },
+  { key: 'labels', label: 'Labels', type: 'multiselect' },
+  { key: 'createdAt', label: 'Time', type: 'date-range' },
+];
+
+const f = (over: Partial<Record<string, unknown>>) => ({
+  ...emptyFilterState(SCHEMA),
+  ...over,
+});
+
+describe('FilterEngine', () => {
+  it('passes everything on an empty filter state', () => {
+    expect(new FilterEngine(ROWS, SCHEMA).apply(f({}))).toHaveLength(3);
+  });
+
+  it('searches across configured fields case-insensitively', () => {
+    const engine = new FilterEngine(ROWS, SCHEMA);
+    expect(engine.apply(f({ q: 'WEB' })).map((r) => r.name)).toEqual(['web-api', 'web-admin']);
+    expect(engine.apply(f({ q: 'worker' }))).toHaveLength(1);
+  });
+
+  it('select matches exactly and "all" is a no-op', () => {
+    const engine = new FilterEngine(ROWS, SCHEMA);
+    expect(engine.apply(f({ status: 'failed' }))).toHaveLength(1);
+    expect(engine.apply(f({ status: 'all' }))).toHaveLength(3);
+  });
+
+  it('multiselect intersects array values', () => {
+    const engine = new FilterEngine(ROWS, SCHEMA);
+    expect(engine.apply(f({ labels: ['canary'] })).map((r) => r.name)).toEqual(['web-admin']);
+  });
+
+  it('date-range bounds by preset', () => {
+    const engine = new FilterEngine(ROWS, SCHEMA);
+    expect(engine.apply(f({ createdAt: 'today' })).map((r) => r.name)).toEqual(['web-api']);
+    expect(engine.apply(f({ createdAt: 'all' }))).toHaveLength(3);
+  });
+
+  it('combines filters conjunctively', () => {
+    const engine = new FilterEngine(ROWS, SCHEMA);
+    expect(engine.apply(f({ q: 'web', status: 'running' })).map((r) => r.name)).toEqual(['web-admin']);
+  });
+
+  it('derives options with counts from data', () => {
+    const opts = new FilterEngine(ROWS, SCHEMA).options().find((c) => c.key === 'status');
+    expect(opts?.options?.find((o) => o.value === 'success')?.count).toBe(1);
+    expect(opts?.options?.map((o) => o.value).sort()).toEqual(['failed', 'running', 'success']);
+  });
+
+  it('counts active filters and lists them with raw + display values', () => {
+    const engine = new FilterEngine(ROWS, SCHEMA);
+    const state = f({ status: 'failed', q: 'w' });
+    expect(engine.activeCount(state)).toBe(2);
+    const active = engine.active(state);
+    expect(active.find((a) => a.key === 'status')).toMatchObject({ value: 'failed', displayValue: 'Failed' });
+    expect(active.find((a) => a.key === 'q')).toMatchObject({ displayValue: 'w' });
+  });
+});

app/frontend/src/lib/dynamic-filter.ts

@@ -0,0 +1,208 @@
+// Dynamic filter framework — typed filter configs → client-side filtering
+// with optional URL-state sync. Port of dflow's filter.utils pattern,
+// adapted to Containr (no external date lib, searchParams-driven).
+//
+// A page declares a FilterConfig<T>[] schema, passes fetched data +
+// schema to useDynamicFilter(), and renders <FilterBar/>. Filter state
+// lives in the URL when `urlSync` is on, so filtered views are
+// shareable links.
+
+export type FilterType =
+  | 'search'
+  | 'select'
+  | 'multiselect'
+  | 'boolean'
+  | 'date-range'
+  | 'status';
+
+export interface FilterOption {
+  value: string;
+  label: string;
+  count?: number;
+}
+
+export interface FilterConfig<T> {
+  key: string;
+  label: string;
+  type: FilterType;
+  options?: FilterOption[];
+  /** fields searched by type 'search' (defaults to [key]) */
+  searchFields?: (keyof T & string)[];
+  /** custom value accessor (defaults to item[key]) */
+  accessor?: (item: T) => unknown;
+}
+
+export type FilterState = Record<string, unknown>;
+
+const EMPTY: Record<FilterType, unknown> = {
+  search: '',
+  select: 'all',
+  multiselect: [],
+  boolean: [],
+  'date-range': 'all',
+  status: [],
+};
+
+export function emptyValueFor(type: FilterType): unknown {
+  return structuredClone(EMPTY[type]);
+}
+
+export function emptyFilterState<T>(schema: FilterConfig<T>[]): FilterState {
+  const state: FilterState = {};
+  for (const c of schema) state[c.key] = structuredClone(EMPTY[c.type]);
+  return state;
+}
+
+function accessorOf<T>(config: FilterConfig<T>): (item: T) => unknown {
+  if (config.accessor) return config.accessor;
+  return (item) => (item as Record<string, unknown>)[config.key];
+}
+
+export class FilterEngine<T> {
+  private data: T[];
+  private schema: FilterConfig<T>[];
+
+  constructor(data: T[], schema: FilterConfig<T>[]) {
+    this.data = data;
+    this.schema = schema;
+  }
+
+  /** Fill in option lists (with counts) for configs that didn't declare them. */
+  options(): FilterConfig<T>[] {
+    return this.schema.map((config) => {
+      if (config.options?.length) return config;
+      const counts = new Map<string, number>();
+      for (const item of this.data) {
+        const v = accessorOf(config)(item);
+        for (const each of Array.isArray(v) ? v : [v]) {
+          if (each != null && each !== '') {
+            const key = String(each);
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+          }
+        }
+      }
+      const options = [...counts.entries()]
+        .map(([value, count]) => ({ value, label: formatLabel(value), count }))
+        .sort((a, b) => b.count! - a.count!);
+      return { ...config, options };
+    });
+  }
+
+  apply(filters: FilterState): T[] {
+    return this.data.filter((item) =>
+      this.schema.every((config) => {
+        const value = filters[config.key];
+        if (value == null || value === '' || value === 'all') return true;
+        if (Array.isArray(value) && value.length === 0) return true;
+        return this.evaluate(item, config, value);
+      }),
+    );
+  }
+
+  private evaluate(item: T, config: FilterConfig<T>, value: unknown): boolean {
+    const itemValue = accessorOf(config)(item);
+    switch (config.type) {
+      case 'search': {
+        const term = String(value).toLowerCase();
+        const fields = config.searchFields ?? [config.key as keyof T & string];
+        return fields.some((f) =>
+          String((item as Record<string, unknown>)[f] ?? '').toLowerCase().includes(term),
+        );
+      }
+      case 'select':
+        return String(itemValue) === String(value);
+      case 'multiselect':
+      case 'status': {
+        const values = value as string[];
+        if (Array.isArray(itemValue)) return itemValue.some((v) => values.includes(String(v)));
+        return values.includes(String(itemValue));
+      }
+      case 'boolean': {
+        const values = value as string[];
+        return values.includes(String(Boolean(itemValue)));
+      }
+      case 'date-range':
+        return dateInRange(itemValue, String(value));
+      default:
+        return true;
+    }
+  }
+
+  activeCount(filters: FilterState): number {
+    let n = 0;
+    for (const c of this.schema) {
+      const v = filters[c.key];
+      if (v == null || v === '' || v === 'all') continue;
+      n += Array.isArray(v) ? v.length : 1;
+    }
+    return n;
+  }
+
+  active(filters: FilterState): { key: string; label: string; value: string; displayValue: string }[] {
+    const out: { key: string; label: string; value: string; displayValue: string }[] = [];
+    const opts = this.options();
+    for (const c of this.schema) {
+      const v = filters[c.key];
+      if (v == null || v === '' || v === 'all') continue;
+      const optFor = (raw: unknown) => {
+        if (c.type === 'search') return String(raw);
+        if (c.type === 'date-range') {
+          return DATE_RANGE_OPTIONS.find((o) => o.value === raw)?.label ?? String(raw);
+        }
+        return (
+          opts.find((o) => o.key === c.key)?.options?.find((o) => o.value === raw)?.label ??
+          formatLabel(String(raw))
+        );
+      };
+      if (Array.isArray(v)) {
+        for (const each of v) {
+          out.push({ key: c.key, label: c.label, value: String(each), displayValue: optFor(each) });
+        }
+      } else {
+        out.push({ key: c.key, label: c.label, value: String(v), displayValue: optFor(v) });
+      }
+    }
+    return out;
+  }
+}
+
+function formatLabel(value: string): string {
+  if (value === 'true') return 'Yes';
+  if (value === 'false') return 'No';
+  return value.charAt(0).toUpperCase() + value.slice(1).replace(/[_-]/g, ' ');
+}
+
+function dateInRange(itemValue: unknown, range: string): boolean {
+  if (!itemValue || range === 'all') return true;
+  const date = new Date(String(itemValue));
+  if (Number.isNaN(date.getTime())) return false;
+  const now = new Date();
+  let boundary: Date;
+  switch (range) {
+    case 'today':
+      boundary = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+      break;
+    case 'week': {
+      const day = (now.getDay() + 6) % 7; // monday start
+      boundary = new Date(now.getFullYear(), now.getMonth(), now.getDate() - day);
+      break;
+    }
+    case 'month':
+      boundary = new Date(now.getFullYear(), now.getMonth(), 1);
+      break;
+    case '30d':
+      boundary = new Date(now.getTime() - 30 * 86400000);
+      break;
+    default:
+      return true;
+  }
+  return date >= boundary;
+}
+
+export const DATE_RANGE_OPTIONS: FilterOption[] = [
+  { value: 'all', label: 'All time' },
+  { value: 'today', label: 'Today' },
+  { value: 'week', label: 'This week' },
+  { value: 'month', label: 'This month' },
+  { value: '30d', label: 'Last 30 days' },
+];

app/frontend/src/lib/use-dynamic-filter.ts

@@ -0,0 +1,104 @@
+import { useCallback, useMemo } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import {
+  emptyFilterState,
+  emptyValueFor,
+  FilterEngine,
+  type FilterConfig,
+  type FilterState,
+} from '@/lib/dynamic-filter';
+
+// Filter state lives in `?f.<key>=...` search params — filtered views are
+// shareable links. Arrays join with commas.
+
+function stateFromParams<T>(schema: FilterConfig<T>[], params: URLSearchParams): FilterState {
+  const state = emptyFilterState(schema);
+  for (const c of schema) {
+    const raw = params.get(`f.${c.key}`);
+    if (raw == null) continue;
+    switch (c.type) {
+      case 'multiselect':
+      case 'boolean':
+      case 'status':
+        state[c.key] = raw.split(',').filter(Boolean);
+        break;
+      default:
+        state[c.key] = raw;
+    }
+  }
+  return state;
+}
+
+function stateToParams<T>(schema: FilterConfig<T>[], state: FilterState): URLSearchParams {
+  const params = new URLSearchParams();
+  const empty = emptyFilterState(schema);
+  for (const c of schema) {
+    const v = state[c.key];
+    if (v == null || v === '' || v === 'all') continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    if (JSON.stringify(v) === JSON.stringify(empty[c.key])) continue;
+    params.set(`f.${c.key}`, Array.isArray(v) ? v.join(',') : String(v));
+  }
+  return params;
+}
+
+/** URL-backed filter state — usable before any data is fetched. */
+export function useFilterState<T>(schema: FilterConfig<T>[]) {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const filters = useMemo(() => stateFromParams(schema, searchParams), [schema, searchParams]);
+
+  const setFilters = useCallback(
+    (updater: (prev: FilterState) => FilterState) => {
+      const next = updater(filters);
+      setSearchParams((prev) => {
+        const merged = new URLSearchParams(prev);
+        for (const key of [...merged.keys()]) {
+          if (key.startsWith('f.')) merged.delete(key);
+        }
+        stateToParams(schema, next).forEach((v, k) => merged.set(k, v));
+        return merged;
+      }, { replace: true });
+    },
+    [filters, schema, setSearchParams],
+  );
+
+  const updateFilter = useCallback(
+    (key: string, value: unknown) => setFilters((prev) => ({ ...prev, [key]: value })),
+    [setFilters],
+  );
+  const clearAll = useCallback(
+    () => setFilters(() => emptyFilterState(schema)),
+    [setFilters, schema],
+  );
+  const removeFilter = useCallback(
+    (key: string, rawValue?: string) =>
+      setFilters((prev) => {
+        const v = prev[key];
+        if (Array.isArray(v) && rawValue !== undefined) {
+          return { ...prev, [key]: v.filter((x) => String(x) !== rawValue) };
+        }
+        const config = schema.find((c) => c.key === key);
+        return config ? { ...prev, [key]: emptyValueFor(config.type) } : prev;
+      }),
+    [setFilters, schema],
+  );
+
+  return { filters, updateFilter, removeFilter, clearAll };
+}
+
+/** Full client-side filter: URL state + engine over `data`. */
+export function useDynamicFilter<T>({ data, schema }: { data: T[]; schema: FilterConfig<T>[] }) {
+  const state = useFilterState(schema);
+  const engine = useMemo(() => new FilterEngine(data, schema), [data, schema]);
+
+  return {
+    filteredData: useMemo(() => engine.apply(state.filters), [engine, state.filters]),
+    filters: state.filters,
+    schema: useMemo(() => engine.options(), [engine]),
+    activeCount: useMemo(() => engine.activeCount(state.filters), [engine, state.filters]),
+    active: useMemo(() => engine.active(state.filters), [engine, state.filters]),
+    updateFilter: state.updateFilter,
+    removeFilter: state.removeFilter,
+    clearAll: state.clearAll,
+  };
+}

app/frontend/src/shared/components/FilterBar.tsx

@@ -0,0 +1,147 @@
+import { Search, X } from 'lucide-react';
+import {
+  DATE_RANGE_OPTIONS,
+  type FilterConfig,
+  type FilterState,
+} from '@/lib/dynamic-filter';
+
+const inputClass =
+  'h-9 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] bg-[var(--surface-muted)] text-sm text-[var(--text-primary)] placeholder:text-[var(--text-muted)] focus:border-[var(--accent-primary)] focus:ring-1 focus:ring-[var(--accent-primary)] transition-all';
+
+// Dynamic filter bar — renders a FilterConfig schema as compact controls.
+// State is owned by useDynamicFilter (URL-synced); this is a pure view.
+
+export function FilterBar<T>({
+  schema,
+  filters,
+  activeCount,
+  active,
+  updateFilter,
+  removeFilter,
+  clearAll,
+}: {
+  schema: FilterConfig<T>[];
+  filters: FilterState;
+  activeCount: number;
+  active: { key: string; label: string; value: string; displayValue: string }[];
+  updateFilter: (key: string, value: unknown) => void;
+  removeFilter: (key: string, rawValue?: string) => void;
+  clearAll: () => void;
+}) {
+  return (
+    <div className="mb-5">
+      <div className="flex flex-wrap items-end gap-3">
+        {schema.map((config) => {
+          const value = filters[config.key];
+          switch (config.type) {
+            case 'search':
+              return (
+                <div key={config.key} className="relative">
+                  <Search
+                    size={13}
+                    className="absolute left-3 top-1/2 -translate-y-1/2 text-[var(--text-muted)]"
+                  />
+                  <input
+                    value={String(value ?? '')}
+                    onChange={(e) => updateFilter(config.key, e.target.value)}
+                    placeholder={`Search ${config.label.toLowerCase()}…`}
+                    className={`${inputClass} w-56 pl-8`}
+                    aria-label={config.label}
+                  />
+                </div>
+              );
+            case 'select':
+            case 'date-range': {
+              const options =
+                config.type === 'date-range'
+                  ? DATE_RANGE_OPTIONS
+                  : [{ value: 'all', label: `All ${config.label.toLowerCase()}` }, ...(config.options ?? [])];
+              return (
+                <select
+                  key={config.key}
+                  value={String(value ?? 'all')}
+                  onChange={(e) => updateFilter(config.key, e.target.value)}
+                  className={`${inputClass} w-40`}
+                  aria-label={config.label}
+                >
+                  {options.map((o) => (
+                    <option key={o.value} value={o.value}>
+                      {o.count != null ? `${o.label} (${o.count})` : o.label}
+                    </option>
+                  ))}
+                </select>
+              );
+            }
+            case 'multiselect':
+            case 'boolean':
+            case 'status': {
+              const selected = Array.isArray(value) ? (value as string[]) : [];
+              const options =
+                config.type === 'boolean'
+                  ? [
+                      { value: 'true', label: 'Yes' },
+                      { value: 'false', label: 'No' },
+                    ]
+                  : (config.options ?? []);
+              return (
+                <div key={config.key} className="flex flex-wrap items-center gap-1.5">
+                  <span className="text-[10px] font-medium uppercase tracking-wider text-[var(--text-muted)]">
+                    {config.label}:
+                  </span>
+                  {options.map((o) => {
+                    const on = selected.includes(o.value);
+                    return (
+                      <button
+                        key={o.value}
+                        onClick={() =>
+                          updateFilter(
+                            config.key,
+                            on ? selected.filter((s) => s !== o.value) : [...selected, o.value],
+                          )
+                        }
+                        className={`h-7 px-2.5 rounded-[var(--radius-sm)] text-xs font-medium border transition-colors ${
+                          on
+                            ? 'bg-[var(--accent-primary-soft)] border-[var(--accent-primary)]/40 text-[var(--accent-primary)]'
+                            : 'border-[var(--border-subtle)] text-[var(--text-secondary)] hover:border-[var(--border-default)]'
+                        }`}
+                      >
+                        {o.label}
+                        {o.count != null && <span className="ml-1 opacity-60">{o.count}</span>}
+                      </button>
+                    );
+                  })}
+                </div>
+              );
+            }
+            default:
+              return null;
+          }
+        })}
+        {activeCount > 0 && (
+          <button
+            onClick={clearAll}
+            className="h-9 px-3 rounded-[var(--radius-md)] border border-[var(--border-subtle)] text-xs font-medium text-[var(--text-secondary)] hover:border-[var(--border-default)] transition-colors"
+          >
+            Clear ({activeCount})
+          </button>
+        )}
+      </div>
+
+      {active.length > 0 && (
+        <div className="flex flex-wrap items-center gap-1.5 mt-3">
+          {active.map((a, i) => (
+            <button
+              key={`${a.key}-${a.value}-${i}`}
+              onClick={() => removeFilter(a.key, a.value)}
+              className="group inline-flex items-center gap-1.5 h-6 px-2 rounded-[var(--radius-sm)] bg-[var(--accent-primary-soft)] text-[11px] font-medium text-[var(--accent-primary)]"
+            >
+              <span className="opacity-70">{a.label}</span>
+              {a.displayValue}
+              <X size={11} className="opacity-50 group-hover:opacity-100" />
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

app/frontend/src/shared/components/index.ts

@@ -11,3 +11,4 @@ export * from './StatusBadge';
 export { useToast } from '../hooks/use-toast';
 export type { ToastType, ToastContextValue } from '../hooks/use-toast';
 export * from './BrandWordmark';
+export * from './FilterBar';

app/mobile/src/api.ts

@@ -68,6 +68,36 @@ export interface Template {
   icon?: string;
 }
 
+export interface Variable {
+  id?: string;
+  key: string;
+  value: string;
+  is_secret: boolean;
+}
+
+export interface ServiceDomain {
+  id: string;
+  domain: string;
+  is_default: boolean;
+  cert_type?: string;
+  cert_status?: string;
+}
+
+export interface AppNotification {
+  id: string;
+  kind: string;
+  title: string;
+  body?: string;
+  resource_type?: string;
+  resource_id?: string;
+  read_at?: string | null;
+  created_at?: string;
+}
+
+// Masked value the API returns for secret variables; echoing it back on
+// update preserves the stored ciphertext.
+export const MASKED_SECRET = '********';
+
 export class ApiError extends Error {
   constructor(
     public status: number,
@@ -145,6 +175,69 @@ export class Api {
     return this.req<EnvCheck>('GET', `/services/${id}/env-check`);
   }
 
+  serviceVariables(id: string) {
+    return this.req<{ variables: Variable[] }>('GET', `/services/${id}/variables`).then(
+      (r) => r.variables ?? [],
+    );
+  }
+
+  updateVariables(id: string, variables: { key: string; value: string; is_secret: boolean }[]) {
+    return this.req<unknown>('PUT', `/services/${id}/variables`, { variables });
+  }
+
+  serviceDomains(id: string) {
+    return this.req<{ domains: ServiceDomain[] }>('GET', `/services/${id}/domains`).then(
+      (r) => r.domains ?? [],
+    );
+  }
+
+  addDomain(id: string, domain: string) {
+    return this.req<unknown>('POST', `/services/${id}/domains`, { domain });
+  }
+
+  deleteDomain(id: string, domainId: string) {
+    return this.req<unknown>('DELETE', `/services/${id}/domains/${domainId}`);
+  }
+
+  setDefaultDomain(id: string, domainId: string) {
+    return this.req<unknown>('POST', `/services/${id}/domains/${domainId}/default`);
+  }
+
+  updateService(
+    id: string,
+    patch: Partial<{
+      name: string;
+      command: string;
+      replicas: number;
+      port: number;
+      domain: string;
+      restart_policy: string;
+      healthcheck_path: string;
+      cpu: string;
+      memory: string;
+      sleep_enabled: boolean;
+      sleep_idle_minutes: number;
+      maintenance_mode: boolean;
+    }>,
+  ) {
+    return this.req<unknown>('PUT', `/services/${id}`, patch);
+  }
+
+  notifications() {
+    return this.req<{ notifications: AppNotification[]; unread: number }>(
+      'GET',
+      '/notifications?limit=50',
+    );
+  }
+
+  markNotificationRead(id: string) {
+    return this.req<unknown>('POST', `/notifications/${id}/read`);
+  }
+
+  markAllNotificationsRead() {
+    return this.req<unknown>('POST', '/notifications/read-all');
+  }
+
   serviceDeployments(id: string) {
     return this.req<{ deployments: Deployment[] }>(
       'GET',

app/mobile/src/app/(tabs)/_layout.tsx

@@ -1,9 +1,19 @@
 import React from 'react';
 import { Tabs } from 'expo-router';
 import { Ionicons } from '@expo/vector-icons';
+import { useQuery } from '@tanstack/react-query';
+import { useApi } from '../../session';
 import { colors } from '../../theme';
 
 export default function TabsLayout() {
+  const api = useApi();
+  const notifs = useQuery({
+    queryKey: ['notifications'],
+    queryFn: () => api.notifications(),
+    refetchInterval: 60_000,
+  });
+  const unread = notifs.data?.unread ?? 0;
+
   return (
     <Tabs
       screenOptions={{
@@ -41,6 +51,16 @@ export default function TabsLayout() {
           ),
         }}
       />
+      <Tabs.Screen
+        name="notifications"
+        options={{
+          title: 'Alerts',
+          tabBarBadge: unread > 0 ? unread : undefined,
+          tabBarIcon: ({ color, size }) => (
+            <Ionicons name="notifications-outline" size={size} color={color} />
+          ),
+        }}
+      />
       <Tabs.Screen
         name="settings"
         options={{

app/mobile/src/app/(tabs)/notifications.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import { FlatList, RefreshControl, StyleSheet, Text, View } from 'react-native';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useApi } from '../../session';
+import { colors } from '../../theme';
+import { relTime } from '../../time';
+import { ActionButton, Card, Empty, ErrorBox, Loading } from '../../components';
+
+const KIND_COLOR: Record<string, string> = {
+  deployment_failed: colors.err,
+  deployment: colors.accent,
+  alert: colors.warn,
+  scale: colors.info,
+};
+
+export default function Notifications() {
+  const api = useApi();
+  const qc = useQueryClient();
+
+  const notifs = useQuery({
+    queryKey: ['notifications'],
+    queryFn: () => api.notifications(),
+    refetchInterval: 30_000,
+  });
+
+  const markAll = useMutation({
+    mutationFn: () => api.markAllNotificationsRead(),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['notifications'] }),
+  });
+  const markRead = useMutation({
+    mutationFn: (id: string) => api.markNotificationRead(id),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['notifications'] }),
+  });
+
+  if (notifs.isLoading) return <Loading />;
+  if (notifs.error) return <ErrorBox error={notifs.error} />;
+
+  const items = notifs.data?.notifications ?? [];
+  const unread = notifs.data?.unread ?? 0;
+
+  return (
+    <FlatList
+      style={styles.root}
+      contentContainerStyle={{ padding: 16 }}
+      refreshControl={
+        <RefreshControl
+          refreshing={notifs.isRefetching}
+          onRefresh={() => notifs.refetch()}
+          tintColor={colors.accent}
+        />
+      }
+      ListHeaderComponent={
+        unread > 0 ? (
+          <ActionButton
+            label={`Mark all read (${unread})`}
+            disabled={markAll.isPending}
+            onPress={() => markAll.mutate()}
+          />
+        ) : null
+      }
+      ListEmptyComponent={<Empty text="No notifications" />}
+      data={items}
+      keyExtractor={(n) => n.id}
+      renderItem={({ item }) => {
+        const isUnread = !item.read_at;
+        const dot = KIND_COLOR[item.kind] ?? colors.accent;
+        return (
+          <Card
+            style={isUnread ? { borderColor: colors.accent } : undefined}
+          >
+            <View style={styles.row}>
+              <View style={[styles.dot, { backgroundColor: isUnread ? dot : colors.border }]} />
+              <View style={{ flex: 1 }}>
+                <Text style={[styles.title, !isUnread && { color: colors.textDim }]}>
+                  {item.title}
+                </Text>
+                {item.body ? <Text style={styles.body}>{item.body}</Text> : null}
+                <Text style={styles.meta}>
+                  {item.kind}
+                  {item.created_at ? ` · ${relTime(item.created_at)}` : ''}
+                </Text>
+              </View>
+              {isUnread ? (
+                <Text
+                  style={styles.markRead}
+                  onPress={() => markRead.mutate(item.id)}
+                >
+                  Mark read
+                </Text>
+              ) : null}
+            </View>
+          </Card>
+        );
+      }}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  row: { flexDirection: 'row', alignItems: 'flex-start' },
+  dot: { width: 8, height: 8, borderRadius: 4, marginTop: 5, marginRight: 10 },
+  title: { color: colors.text, fontSize: 15, fontWeight: '600' },
+  body: { color: colors.textDim, fontSize: 13, marginTop: 4, lineHeight: 18 },
+  meta: { color: colors.textDim, fontSize: 11, marginTop: 6 },
+  markRead: { color: colors.accent, fontSize: 12, fontWeight: '600', marginLeft: 8 },
+});

app/mobile/src/app/_layout.tsx

@@ -37,6 +37,9 @@ function AuthGate() {
         <Stack.Screen name="project/[id]" options={{ title: 'Project' }} />
         <Stack.Screen name="service/[id]" options={{ title: 'Service' }} />
         <Stack.Screen name="service/logs" options={{ title: 'Logs' }} />
+        <Stack.Screen name="service/variables" options={{ title: 'Variables' }} />
+        <Stack.Screen name="service/domains" options={{ title: 'Domains' }} />
+        <Stack.Screen name="service/settings" options={{ title: 'Service settings' }} />
       </Stack.Protected>
       <Stack.Screen name="login" options={{ headerShown: false }} />
     </Stack>

app/mobile/src/app/service/[id].tsx

@@ -11,6 +11,7 @@ import {
   Empty,
   ErrorBox,
   Loading,
+  Row,
   SectionTitle,
   StatusBadge,
 } from '../../components';
@@ -142,6 +143,28 @@ export default function ServiceDetail() {
         />
       </View>
 
+      <SectionTitle>Manage</SectionTitle>
+      <Card>
+        <Row
+          title="Variables"
+          subtitle="Environment and secrets"
+          onPress={() =>
+            router.push(`/service/variables?id=${s.id}&name=${encodeURIComponent(s.name)}`)
+          }
+        />
+        <Row
+          title="Domains"
+          subtitle={s.domain ?? 'Hostnames routed to this service'}
+          onPress={() => router.push(`/service/domains?id=${s.id}`)}
+        />
+        <Row
+          title="Scale & sleep"
+          subtitle={`${s.replicas ?? 1} replica${(s.replicas ?? 1) === 1 ? '' : 's'}` +
+            (s.sleep_enabled ? ` · sleeps after ${s.sleep_idle_minutes}m idle` : '')}
+          onPress={() => router.push(`/service/settings?id=${s.id}`)}
+        />
+      </Card>
+
       {s.sleep_enabled ? (
         <Text style={styles.hint}>
           Sleep enabled — scales to zero after {s.sleep_idle_minutes}m idle, wakes on traffic.

app/mobile/src/app/service/domains.tsx

@@ -0,0 +1,151 @@
+import React, { useState } from 'react';
+import {
+  Alert,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { Ionicons } from '@expo/vector-icons';
+import { useLocalSearchParams } from 'expo-router';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useApi } from '../../session';
+import { colors } from '../../theme';
+import { ActionButton, Card, Empty, ErrorBox, Loading } from '../../components';
+
+export default function ServiceDomains() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  const api = useApi();
+  const qc = useQueryClient();
+  const [newDomain, setNewDomain] = useState('');
+
+  const domains = useQuery({
+    queryKey: ['domains', id],
+    queryFn: () => api.serviceDomains(id!),
+    enabled: !!id,
+  });
+
+  const invalidate = () => {
+    qc.invalidateQueries({ queryKey: ['domains', id] });
+    qc.invalidateQueries({ queryKey: ['service', id] });
+  };
+  const onErr = (e: unknown) =>
+    Alert.alert('Failed', e instanceof Error ? e.message : String(e));
+
+  const add = useMutation({
+    mutationFn: (d: string) => api.addDomain(id!, d),
+    onSuccess: () => {
+      setNewDomain('');
+      invalidate();
+    },
+    onError: onErr,
+  });
+  const del = useMutation({
+    mutationFn: (domainId: string) => api.deleteDomain(id!, domainId),
+    onSuccess: invalidate,
+    onError: onErr,
+  });
+  const makeDefault = useMutation({
+    mutationFn: (domainId: string) => api.setDefaultDomain(id!, domainId),
+    onSuccess: invalidate,
+    onError: onErr,
+  });
+
+  if (domains.isLoading) return <Loading />;
+  if (domains.error) return <ErrorBox error={domains.error} />;
+
+  const submit = () => {
+    const d = newDomain.trim().toLowerCase();
+    if (d) add.mutate(d);
+  };
+
+  return (
+    <ScrollView style={styles.root} contentContainerStyle={{ padding: 16 }}>
+      <Text style={styles.hint}>
+        Hostnames routed to this service. The default domain is the one shown on cards and used
+        for generated links.
+      </Text>
+
+      {domains.data?.length === 0 ? <Empty text="No domains configured" /> : null}
+      {(domains.data ?? []).map((d) => (
+        <Card key={d.id}>
+          <View style={styles.row}>
+            <View style={{ flex: 1 }}>
+              <Text style={styles.domain}>{d.domain}</Text>
+              <Text style={styles.meta}>
+                {d.is_default ? 'default · ' : ''}
+                {d.cert_status ? `tls: ${d.cert_status}` : 'tls pending'}
+              </Text>
+            </View>
+            {!d.is_default ? (
+              <TouchableOpacity
+                onPress={() => makeDefault.mutate(d.id)}
+                hitSlop={8}
+                style={styles.iconBtn}
+              >
+                <Ionicons name="star-outline" size={20} color={colors.accent} />
+              </TouchableOpacity>
+            ) : (
+              <Ionicons name="star" size={20} color={colors.warn} style={styles.iconBtn} />
+            )}
+            <TouchableOpacity
+              onPress={() =>
+                Alert.alert('Remove domain', `Detach ${d.domain} from this service?`, [
+                  { text: 'Cancel', style: 'cancel' },
+                  { text: 'Remove', style: 'destructive', onPress: () => del.mutate(d.id) },
+                ])
+              }
+              hitSlop={8}
+              style={styles.iconBtn}
+            >
+              <Ionicons name="trash-outline" size={18} color={colors.err} />
+            </TouchableOpacity>
+          </View>
+        </Card>
+      ))}
+
+      <View style={styles.addRow}>
+        <TextInput
+          style={styles.input}
+          value={newDomain}
+          onChangeText={setNewDomain}
+          placeholder="app.example.com"
+          placeholderTextColor={colors.textDim}
+          autoCapitalize="none"
+          autoCorrect={false}
+          keyboardType="url"
+          onSubmitEditing={submit}
+        />
+        <ActionButton
+          label={add.isPending ? '…' : 'Add'}
+          kind="primary"
+          disabled={add.isPending || newDomain.trim() === ''}
+          onPress={submit}
+        />
+      </View>
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  hint: { color: colors.textDim, fontSize: 12, marginBottom: 12, lineHeight: 17 },
+  row: { flexDirection: 'row', alignItems: 'center' },
+  domain: { color: colors.text, fontSize: 15, fontWeight: '600' },
+  meta: { color: colors.textDim, fontSize: 12, marginTop: 3 },
+  iconBtn: { padding: 6, marginLeft: 10 },
+  addRow: { flexDirection: 'row', alignItems: 'center', marginTop: 8 },
+  input: {
+    flex: 1,
+    color: colors.text,
+    backgroundColor: colors.surface,
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: 10,
+    padding: 12,
+    marginRight: 8,
+    fontSize: 14,
+  },
+});

app/mobile/src/app/service/settings.tsx

@@ -0,0 +1,174 @@
+import React, { useState } from 'react';
+import {
+  Alert,
+  ScrollView,
+  StyleSheet,
+  Switch,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { useLocalSearchParams } from 'expo-router';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useApi } from '../../session';
+import { Service } from '../../api';
+import { colors } from '../../theme';
+import { ActionButton, Card, ErrorBox, Loading, SectionTitle } from '../../components';
+
+export default function ServiceSettings() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  const api = useApi();
+
+  const service = useQuery({
+    queryKey: ['service', id],
+    queryFn: () => api.service(id!),
+    enabled: !!id,
+  });
+
+  if (service.isLoading) return <Loading />;
+  if (service.error || !service.data) {
+    return <ErrorBox error={service.error ?? new Error('Not found')} />;
+  }
+
+  // Form mounts once data exists; its state initializes from the fetch.
+  return <Form serviceId={id!} initial={service.data} />;
+}
+
+function Form({ serviceId, initial }: { serviceId: string; initial: Service }) {
+  const api = useApi();
+  const qc = useQueryClient();
+  const [replicas, setReplicas] = useState(initial.replicas ?? 1);
+  const [port, setPort] = useState(String(initial.port ?? 0));
+  const [sleepEnabled, setSleepEnabled] = useState(!!initial.sleep_enabled);
+  const [sleepMinutes, setSleepMinutes] = useState(
+    String(initial.sleep_idle_minutes || 30),
+  );
+
+  const save = useMutation({
+    mutationFn: () =>
+      api.updateService(serviceId, {
+        replicas,
+        port: parseInt(port, 10) || 0,
+        sleep_enabled: sleepEnabled,
+        sleep_idle_minutes: Math.min(1440, Math.max(1, parseInt(sleepMinutes, 10) || 30)),
+      }),
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['service', serviceId] });
+      qc.invalidateQueries({ queryKey: ['services'] });
+      Alert.alert('Saved', 'Changes apply on the next deploy.');
+    },
+    onError: (e) => Alert.alert('Save failed', e instanceof Error ? e.message : String(e)),
+  });
+
+  const clampReplicas = (n: number) => Math.min(16, Math.max(0, n));
+
+  return (
+    <ScrollView style={styles.root} contentContainerStyle={{ padding: 16 }}>
+      <SectionTitle>Scaling</SectionTitle>
+      <Card>
+        <View style={styles.stepRow}>
+          <View style={{ flex: 1 }}>
+            <Text style={styles.label}>Replicas</Text>
+            <Text style={styles.sub}>Containers run per deploy; 0 parks the service.</Text>
+          </View>
+          <TouchableOpacity
+            style={styles.stepBtn}
+            onPress={() => setReplicas((r) => clampReplicas(r - 1))}
+            disabled={replicas <= 0}
+          >
+            <Text style={styles.stepText}>−</Text>
+          </TouchableOpacity>
+          <Text style={styles.stepValue}>{replicas}</Text>
+          <TouchableOpacity
+            style={styles.stepBtn}
+            onPress={() => setReplicas((r) => clampReplicas(r + 1))}
+            disabled={replicas >= 16}
+          >
+            <Text style={styles.stepText}>+</Text>
+          </TouchableOpacity>
+        </View>
+        <View style={styles.field}>
+          <Text style={styles.label}>Container port</Text>
+          <TextInput
+            style={styles.input}
+            value={port}
+            onChangeText={setPort}
+            keyboardType="number-pad"
+            placeholder="0 = none"
+            placeholderTextColor={colors.textDim}
+          />
+        </View>
+      </Card>
+
+      <SectionTitle>Scale to zero</SectionTitle>
+      <Card>
+        <View style={styles.switchRow}>
+          <View style={{ flex: 1 }}>
+            <Text style={styles.label}>Sleep when idle</Text>
+            <Text style={styles.sub}>Scales to zero after idle; incoming traffic wakes it.</Text>
+          </View>
+          <Switch
+            value={sleepEnabled}
+            onValueChange={setSleepEnabled}
+            trackColor={{ false: colors.border, true: colors.accentDim }}
+            thumbColor={sleepEnabled ? colors.accent : colors.textDim}
+          />
+        </View>
+        {sleepEnabled ? (
+          <View style={styles.field}>
+            <Text style={styles.label}>Idle minutes before sleep (1–1440)</Text>
+            <TextInput
+              style={styles.input}
+              value={sleepMinutes}
+              onChangeText={setSleepMinutes}
+              keyboardType="number-pad"
+              placeholder="30"
+              placeholderTextColor={colors.textDim}
+            />
+          </View>
+        ) : null}
+      </Card>
+
+      <ActionButton
+        label={save.isPending ? 'Saving…' : 'Save settings'}
+        kind="primary"
+        disabled={save.isPending}
+        onPress={() => save.mutate()}
+      />
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  label: { color: colors.text, fontSize: 15, fontWeight: '600' },
+  sub: { color: colors.textDim, fontSize: 12, marginTop: 2 },
+  stepRow: { flexDirection: 'row', alignItems: 'center' },
+  stepBtn: {
+    width: 38,
+    height: 38,
+    borderRadius: 8,
+    backgroundColor: colors.surfaceAlt,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  stepText: { color: colors.text, fontSize: 20, fontWeight: '700' },
+  stepValue: {
+    color: colors.text,
+    fontSize: 18,
+    fontWeight: '700',
+    minWidth: 36,
+    textAlign: 'center',
+  },
+  switchRow: { flexDirection: 'row', alignItems: 'center' },
+  field: { marginTop: 12 },
+  input: {
+    color: colors.text,
+    backgroundColor: colors.surfaceAlt,
+    borderRadius: 8,
+    padding: 10,
+    marginTop: 6,
+    fontSize: 14,
+  },
+});

app/mobile/src/app/service/variables.tsx

@@ -0,0 +1,187 @@
+import React, { useState } from 'react';
+import {
+  Alert,
+  KeyboardAvoidingView,
+  Platform,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  TouchableOpacity,
+  View,
+} from 'react-native';
+import { Ionicons } from '@expo/vector-icons';
+import { useLocalSearchParams } from 'expo-router';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useApi } from '../../session';
+import { MASKED_SECRET, Variable } from '../../api';
+import { colors } from '../../theme';
+import { ActionButton, Card, Empty, ErrorBox, Loading } from '../../components';
+
+interface Row {
+  key: string;
+  value: string;
+  is_secret: boolean;
+  // Secret untouched by the user — submits the masked placeholder so the
+  // server keeps the stored ciphertext.
+  keepSecret: boolean;
+}
+
+export default function ServiceVariables() {
+  const { id, name } = useLocalSearchParams<{ id: string; name?: string }>();
+  const api = useApi();
+
+  const vars = useQuery({
+    queryKey: ['variables', id],
+    queryFn: () => api.serviceVariables(id!),
+    enabled: !!id,
+  });
+
+  if (vars.isLoading) return <Loading />;
+  if (vars.error) return <ErrorBox error={vars.error} />;
+  if (!vars.data) return <ErrorBox error={new Error('Not found')} />;
+
+  // Editor mounts once data exists; its state initializes from the fetch.
+  return <Editor serviceId={id!} name={name} initial={vars.data} />;
+}
+
+function Editor({
+  serviceId,
+  name,
+  initial,
+}: {
+  serviceId: string;
+  name?: string;
+  initial: Variable[];
+}) {
+  const api = useApi();
+  const qc = useQueryClient();
+  const [rows, setRows] = useState<Row[]>(() =>
+    initial.map((v) => ({
+      key: v.key,
+      value: v.is_secret ? '' : v.value,
+      is_secret: v.is_secret,
+      keepSecret: v.is_secret,
+    })),
+  );
+
+  const save = useMutation({
+    mutationFn: () => {
+      const clean = rows
+        .filter((r) => r.key.trim() !== '')
+        .map((r) => ({
+          key: r.key.trim(),
+          value: r.keepSecret ? MASKED_SECRET : r.value,
+          is_secret: r.is_secret,
+        }));
+      return api.updateVariables(serviceId, clean);
+    },
+    onSuccess: () => {
+      qc.invalidateQueries({ queryKey: ['variables', serviceId] });
+      qc.invalidateQueries({ queryKey: ['env-check', serviceId] });
+      Alert.alert('Saved', 'Variables apply on the next deploy/restart.');
+    },
+    onError: (e) => Alert.alert('Save failed', e instanceof Error ? e.message : String(e)),
+  });
+
+  const set = (i: number, patch: Partial<Row>) =>
+    setRows((rs) => rs.map((r, j) => (j === i ? { ...r, ...patch } : r)));
+
+  return (
+    <KeyboardAvoidingView
+      style={styles.root}
+      behavior={Platform.OS === 'ios' ? 'padding' : undefined}
+    >
+      <ScrollView contentContainerStyle={{ padding: 16 }}>
+        <Text style={styles.hint}>
+          Variables for {name ?? 'this service'}. Secret values are stored encrypted — leave a
+          secret blank to keep it, type to replace.
+        </Text>
+
+        {rows.length === 0 ? <Empty text="No variables yet" /> : null}
+        {rows.map((r, i) => (
+          <Card key={i}>
+            <View style={styles.rowHead}>
+              <TextInput
+                style={styles.keyInput}
+                value={r.key}
+                onChangeText={(t) => set(i, { key: t.toUpperCase().replace(/\s/g, '_') })}
+                placeholder="KEY"
+                placeholderTextColor={colors.textDim}
+                autoCapitalize="characters"
+                autoCorrect={false}
+              />
+              <TouchableOpacity
+                onPress={() =>
+                  set(i, r.is_secret ? { is_secret: false, keepSecret: false } : { is_secret: true })
+                }
+                hitSlop={8}
+                style={styles.iconBtn}
+              >
+                <Ionicons
+                  name={r.is_secret ? 'lock-closed' : 'lock-open-outline'}
+                  size={18}
+                  color={r.is_secret ? colors.warn : colors.textDim}
+                />
+              </TouchableOpacity>
+              <TouchableOpacity
+                onPress={() => setRows((rs) => rs.filter((_, j) => j !== i))}
+                hitSlop={8}
+                style={styles.iconBtn}
+              >
+                <Ionicons name="trash-outline" size={18} color={colors.err} />
+              </TouchableOpacity>
+            </View>
+            <TextInput
+              style={styles.valueInput}
+              value={r.value}
+              onChangeText={(t) => set(i, { value: t, keepSecret: false })}
+              placeholder={r.keepSecret ? '••••••••  (unchanged)' : 'value'}
+              placeholderTextColor={colors.textDim}
+              secureTextEntry={r.is_secret && !r.keepSecret}
+              autoCapitalize="none"
+              autoCorrect={false}
+              multiline={false}
+            />
+          </Card>
+        ))}
+
+        <ActionButton
+          label="+ Add variable"
+          onPress={() =>
+            setRows((rs) => [...rs, { key: '', value: '', is_secret: false, keepSecret: false }])
+          }
+        />
+        <ActionButton
+          label={save.isPending ? 'Saving…' : 'Save variables'}
+          kind="primary"
+          disabled={save.isPending}
+          onPress={() => save.mutate()}
+        />
+        <View style={{ height: 40 }} />
+      </ScrollView>
+    </KeyboardAvoidingView>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: { flex: 1, backgroundColor: colors.bg },
+  hint: { color: colors.textDim, fontSize: 12, marginBottom: 12, lineHeight: 17 },
+  rowHead: { flexDirection: 'row', alignItems: 'center', marginBottom: 6 },
+  keyInput: {
+    flex: 1,
+    color: colors.text,
+    fontSize: 14,
+    fontWeight: '700',
+    fontFamily: Platform.OS === 'ios' ? 'Menlo' : 'monospace',
+  },
+  valueInput: {
+    color: colors.text,
+    fontSize: 14,
+    fontFamily: Platform.OS === 'ios' ? 'Menlo' : 'monospace',
+    backgroundColor: colors.surfaceAlt,
+    borderRadius: 8,
+    padding: 10,
+  },
+  iconBtn: { padding: 6, marginLeft: 6 },
+});

docs/api/openapi.yaml

@@ -720,6 +720,35 @@ paths:
                     items:
                       type: string
 
+  /services/{id}/terminal:
+    get:
+      tags:
+        - Services
+      summary: Interactive terminal (WebSocket)
+      description: >-
+        Upgrades to a WebSocket bridged to a `docker exec` PTY in the
+        service's running container (bash if present, else sh).
+        Cookie/bearer auth as usual.
+        Client→server JSON frames: `{"type":"stdin","data":"..."}`,
+        `{"type":"resize","cols":N,"rows":N}`.
+        Server→client frames: `{"type":"stdout","data":"..."}`,
+        `{"type":"exit","code":N}`, `{"type":"error","message":"..."}`.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '101':
+          description: Switching protocols — WebSocket session established
+        '404':
+          description: Service not found or not visible
+        '409':
+          description: Service has no running container
+        '503':
+          description: Docker unavailable
+
   /internal/wake/{id}:
     get:
       tags:
@@ -2127,6 +2156,62 @@ paths:
                     items:
                       type: string
 
+  /templates/import/git:
+    post:
+      tags:
+        - Templates
+      summary: Import a compose file from a git repository
+      description: |
+        Fetches a compose file out of a git repository and runs it through
+        the same conversion as POST /templates/import/compose. `repo`
+        accepts a clone URL, ssh remote, or `owner/repo` shorthand —
+        connected git providers (including GitHub App installs) supply
+        credentials, so private repositories work. `path` defaults to
+        `compose.yaml`, `compose.yml`, `docker-compose.yml`, then
+        `docker-compose.yaml`; `ref` selects a branch or commit SHA.
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - repo
+              properties:
+                repo:
+                  type: string
+                  description: Clone URL, ssh remote, or owner/repo shorthand
+                path:
+                  type: string
+                  description: Repo-relative compose file path (searched by convention when empty)
+                ref:
+                  type: string
+                  description: Branch name or 40-char commit SHA
+      responses:
+        '200':
+          description: Converted config
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  config:
+                    $ref: '#/components/schemas/TemplateConfig'
+                  variables:
+                    type: array
+                    items:
+                      type: object
+                  warnings:
+                    type: array
+                    items:
+                      type: string
+        '400':
+          description: Invalid repo reference, compose file missing, or conversion error
+        '502':
+          description: Git fetch failed
+
   /templates/deploy:
     post:
       tags:
@@ -5051,6 +5136,37 @@ 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
+                        tags:
+                          type: array
+                          items: { type: string }
+
   /agents:
     get:
       tags:
@@ -5100,7 +5216,7 @@ paths:
       tags:
         - Agents
       summary: Update node agent
-      description: Partial update — accepts any subset of agent fields (name, status, labels, etc.).
+      description: Partial update — accepts any subset of agent fields (name, status, auto_prune, tags). `tags` sets the node's placement labels; services with placement_tags only schedule onto agents carrying every required tag.
       security:
         - bearerAuth: []
       parameters:
@@ -5262,6 +5378,230 @@ 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}/upgrade:
+    post:
+      tags:
+        - Agents
+      summary: Upgrade the node agent
+      description: >-
+        Enqueues a `self_upgrade` command. The agent downloads its
+        replacement binary from this server's bundled `/agents/download`
+        endpoint, verifies the sha256, atomically swaps the executable, and
+        re-execs itself — the command result reports before the process
+        swaps. The node must be online, and the server must bundle a binary
+        for the node's architecture (`linux-amd64`/`linux-arm64`).
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: '#/components/parameters/AgentIdParam'
+      responses:
+        '202':
+          description: Upgrade command enqueued
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  command: { type: object }
+                  platform: { type: string }
+                  version: { type: string }
+        '404':
+          description: Agent not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: Node offline or no bundled binary for its architecture
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+
   /agents/{id}/metrics:
     get:
       tags:
@@ -6727,6 +7067,19 @@ 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. Git-sourced services build on the node itself (build context ships as an agent-token artifact); rollbacks of locally-built tags ship the image via docker save/load.
+        node_name:
+          type: string
+          description: Display name of the pinned node agent (read-only)
+        spread:
+          type: boolean
+          description: Replicas are distributed across every online, schedulable node agent (replica i → agents[i mod n]). Mutually exclusive with an explicit node_id pin.
+        placement_tags:
+          type: array
+          items: { type: string }
+          description: Node tags required for remote placement — auto/spread only consider agents carrying every tag; re-resolved each reconcile. Mutually exclusive with an explicit node_id pin (read-only on responses when a pin is set).
         public_url:
           type: string
           description: Computed public URL (published port or domain)
@@ -6818,6 +7171,16 @@ 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
+        spread:
+          type: boolean
+          description: Distribute replicas across every online, schedulable node agent; mutually exclusive with an explicit node_id pin
+        placement_tags:
+          type: array
+          items: { type: string }
+          description: Restrict remote placement to agents carrying every listed tag; mutually exclusive with an explicit pin or 'local'
 
     UpdateServiceRequest:
       type: object
@@ -6904,6 +7267,16 @@ 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)
+        spread:
+          type: boolean
+          description: Distribute replicas across every online, schedulable node agent; mutually exclusive with an explicit node_id pin — send 'local' first to clear a pin
+        placement_tags:
+          type: array
+          items: { type: string }
+          description: Restrict remote placement to agents carrying every listed tag; [] clears. Mutually exclusive with a pin or 'local' — clear the pin first
 
     ServiceDomain:
       type: object
@@ -7364,6 +7737,9 @@ components:
         is_public:
           type: boolean
           description: Whether a user-created template is published to the public catalog
+        source:
+          type: string
+          description: 'Catalog origin: absent for local/official templates; "registry" for entries merged from CONTAINR_TEMPLATE_REGISTRY_URL. Deploying a registry template materializes a local copy first.'
         created_at:
           type: string
           format: date-time
@@ -8778,6 +9154,18 @@ 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.
+        tags:
+          type: array
+          items: { type: string }
+          description: Operator-set placement labels; services with placement_tags require all of them on the target node.
         last_heartbeat:
           type: string
           format: date-time
@@ -9011,6 +9399,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
@@ -86,6 +90,8 @@ operations                       live ops view: active deploys, queue depth,
                                24h failures, cron runs, backups
 activity                         enriched activity feed; --severity/--category/
                                --resource/--project/--limit filters
+shell <service-id>               interactive PTY shell inside the service
+                               container (bash→sh fallback; resizes follow)
 banners list|create|update|delete  announcement banners (admin);
                                active banners print on `auth status`
 invites list|create|revoke       team invite links (admin); create
@@ -126,6 +132,60 @@ 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
+```
+
+`auto` scores nodes by real headroom — lowest memory utilisation, then
+cpu, then container count. Or spread replicas across every online,
+schedulable node (mutually exclusive with a pin):
+
+```bash
+containr services update <id> --replicas 4 --spread    # replica i → node[i % n]
+containr services update <id> --spread=false           # back to single placement
+```
+
+Constrain `auto`/`spread` placement to nodes carrying operator tags —
+`nodes update` labels a node, `--placement-tags` requires every listed tag
+(mutually exclusive with a pin; an empty value clears the requirement):
+
+```bash
+containr nodes update <id> --tags gpu,eu-west
+containr services update <id> --placement-tags gpu     # only gpu nodes are eligible
+```
+
+Remote nodes run registry-pulled images only — git builds stay local.
+Domains work remotely: the agent publishes the service port and the
+backend writes a Traefik file-provider route to the node's mesh IP
+(TRAEFIK_DYNAMIC_DIR — wired by the infra compose). Sleep mode works
+too: heartbeats carry per-container net counters, idle remote services
+lose their replicas via the agent, and the route repoints at the
+backend's wake page — the next hit reconciles the service back. 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
+containr nodes upgrade <id>   # agent pulls its replacement from the server, re-execs
+```
+
+`nodes upgrade` swaps the agent binary for the one bundled in the running
+server image — the agent downloads it over the API, verifies the sha256 the
+server computed, sanity-checks it, atomically replaces its own executable,
+and re-execs. The node must be online and the server must ship a binary for
+its architecture (`linux-amd64`/`linux-arm64`).
+
 ## Service domains and access
 
 A service can carry multiple hostnames; the default is mirrored to

infra/docker-compose.yml

@@ -7,7 +7,8 @@ services:
       - "--api.insecure=${TRAEFIK_API_INSECURE:-true}"
       - "--providers.docker=true"
       - "--providers.docker.exposedbydefault=false"
-      - "--providers.file.filename=/etc/traefik/traefik-dynamic.yml"
+      - "--providers.file.directory=/traefik-dynamic"
+      - "--providers.file.watch=true"
       - "--entrypoints.web.address=:80"
       - "--entrypoints.websecure.address=:443"
       - "--entrypoints.traefik.address=:8080"
@@ -26,7 +27,8 @@ services:
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
       - ../data/letsencrypt:/letsencrypt
-      - ./traefik-dynamic.yml:/etc/traefik/traefik-dynamic.yml:ro
+      - traefik_dynamic:/traefik-dynamic
+      - ./traefik-dynamic.yml:/traefik-dynamic/00-base.yml:ro
     networks:
       - containr-network
     restart: unless-stopped
@@ -100,6 +102,8 @@ services:
       - JWT_SECRET=${JWT_SECRET:-dev_jwt_secret_key_change_in_production}
       - CONTAINR_AGENT_AUTH_TOKEN=${CONTAINR_AGENT_AUTH_TOKEN:-}
       - CONTAINR_AGENT_AUTH_TOKENS=${CONTAINR_AGENT_AUTH_TOKENS:-}
+      - TRAEFIK_DYNAMIC_DIR=/traefik-dynamic
+      - TRAEFIK_BACKEND_URL=http://containr-backend:8080
       - COOKIE_SECURE=${COOKIE_SECURE:-true}
       - TRUSTED_PROXY_CIDR=${TRUSTED_PROXY_CIDR:-172.20.0.0/16}
       - CORS_ORIGINS=${CORS_ORIGINS:-http://localhost,http://localhost:3000}
@@ -136,6 +140,7 @@ services:
       - GITEA_BASE_URL=${GITEA_BASE_URL:-https://gitea.example.com}
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
+      - traefik_dynamic:/traefik-dynamic
     group_add:
       - "${DOCKER_GID:-0}"
     networks:
@@ -213,6 +218,8 @@ volumes:
     driver: local
   dragonfly_data:
     driver: local
+  traefik_dynamic:
+    driver: local
 
 networks:
   containr-network:

llms.txt

@@ -19,7 +19,7 @@ Base URL: `https://<host>/api/v1`. OpenAPI: `docs/api/openapi.yaml`.
 - **Variables**: service env values support `${{service.KEY}}` cross-service refs (builtins HOST/PORT) and `${{shared.KEY}}` project shared variables (`GET|PUT /projects/{id}/variables`, CLI `variables shared …`). Resolved at deploy/reconcile, not live-updated.
 - **Volumes**: service mounts via `PUT /services/{id}` `volumes: [{type: volume|bind, source, target, read_only}]` — replaces the whole list (`[]` clears), applied on next deploy. `GET /admin/volumes` inventories node volumes with `in_use` flags; `DELETE /admin/volumes/{name}` removes unused ones (admin).
 - **Domains**: multiple hostnames per service via `GET|POST /services/{id}/domains`, `DELETE /services/{id}/domains/{domain_id}`, `POST …/{domain_id}/default` (mirrors `services.domain`). `GET /services/{id}/domains/check` returns `ok|wrong-target|pending` per domain vs `app_settings.public_ip`/`PUBLIC_IP`. `PUT` `maintenance_mode` redirects all traffic to `GET /maintenance` (needs `base_url`/`BASE_URL` setting); `basic_auth: [{username,password}]` stores bcrypt htpasswd and gates the route — responses return usernames only.
-- **Builders & resources**: service field `builder` = `auto|railpack|nixpacks|dockerfile|static` (auto detects; static builds assets with `static_build_cmd` and serves `static_dir` via nginx:80). `cpu`/`memory` are hard caps; `cpu_reserve`/`memory_reserve` are soft reservations (CPU shares / MemoryReservation) — empty string clears. `app_settings.default_cpu`/`default_memory` set instance defaults; `app_settings.capacity_policy=block` rejects deploys exceeding node memory (default `warn`).
+- **Builders & resources**: service field `builder` = `auto|railpack|nixpacks|dockerfile|static` (auto detects; static builds assets with `static_build_cmd` and serves `static_dir` via nginx:80). `cpu`/`memory` are hard caps; `cpu_reserve`/`memory_reserve` are soft reservations (CPU shares / MemoryReservation) — empty string clears. `app_settings.default_cpu`/`default_memory` set instance defaults; `app_settings.capacity_policy=block` rejects deploys exceeding node memory (default `warn`). Services pinned to remote node agents (`node_id`) build git sources on the node itself: the server checks out the repo, packages a Docker context artifact served over the agent-token endpoint (`GET /api/agents/artifacts/{id}`), and the node's `build_image` command runs `docker build` — no registry needed. Rollbacks of locally-built tags ship the image as a docker-save artifact consumed by `load_image`.
 - **Clone & move**: `POST /services/{id}/clone` `{name?, project_id?, environment?}` copies config, volumes, domains, access gates, and variables (secret ciphertext verbatim; clone starts stopped). `POST /services/{id}/move` `{project_id}` re-parents a service — both require ownership of source and target; name conflicts → `CONFLICT`. Cloned domains are verbatim copies: the same hostname on two services makes routing ambiguous.
 - **Registries**: `GET|POST /registries`, `PUT|DELETE /registries/{id}` — owner-scoped private-image pull credentials, encrypted at rest, never returned (`has_password` signals presence). `host` matched against the image reference on image deploys (`docker.io` for Docker Hub; scheme/case normalized). Empty `password` on update keeps the stored credential.
 - **External databases**: `POST /databases/register-external` (probes first; `{name,type,host,port,database,username,password,ssl}`), `POST /databases/test-connection` (ad-hoc probe → `{ok,latency_ms,error}`), `POST /databases/{id}/test-connection` (re-probe with stored credentials). Rows carry `provider:"external"` + `external{host,port,database,username,has_password,ssl}`; passwords encrypted at rest, never returned. Lifecycle actions and backups reject external rows — no container exists.

scripts/build-cli.sh

@@ -38,8 +38,17 @@ for platform in $PLATFORMS; do
         -ldflags "$LDFLAGS" \
         -o "bin/${MCP_NAME}" \
         ./cmd/mcp
-    
+done
-    echo "✅ Built bin/${OUTPUT_NAME} + bin/${MCP_NAME}"
+
+# Node agents are linux-only — the download endpoint serves the same two
+# arches, and install-agent.sh falls back to these GH release assets.
+for arch in amd64 arm64; do
+    echo "📦 Building agent for linux/${arch}..."
+    CGO_ENABLED=0 GOOS=linux GOARCH=$arch go build \
+        -ldflags "-X main.version=${VERSION}" \
+        -o "bin/containr-agent-linux-${arch}" \
+        ./cmd/agent
+    echo "✅ Built bin/containr-agent-linux-${arch}"
 done
 
 echo "🎉 CLI build complete!"

templates/n8n.md

@@ -103,7 +103,8 @@ services:
       - n8n_storage:/home/node/.n8n
     command: worker
     depends_on:
-      - n8n
+      n8n:
+        condition: service_started
       redis:
         condition: service_healthy
       postgres: