feat: build-on-node — git checkouts, remote image builds, image transport (#60)

Git-sourced deploys never materialized a checkout: sourcePath was
build_path resolved against the server cwd, so builds consumed the
backend's own directory. Remote placement could only run
registry-pulled images.

- internal/source: per-deployment checkout (init/fetch/checkout) at
  branch or commit; GIT_ASKPASS keeps tokens out of argv, .git/config,
  and the build context; dumb-transport and SHA-refusal fallbacks;
  build_path validated inside the checkout.
- BuildManager.PackageContext: produces the same tar context Build
  ships to the daemon — generated Dockerfile at tar root, .git
  excluded. Fixes nixpacks passing the Dockerfile path as content.
- Agent artifact endpoint: GET /api/agents/artifacts/:id streams
  build contexts and docker-save tarballs behind agent-token auth;
  hex-validated ids, per-deployment cleanup, boot-time purge.
- Agent commands: build_image (docker build -, --build-arg values via
  process env, not argv) and load_image (docker load for containr-*
  rollback tags no registry serves).
- Deployment flow: remote git builds package context → artifact →
  node docker-builds the deployment tag; remote rollbacks of local
  tags export via SaveImage → artifact → node docker-loads.

Verified end-to-end: agent-pinned git service built on the node
(build_image → create_container → deployed) and rollback shipped a
docker-save tarball (load_image → deployed). Artifact auth returns
401/404 correctly; workspaces and blobs are removed after deploy.

Authored By: TDvorak <[email protected]>

.env.example

@@ -49,6 +49,10 @@ CONTAINR_AGENT_AUTH_TOKEN=replace_with_strong_agent_secret
 # 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.

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

@@ -296,9 +296,22 @@ and wired refs, one click or one CLI call.
   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 nodes run registry-pulled
-  images only — git builds, Traefik domains, and remote sleep are
-  documented ceilings. Tag affinity shipped: `node_agents.tags`
+  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
@@ -307,9 +320,8 @@ and wired refs, one click or one CLI call.
   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: deployment
-  status reported back from agent results, spread weighting by
-  real capacity.
+  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/

app/backend/Dockerfile

@@ -30,7 +30,7 @@ COPY auth/src ./src
 # Final runtime image (Go API + Better Auth sidecar in one container)
 FROM node:22-alpine
 
-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

app/backend/cmd/agent/main.go

@@ -204,10 +204,92 @@ func sendHeartbeat(ctx context.Context, client *http.Client, cfg agentConfig, ag
 		"system_load":     readSystemLoad(),
 		"uptime":          readSystemUptime(),
 		"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 {
@@ -234,7 +316,7 @@ func processCommands(ctx context.Context, client *http.Client, cfg agentConfig,
 		if item.Type == "self_upgrade" {
 			result, reexecPath, runErr = selfUpgrade(cfg, item.Payload)
 		} else {
-			result, runErr = executeCommand(item)
+			result, runErr = executeCommand(cfg, item)
 		}
 		status := "completed"
 		errText := ""
@@ -261,7 +343,7 @@ func processCommands(ctx context.Context, client *http.Client, cfg agentConfig,
 	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)
@@ -272,7 +354,16 @@ 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":
@@ -460,7 +551,139 @@ func createContainer(payload map[string]interface{}) (string, error) {
 		logs, _ := runDocker("logs", "--tail", "5", name)
 		return "", fmt.Errorf("container %s is %q after start: %s", name, state, logs)
 	}
-	return name, nil
+	// 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
@@ -674,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 {

app/backend/internal/api/agents.go

@@ -198,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 {
@@ -665,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)
 }
 
@@ -742,7 +769,9 @@ func (h *NodeAgentHandler) CompleteCommand(c *gin.Context) {
 }
 
 // scrubCommandSecrets rewrites a completed command's payload with any
-// registry password blanked. Best-effort — a failed scrub leaves the row.
+// 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
@@ -751,15 +780,24 @@ func scrubCommandSecrets(ctx context.Context, q *sqlcdb.Queries, commandID strin
 	if err := json.Unmarshal(payload.RawMessage, &doc); err != nil {
 		return
 	}
-	container, ok := doc["container"].(map[string]interface{})
-	if !ok {
+	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
 	}
-	reg, ok := container["registry"].(map[string]interface{})
-	if !ok || reg["password"] == nil {
-		return
-	}
-	reg["password"] = "***"
 	if err := q.ScrubCommandPayload(ctx, sqlcdb.ScrubCommandPayloadParams{
 		ID:      commandID,
 		Payload: rawJSON(doc),
@@ -1431,6 +1469,10 @@ func (h *NodeAgentHandler) SetupPublicRoutes(router *gin.RouterGroup) {
 		// 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)
 	}
 }
 

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/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,19 +442,31 @@ func runDeploymentAndSyncWithImage(
 		maintURL = maintenanceURL(db)
 	}
 
-	// Node-pinned services dispatch to the agent's command queue. Builds run
-	// on the local host, so remote placement only works for registry-pulled
-	// images — git-sourced and rollback deploys fail fast with that message.
+	// Node-pinned and spread services dispatch to agent command queues.
 	nodeID := serviceNodeID(db, service.ID)
 	spread := serviceSpread(db, service.ID)
-	if (nodeID != "" || spread) && (service.GitRepo != "" || imageOverride != "") {
-		failedAt := time.Now()
-		msg := "service uses remote node placement but remote nodes only run registry-pulled images (git builds and rollbacks stay local — build-on-node is not yet supported)"
-		_, _ = db.Exec(
-			`UPDATE deployments SET status = 'failed', error = $1, completed_at = $2, updated_at = $2 WHERE id = $3`,
-			msg, failedAt, dbDeployment.ID,
-		)
-		return
+	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{
@@ -480,14 +513,36 @@ func runDeploymentAndSyncWithImage(
 		if image == "" {
 			image = service.Image
 		}
-		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,
+		if remote && strings.HasPrefix(image, "containr-") {
+			// Locally-built tag — no registry serves it. Ship the image
+			// itself as a docker-save artifact; the node loads it.
+			rc, err := engine.DockerClient().SaveImage(ctx, image)
+			if err != nil {
+				failDeploy("export rollback image: " + err.Error())
+				return
+			}
+			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
@@ -497,16 +552,54 @@ func runDeploymentAndSyncWithImage(
 		if service.Builder != "" && service.Builder != "auto" {
 			buildType = service.Builder
 		}
-		deployReq.BuildConfig = &deployment.BuildConfig{
-			BuildType:  buildType,
-			SourcePath: sourcePath,
-			Branch:     req.Branch,
-			Commit:     req.CommitHash,
-			NoCache:    req.NoCache,
-		}
+		buildArgs := map[string]string{}
+		buildCommand := ""
 		if buildType == "static" {
-			deployReq.BuildConfig.BuildCommand = firstNonEmpty(service.StaticBuildCmd, "npm ci && npm run build")
-			deployReq.BuildConfig.BuildArgs = map[string]string{"STATIC_DIR": firstNonEmpty(service.StaticDir, "dist")}
+			buildCommand = firstNonEmpty(service.StaticBuildCmd, "npm ci && npm run build")
+			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/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

@@ -19,8 +19,8 @@ import (
 
 // agentNodeRunner implements deployment.NodeRunner by dispatching container
 // lifecycle commands to a node agent's command queue and waiting for the
-// reported result. Remote nodes have no Traefik — domains stay local-only
-// until per-node ingress lands.
+// 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
@@ -131,10 +131,6 @@ func (r *agentNodeRunner) RemoteRuntimeState(ctx context.Context, serviceID stri
 // 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) {
-	if len(spec.Domains) > 0 || spec.Domain != "" {
-		return nil, fmt.Errorf("domains are routed by the local Traefik — remove the service's domains or run it on the local node")
-	}
-
 	replicas := spec.Replicas
 	if replicas < 1 {
 		replicas = 1
@@ -151,7 +147,7 @@ func (r *agentNodeRunner) reconcileOnAgents(ctx context.Context, spec deployment
 		if keep {
 			continue
 		}
-		if cmdErr := r.enqueueAndWait(ctx, row.NodeAgentID, "", "remove_container",
+		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)
 		}
@@ -161,6 +157,45 @@ func (r *agentNodeRunner) reconcileOnAgents(ctx context.Context, spec deployment
 		})
 	}
 
+	// 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)
@@ -185,18 +220,41 @@ func (r *agentNodeRunner) reconcileOnAgents(ctx context.Context, spec deployment
 			HealthCheck:   rawJSON(map[string]interface{}{"path": spec.HealthPath}),
 		})
 
-		if err := r.enqueueAndWait(ctx, agentID, containerID, "create_container",
-			map[string]interface{}{"container": container}); err != nil {
+		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)
 		}
-		_ = r.q.UpdateContainerStatus(ctx, sqlcdb.UpdateContainerStatusParams{
-			ID:     containerID,
-			Status: rawJSON(map[string]interface{}{"state": "running", "health": "none"}),
-		})
+		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
 }
 
@@ -296,7 +354,17 @@ func (r *agentNodeRunner) ControlService(ctx context.Context, serviceID, agentID
 		if row.ServiceID != serviceID {
 			continue
 		}
-		if err := r.enqueueAndWait(ctx, agentID, row.ID, cmdType,
+		// 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)
 		}
@@ -314,16 +382,42 @@ func (r *agentNodeRunner) RemoveService(ctx context.Context, serviceID, agentID
 	if err := r.ControlService(ctx, serviceID, agentID, "remove"); err != nil {
 		return err
 	}
-	return r.q.DeleteServiceContainersOnAgent(ctx, sqlcdb.DeleteServiceContainersOnAgentParams{
+	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. Agents poll on their own interval (≥5s), so this blocks —
-// it runs inside the deploy queue worker, never on a request path.
-func (r *agentNodeRunner) enqueueAndWait(ctx context.Context, agentID, containerID, cmdType string, payload map[string]interface{}) error {
+// 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}
@@ -336,10 +430,10 @@ func (r *agentNodeRunner) enqueueAndWait(ctx context.Context, agentID, container
 		Payload:     rawJSON(payload),
 	})
 	if err != nil {
-		return err
+		return "", err
 	}
 
-	deadline := time.Now().Add(8 * time.Minute) // image pulls on a cold node
+	deadline := time.Now().Add(timeout) // image pulls/builds on a cold node
 	for {
 		row, err := r.q.GetCommandForAgent(ctx, sqlcdb.GetCommandForAgentParams{
 			ID:          cmd.ID,
@@ -348,20 +442,20 @@ func (r *agentNodeRunner) enqueueAndWait(ctx context.Context, agentID, container
 		if err == nil {
 			switch row.Status.String {
 			case "completed":
-				return nil
+				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: %s", row.Error.String)
 				}
-				return fmt.Errorf("agent reported failure")
+				return "", fmt.Errorf("agent reported failure")
 			}
 		}
 		if time.Now().After(deadline) {
-			return fmt.Errorf("command %s timed out waiting for the agent", cmdType)
+			return "", fmt.Errorf("command %s timed out waiting for the agent", cmdType)
 		}
 		select {
 		case <-ctx.Done():
-			return ctx.Err()
+			return "", ctx.Err()
 		case <-time.After(2 * time.Second):
 		}
 	}

app/backend/internal/api/routes.go

@@ -5,6 +5,7 @@ import (
 	"log"
 	"net/http"
 	"os"
+	"path/filepath"
 	"time"
 
 	"containr/internal/build"
@@ -43,6 +44,8 @@ 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))
@@ -285,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

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 {
@@ -346,18 +419,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
+		return http.StatusServiceUnavailable, gin.H{"error": "deployment engine unavailable"}
 	}
 	id, err := uuid.Parse(c.Param("id"))
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid service id"})
-		return
+		return http.StatusBadRequest, gin.H{"error": "invalid service id"}
 	}
 	var service Service
 	err = db.QueryRow(
@@ -385,12 +480,10 @@ func handleServiceWake(c *gin.Context) {
 		&service.CreatedAt, &service.UpdatedAt,
 	)
 	if err != nil {
-		c.JSON(http.StatusNotFound, gin.H{"error": "service not found"})
-		return
+		return http.StatusNotFound, gin.H{"error": "service not found"}
 	}
 	if service.Status == "running" || service.Status == "deployed" {
-		c.JSON(http.StatusOK, gin.H{"status": service.Status})
-		return
+		return http.StatusOK, gin.H{"status": service.Status}
 	}
 	go func() {
 		ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
@@ -411,7 +504,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 +531,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/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
-	buildCtx, err := createBuildContext(req.SourcePath, dockerfile)
+	// Create build context tar — createBuildContext takes the 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/database/sqlcdb/agents.sql.go

@@ -765,8 +765,36 @@ func (q *Queries) ListSchedulableAgentsMatching(ctx context.Context, dollar_1 js
 	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 FROM container_instances
+SELECT id, name, node_agent_id, status, ports, resources FROM container_instances
 WHERE service_id = $1
 `
 
@@ -775,6 +803,8 @@ type ListServiceContainersRow struct {
 	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) {
@@ -791,6 +821,8 @@ func (q *Queries) ListServiceContainers(ctx context.Context, serviceID string) (
 			&i.Name,
 			&i.NodeAgentID,
 			&i.Status,
+			&i.Ports,
+			&i.Resources,
 		); err != nil {
 			return nil, err
 		}
@@ -1005,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

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

@@ -98,6 +98,8 @@ type Querier interface {
 	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)
@@ -134,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

app/backend/internal/deployment/engine.go

@@ -32,6 +32,9 @@ type NodeRunner interface {
 	// 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 {
@@ -92,12 +95,29 @@ type ServiceConfig struct {
 	// reuses it so public URLs survive restarts. 0 = pick ephemeral.
 	PublishedPort int32 `json:"published_port,omitempty"`
 	// NodeID pins the service to a registered node agent; "" = local Docker
-	// host. Remote placement requires a registry-pullable image — builds stay
-	// on the local host (build-on-node is not yet supported).
+	// host.
 	NodeID string `json:"node_id,omitempty"`
 	// Spread distributes replicas across every online, schedulable agent.
-	// Same registry-image constraint as NodeID.
 	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 {
@@ -208,6 +228,12 @@ 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
@@ -323,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,
@@ -390,6 +424,8 @@ func (de *DeploymentEngine) deployService(ctx context.Context, deployment *Deplo
 		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

@@ -63,6 +63,12 @@ type RuntimeSpec struct {
 	// 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.
@@ -182,6 +188,12 @@ func (de *DeploymentEngine) ReconcileService(ctx context.Context, spec RuntimeSp
 		}
 		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
 	}

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{

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/sqlc/queries/agents.sql

@@ -110,6 +110,12 @@ RETURNING *;
 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
@@ -174,7 +180,7 @@ LIMIT 1;
 UPDATE node_agents SET tags = $2::jsonb, updated_at = NOW() WHERE id = $1;
 
 -- name: ListServiceContainers :many
-SELECT id, name, node_agent_id, status FROM container_instances
+SELECT id, name, node_agent_id, status, ports, resources FROM container_instances
 WHERE service_id = $1;
 
 -- name: SetAgentSchedulable :exec
@@ -197,5 +203,20 @@ ON CONFLICT (id) DO UPDATE SET
 -- 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/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)\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
+    "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",

docs/guides/CLI.md

@@ -161,8 +161,13 @@ 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, domains
-(Traefik lives on the host), and sleep detection stay local. Start,
+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`.
 

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.