Fix route-based port mapping: use hostPort as container port

allocateRoutePorts() was using the route's port field (the mc-proxy
listener port, e.g. 443) as the container internal port in the podman
port mapping. For L7 routes, apps don't listen on the mc-proxy port —
they read $PORT (set to the assigned host port) and listen on that.

The mapping host:53204 → container:443 fails because nothing listens
on 443 inside the container. Fix: use hostPort as both the host and
container port, so $PORT = host port = container port.

Broke mcdoc in production (manually fixed, now permanently fixed).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

flake.nix

@@ -10,7 +10,7 @@
     let
       system = "x86_64-linux";
       pkgs = nixpkgs.legacyPackages.${system};
-      version = "0.4.0";
+      version = "0.5.0";
     in
     {
       packages.${system} = {

internal/agent/agent.go

@@ -34,6 +34,7 @@ type Agent struct {
 	PortAlloc *PortAllocator
 	Proxy     *ProxyRouter
 	Certs     *CertProvisioner
+	DNS       *DNSRegistrar
 }
 
 // Run starts the agent: opens the database, sets up the gRPC server with
@@ -63,6 +64,11 @@ func Run(cfg *config.AgentConfig) error {
 		return fmt.Errorf("create cert provisioner: %w", err)
 	}
 
+	dns, err := NewDNSRegistrar(cfg.MCNS, logger)
+	if err != nil {
+		return fmt.Errorf("create DNS registrar: %w", err)
+	}
+
 	a := &Agent{
 		Config:    cfg,
 		DB:        db,
@@ -72,6 +78,7 @@ func Run(cfg *config.AgentConfig) error {
 		PortAlloc: NewPortAllocator(),
 		Proxy:     proxy,
 		Certs:     certs,
+		DNS:       dns,
 	}
 
 	tlsCert, err := tls.LoadX509KeyPair(cfg.Server.TLSCert, cfg.Server.TLSKey)

internal/agent/deploy.go

@@ -164,6 +164,13 @@ func (a *Agent) deployComponent(ctx context.Context, serviceName string, cs *mcp
 		}
 	}
 
+	// Register DNS record for the service.
+	if a.DNS != nil && len(regRoutes) > 0 {
+		if err := a.DNS.EnsureRecord(ctx, serviceName); err != nil {
+			a.Logger.Warn("failed to register DNS record", "service", serviceName, "err", err)
+		}
+	}
+
 	if err := registry.UpdateComponentState(a.DB, serviceName, compName, "running", "running"); err != nil {
 		a.Logger.Warn("failed to update component state", "service", serviceName, "component", compName, "err", err)
 	}
@@ -191,7 +198,10 @@ func (a *Agent) allocateRoutePorts(service, component string, routes []registry.
 			return nil, nil, fmt.Errorf("store host port for route %q: %w", r.Name, err)
 		}
 
-		ports = append(ports, fmt.Sprintf("127.0.0.1:%d:%d", hostPort, r.Port))
+		// The container port must match hostPort (which is also set as $PORT),
+		// so the app's listen address matches the podman port mapping.
+		// r.Port is the mc-proxy listener port, NOT the container port.
+		ports = append(ports, fmt.Sprintf("127.0.0.1:%d:%d", hostPort, hostPort))
 
 		if len(routes) == 1 {
 			env = append(env, fmt.Sprintf("PORT=%d", hostPort))

internal/agent/deploy_test.go

@@ -0,0 +1,159 @@
+package agent
+
+import (
+	"database/sql"
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"git.wntrmute.dev/mc/mcp/internal/registry"
+)
+
+func openTestDB(t *testing.T) *sql.DB {
+	t.Helper()
+	db, err := registry.Open(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	return db
+}
+
+func testAgent(t *testing.T) *Agent {
+	t.Helper()
+	return &Agent{
+		DB:        openTestDB(t),
+		PortAlloc: NewPortAllocator(),
+		Logger:    slog.New(slog.NewTextHandler(os.Stderr, nil)),
+	}
+}
+
+// seedComponent creates the service and component in the registry so that
+// allocateRoutePorts can store host ports for it.
+func seedComponent(t *testing.T, db *sql.DB, service, component string, routes []registry.Route) {
+	t.Helper()
+	if err := registry.CreateService(db, service, true); err != nil {
+		t.Fatalf("create service: %v", err)
+	}
+	if err := registry.CreateComponent(db, &registry.Component{
+		Name:          component,
+		Service:       service,
+		Image:         "img:latest",
+		DesiredState:  "running",
+		ObservedState: "unknown",
+		Routes:        routes,
+	}); err != nil {
+		t.Fatalf("create component: %v", err)
+	}
+}
+
+func TestAllocateRoutePorts_SingleRoute(t *testing.T) {
+	a := testAgent(t)
+	routes := []registry.Route{
+		{Name: "default", Port: 443, Mode: "l7"},
+	}
+	seedComponent(t, a.DB, "mcdoc", "mcdoc", routes)
+
+	ports, env, err := a.allocateRoutePorts("mcdoc", "mcdoc", routes)
+	if err != nil {
+		t.Fatalf("allocateRoutePorts: %v", err)
+	}
+
+	if len(ports) != 1 {
+		t.Fatalf("expected 1 port mapping, got %d", len(ports))
+	}
+	if len(env) != 1 {
+		t.Fatalf("expected 1 env var, got %d", len(env))
+	}
+
+	// Parse the port mapping: should be "127.0.0.1:<hostPort>:<hostPort>"
+	// NOT "127.0.0.1:<hostPort>:443"
+	var hostPort, containerPort int
+	n, _ := fmt.Sscanf(ports[0], "127.0.0.1:%d:%d", &hostPort, &containerPort)
+	if n != 2 {
+		t.Fatalf("failed to parse port mapping %q", ports[0])
+	}
+	if hostPort != containerPort {
+		t.Errorf("host port (%d) != container port (%d); container port must match host port for $PORT consistency", hostPort, containerPort)
+	}
+
+	// Env var should be PORT=<hostPort>
+	var envPort int
+	n, _ = fmt.Sscanf(env[0], "PORT=%d", &envPort)
+	if n != 1 {
+		t.Fatalf("failed to parse env var %q", env[0])
+	}
+	if envPort != hostPort {
+		t.Errorf("PORT env (%d) != host port (%d)", envPort, hostPort)
+	}
+}
+
+func TestAllocateRoutePorts_MultiRoute(t *testing.T) {
+	a := testAgent(t)
+	routes := []registry.Route{
+		{Name: "rest", Port: 8443, Mode: "l4"},
+		{Name: "grpc", Port: 9443, Mode: "l4"},
+	}
+	seedComponent(t, a.DB, "metacrypt", "api", routes)
+
+	ports, env, err := a.allocateRoutePorts("metacrypt", "api", routes)
+	if err != nil {
+		t.Fatalf("allocateRoutePorts: %v", err)
+	}
+
+	if len(ports) != 2 {
+		t.Fatalf("expected 2 port mappings, got %d", len(ports))
+	}
+	if len(env) != 2 {
+		t.Fatalf("expected 2 env vars, got %d", len(env))
+	}
+
+	// Each port mapping should have host port == container port.
+	for i, p := range ports {
+		var hp, cp int
+		n, _ := fmt.Sscanf(p, "127.0.0.1:%d:%d", &hp, &cp)
+		if n != 2 {
+			t.Fatalf("port[%d]: failed to parse %q", i, p)
+		}
+		if hp != cp {
+			t.Errorf("port[%d]: host port (%d) != container port (%d)", i, hp, cp)
+		}
+	}
+
+	// Env vars should be PORT_REST and PORT_GRPC (not bare PORT).
+	if env[0][:10] != "PORT_REST=" {
+		t.Errorf("env[0] = %q, want PORT_REST=...", env[0])
+	}
+	if env[1][:10] != "PORT_GRPC=" {
+		t.Errorf("env[1] = %q, want PORT_GRPC=...", env[1])
+	}
+}
+
+func TestAllocateRoutePorts_L7PortNotUsedAsContainerPort(t *testing.T) {
+	a := testAgent(t)
+	routes := []registry.Route{
+		{Name: "default", Port: 443, Mode: "l7"},
+	}
+	seedComponent(t, a.DB, "svc", "web", routes)
+
+	ports, _, err := a.allocateRoutePorts("svc", "web", routes)
+	if err != nil {
+		t.Fatalf("allocateRoutePorts: %v", err)
+	}
+
+	// The container port must NOT be 443 (the mc-proxy listener port).
+	// It must be the host port (which is in range 10000-60000).
+	var hostPort, containerPort int
+	n, _ := fmt.Sscanf(ports[0], "127.0.0.1:%d:%d", &hostPort, &containerPort)
+	if n != 2 {
+		t.Fatalf("failed to parse port mapping %q", ports[0])
+	}
+	if containerPort == 443 {
+		t.Errorf("container port is 443 (mc-proxy listener); should be %d (host port)", hostPort)
+	}
+	if containerPort < portRangeMin || containerPort >= portRangeMax {
+		t.Errorf("container port %d outside allocation range [%d, %d)", containerPort, portRangeMin, portRangeMax)
+	}
+}

internal/agent/dns.go

@@ -0,0 +1,265 @@
+package agent
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"git.wntrmute.dev/mc/mcp/internal/auth"
+	"git.wntrmute.dev/mc/mcp/internal/config"
+)
+
+// DNSRegistrar creates and removes A records in MCNS during deploy
+// and stop. It is nil-safe: all methods are no-ops when the receiver
+// is nil.
+type DNSRegistrar struct {
+	serverURL  string
+	token      string
+	zone       string
+	nodeAddr   string
+	httpClient *http.Client
+	logger     *slog.Logger
+}
+
+// dnsRecord is the JSON representation of an MCNS record.
+type dnsRecord struct {
+	ID    int    `json:"ID"`
+	Name  string `json:"Name"`
+	Type  string `json:"Type"`
+	Value string `json:"Value"`
+	TTL   int    `json:"TTL"`
+}
+
+// NewDNSRegistrar creates a DNSRegistrar. Returns (nil, nil) if
+// cfg.ServerURL is empty (DNS registration disabled).
+func NewDNSRegistrar(cfg config.MCNSConfig, logger *slog.Logger) (*DNSRegistrar, error) {
+	if cfg.ServerURL == "" {
+		logger.Info("mcns not configured, DNS registration disabled")
+		return nil, nil
+	}
+
+	token, err := auth.LoadToken(cfg.TokenPath)
+	if err != nil {
+		return nil, fmt.Errorf("load mcns token: %w", err)
+	}
+
+	httpClient, err := newTLSClient(cfg.CACert)
+	if err != nil {
+		return nil, fmt.Errorf("create mcns HTTP client: %w", err)
+	}
+
+	logger.Info("mcns DNS registrar enabled", "server", cfg.ServerURL, "zone", cfg.Zone, "node_addr", cfg.NodeAddr)
+	return &DNSRegistrar{
+		serverURL:  strings.TrimRight(cfg.ServerURL, "/"),
+		token:      token,
+		zone:       cfg.Zone,
+		nodeAddr:   cfg.NodeAddr,
+		httpClient: httpClient,
+		logger:     logger,
+	}, nil
+}
+
+// EnsureRecord ensures an A record exists for the service in the
+// configured zone, pointing to the node's address.
+func (d *DNSRegistrar) EnsureRecord(ctx context.Context, serviceName string) error {
+	if d == nil {
+		return nil
+	}
+
+	existing, err := d.listRecords(ctx, serviceName)
+	if err != nil {
+		return fmt.Errorf("list DNS records: %w", err)
+	}
+
+	// Check if any existing record already has the correct value.
+	for _, r := range existing {
+		if r.Value == d.nodeAddr {
+			d.logger.Debug("DNS record exists, skipping",
+				"service", serviceName,
+				"record", r.Name+"."+d.zone,
+				"value", r.Value,
+			)
+			return nil
+		}
+	}
+
+	// No record with the correct value — update the first one if it exists.
+	if len(existing) > 0 {
+		d.logger.Info("updating DNS record",
+			"service", serviceName,
+			"old_value", existing[0].Value,
+			"new_value", d.nodeAddr,
+		)
+		return d.updateRecord(ctx, existing[0].ID, serviceName)
+	}
+
+	// No existing record — create one.
+	d.logger.Info("creating DNS record",
+		"service", serviceName,
+		"record", serviceName+"."+d.zone,
+		"value", d.nodeAddr,
+	)
+	return d.createRecord(ctx, serviceName)
+}
+
+// RemoveRecord removes A records for the service from the configured zone.
+func (d *DNSRegistrar) RemoveRecord(ctx context.Context, serviceName string) error {
+	if d == nil {
+		return nil
+	}
+
+	existing, err := d.listRecords(ctx, serviceName)
+	if err != nil {
+		return fmt.Errorf("list DNS records: %w", err)
+	}
+
+	if len(existing) == 0 {
+		d.logger.Debug("no DNS record to remove", "service", serviceName)
+		return nil
+	}
+
+	for _, r := range existing {
+		d.logger.Info("removing DNS record",
+			"service", serviceName,
+			"record", r.Name+"."+d.zone,
+			"id", r.ID,
+		)
+		if err := d.deleteRecord(ctx, r.ID); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// listRecords returns A records matching the service name in the zone.
+func (d *DNSRegistrar) listRecords(ctx context.Context, serviceName string) ([]dnsRecord, error) {
+	url := fmt.Sprintf("%s/v1/zones/%s/records?name=%s&type=A", d.serverURL, d.zone, serviceName)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create list request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+d.token)
+
+	resp, err := d.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("list records: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read list response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("list records: mcns returned %d: %s", resp.StatusCode, string(body))
+	}
+
+	var envelope struct {
+		Records []dnsRecord `json:"records"`
+	}
+	if err := json.Unmarshal(body, &envelope); err != nil {
+		return nil, fmt.Errorf("parse list response: %w", err)
+	}
+	return envelope.Records, nil
+}
+
+// createRecord creates an A record in the zone.
+func (d *DNSRegistrar) createRecord(ctx context.Context, serviceName string) error {
+	reqBody := map[string]interface{}{
+		"name":  serviceName,
+		"type":  "A",
+		"value": d.nodeAddr,
+		"ttl":   300,
+	}
+
+	body, err := json.Marshal(reqBody)
+	if err != nil {
+		return fmt.Errorf("marshal create request: %w", err)
+	}
+
+	url := fmt.Sprintf("%s/v1/zones/%s/records", d.serverURL, d.zone)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("create record request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+d.token)
+
+	resp, err := d.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("create record: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("create record: mcns returned %d: %s", resp.StatusCode, string(respBody))
+	}
+
+	return nil
+}
+
+// updateRecord updates an existing record's value.
+func (d *DNSRegistrar) updateRecord(ctx context.Context, recordID int, serviceName string) error {
+	reqBody := map[string]interface{}{
+		"name":  serviceName,
+		"type":  "A",
+		"value": d.nodeAddr,
+		"ttl":   300,
+	}
+
+	body, err := json.Marshal(reqBody)
+	if err != nil {
+		return fmt.Errorf("marshal update request: %w", err)
+	}
+
+	url := fmt.Sprintf("%s/v1/zones/%s/records/%d", d.serverURL, d.zone, recordID)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, url, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("create update request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+d.token)
+
+	resp, err := d.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("update record: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("update record: mcns returned %d: %s", resp.StatusCode, string(respBody))
+	}
+
+	return nil
+}
+
+// deleteRecord deletes a record by ID.
+func (d *DNSRegistrar) deleteRecord(ctx context.Context, recordID int) error {
+	url := fmt.Sprintf("%s/v1/zones/%s/records/%d", d.serverURL, d.zone, recordID)
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, url, nil)
+	if err != nil {
+		return fmt.Errorf("create delete request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+d.token)
+
+	resp, err := d.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("delete record: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusNoContent && resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("delete record: mcns returned %d: %s", resp.StatusCode, string(respBody))
+	}
+
+	return nil
+}

internal/agent/dns_test.go

@@ -0,0 +1,214 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"git.wntrmute.dev/mc/mcp/internal/config"
+)
+
+func TestNilDNSRegistrarIsNoop(t *testing.T) {
+	var d *DNSRegistrar
+	if err := d.EnsureRecord(context.Background(), "svc"); err != nil {
+		t.Fatalf("EnsureRecord on nil: %v", err)
+	}
+	if err := d.RemoveRecord(context.Background(), "svc"); err != nil {
+		t.Fatalf("RemoveRecord on nil: %v", err)
+	}
+}
+
+func TestNewDNSRegistrarDisabledWhenUnconfigured(t *testing.T) {
+	d, err := NewDNSRegistrar(config.MCNSConfig{}, slog.Default())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if d != nil {
+		t.Fatal("expected nil registrar for empty config")
+	}
+}
+
+func TestEnsureRecordCreatesWhenMissing(t *testing.T) {
+	var gotMethod, gotPath, gotAuth string
+	var gotBody map[string]interface{}
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			// List returns empty — no existing records.
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"records":[]}`))
+			return
+		}
+		gotMethod = r.Method
+		gotPath = r.URL.Path
+		gotAuth = r.Header.Get("Authorization")
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		w.WriteHeader(http.StatusCreated)
+		_, _ = w.Write([]byte(`{"id":1}`))
+	}))
+	defer srv.Close()
+
+	d := &DNSRegistrar{
+		serverURL:  srv.URL,
+		token:      "test-token",
+		zone:       "svc.mcp.metacircular.net",
+		nodeAddr:   "192.168.88.181",
+		httpClient: srv.Client(),
+		logger:     slog.Default(),
+	}
+
+	if err := d.EnsureRecord(context.Background(), "myservice"); err != nil {
+		t.Fatalf("EnsureRecord: %v", err)
+	}
+
+	if gotMethod != http.MethodPost {
+		t.Fatalf("method: got %q, want POST", gotMethod)
+	}
+	if gotPath != "/v1/zones/svc.mcp.metacircular.net/records" {
+		t.Fatalf("path: got %q", gotPath)
+	}
+	if gotAuth != "Bearer test-token" {
+		t.Fatalf("auth: got %q", gotAuth)
+	}
+	if gotBody["name"] != "myservice" {
+		t.Fatalf("name: got %v", gotBody["name"])
+	}
+	if gotBody["type"] != "A" {
+		t.Fatalf("type: got %v", gotBody["type"])
+	}
+	if gotBody["value"] != "192.168.88.181" {
+		t.Fatalf("value: got %v", gotBody["value"])
+	}
+}
+
+func TestEnsureRecordSkipsWhenExists(t *testing.T) {
+	createCalled := false
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			// Return an existing record with the correct value.
+			resp := map[string][]dnsRecord{"records": {{ID: 1, Name: "myservice", Type: "A", Value: "192.168.88.181", TTL: 300}}}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(resp)
+			return
+		}
+		createCalled = true
+		w.WriteHeader(http.StatusCreated)
+	}))
+	defer srv.Close()
+
+	d := &DNSRegistrar{
+		serverURL:  srv.URL,
+		token:      "test-token",
+		zone:       "svc.mcp.metacircular.net",
+		nodeAddr:   "192.168.88.181",
+		httpClient: srv.Client(),
+		logger:     slog.Default(),
+	}
+
+	if err := d.EnsureRecord(context.Background(), "myservice"); err != nil {
+		t.Fatalf("EnsureRecord: %v", err)
+	}
+	if createCalled {
+		t.Fatal("should not create when record already exists with correct value")
+	}
+}
+
+func TestEnsureRecordUpdatesWrongValue(t *testing.T) {
+	var gotMethod string
+	var gotPath string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			// Return a record with a stale value.
+			resp := map[string][]dnsRecord{"records": {{ID: 42, Name: "myservice", Type: "A", Value: "10.0.0.1", TTL: 300}}}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(resp)
+			return
+		}
+		gotMethod = r.Method
+		gotPath = r.URL.Path
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	d := &DNSRegistrar{
+		serverURL:  srv.URL,
+		token:      "test-token",
+		zone:       "svc.mcp.metacircular.net",
+		nodeAddr:   "192.168.88.181",
+		httpClient: srv.Client(),
+		logger:     slog.Default(),
+	}
+
+	if err := d.EnsureRecord(context.Background(), "myservice"); err != nil {
+		t.Fatalf("EnsureRecord: %v", err)
+	}
+	if gotMethod != http.MethodPut {
+		t.Fatalf("method: got %q, want PUT", gotMethod)
+	}
+	if gotPath != "/v1/zones/svc.mcp.metacircular.net/records/42" {
+		t.Fatalf("path: got %q", gotPath)
+	}
+}
+
+func TestRemoveRecordDeletes(t *testing.T) {
+	var gotMethod, gotPath string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			resp := map[string][]dnsRecord{"records": {{ID: 7, Name: "myservice", Type: "A", Value: "192.168.88.181", TTL: 300}}}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(resp)
+			return
+		}
+		gotMethod = r.Method
+		gotPath = r.URL.Path
+		w.WriteHeader(http.StatusNoContent)
+	}))
+	defer srv.Close()
+
+	d := &DNSRegistrar{
+		serverURL:  srv.URL,
+		token:      "test-token",
+		zone:       "svc.mcp.metacircular.net",
+		nodeAddr:   "192.168.88.181",
+		httpClient: srv.Client(),
+		logger:     slog.Default(),
+	}
+
+	if err := d.RemoveRecord(context.Background(), "myservice"); err != nil {
+		t.Fatalf("RemoveRecord: %v", err)
+	}
+	if gotMethod != http.MethodDelete {
+		t.Fatalf("method: got %q, want DELETE", gotMethod)
+	}
+	if gotPath != "/v1/zones/svc.mcp.metacircular.net/records/7" {
+		t.Fatalf("path: got %q", gotPath)
+	}
+}
+
+func TestRemoveRecordNoopWhenMissing(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// List returns empty.
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"records":[]}`))
+	}))
+	defer srv.Close()
+
+	d := &DNSRegistrar{
+		serverURL:  srv.URL,
+		token:      "test-token",
+		zone:       "svc.mcp.metacircular.net",
+		nodeAddr:   "192.168.88.181",
+		httpClient: srv.Client(),
+		logger:     slog.Default(),
+	}
+
+	if err := d.RemoveRecord(context.Background(), "myservice"); err != nil {
+		t.Fatalf("RemoveRecord: %v", err)
+	}
+}

internal/agent/lifecycle.go

@@ -37,6 +37,13 @@ func (a *Agent) StopService(ctx context.Context, req *mcpv1.StopServiceRequest)
 			}
 		}
 
+		// Remove DNS record when stopping the service.
+		if len(c.Routes) > 0 && a.DNS != nil {
+			if err := a.DNS.RemoveRecord(ctx, req.GetName()); err != nil {
+				a.Logger.Warn("failed to remove DNS record", "service", req.GetName(), "err", err)
+			}
+		}
+
 		if err := a.Runtime.Stop(ctx, containerName); err != nil {
 			a.Logger.Info("stop container (ignored)", "container", containerName, "error", err)
 		}

internal/agent/sync.go

@@ -157,6 +157,24 @@ func (a *Agent) reconcileUntracked(ctx context.Context, known map[string]bool) e
 
 // protoToComponent converts a proto ComponentSpec to a registry Component.
 func protoToComponent(service string, cs *mcpv1.ComponentSpec, desiredState string) *registry.Component {
+	var routes []registry.Route
+	for _, r := range cs.GetRoutes() {
+		mode := r.GetMode()
+		if mode == "" {
+			mode = "l4"
+		}
+		name := r.GetName()
+		if name == "" {
+			name = "default"
+		}
+		routes = append(routes, registry.Route{
+			Name:     name,
+			Port:     int(r.GetPort()),
+			Mode:     mode,
+			Hostname: r.GetHostname(),
+		})
+	}
+
 	return &registry.Component{
 		Name:         cs.GetName(),
 		Service:      service,
@@ -167,6 +185,7 @@ func protoToComponent(service string, cs *mcpv1.ComponentSpec, desiredState stri
 		Ports:        cs.GetPorts(),
 		Volumes:      cs.GetVolumes(),
 		Cmd:          cs.GetCmd(),
+		Routes:       routes,
 		DesiredState: desiredState,
 		Version:      runtime.ExtractVersion(cs.GetImage()),
 	}

internal/config/agent.go

@@ -16,6 +16,7 @@ type AgentConfig struct {
 	Agent     AgentSettings   `toml:"agent"`
 	MCProxy   MCProxyConfig   `toml:"mcproxy"`
 	Metacrypt MetacryptConfig `toml:"metacrypt"`
+	MCNS      MCNSConfig      `toml:"mcns"`
 	Monitor   MonitorConfig   `toml:"monitor"`
 	Log       LogConfig       `toml:"log"`
 }
@@ -40,6 +41,26 @@ type MetacryptConfig struct {
 	TokenPath string `toml:"token_path"`
 }
 
+// MCNSConfig holds the MCNS DNS integration settings for automated
+// DNS record registration. If ServerURL is empty, DNS registration
+// is disabled.
+type MCNSConfig struct {
+	// ServerURL is the MCNS API base URL (e.g. "https://localhost:28443").
+	ServerURL string `toml:"server_url"`
+
+	// CACert is the path to the CA certificate for verifying MCNS's TLS.
+	CACert string `toml:"ca_cert"`
+
+	// TokenPath is the path to the MCIAS service token file.
+	TokenPath string `toml:"token_path"`
+
+	// Zone is the DNS zone for service records. Defaults to "svc.mcp.metacircular.net".
+	Zone string `toml:"zone"`
+
+	// NodeAddr is the IP address to register as the A record value.
+	NodeAddr string `toml:"node_addr"`
+}
+
 // MCProxyConfig holds the mc-proxy connection settings.
 type MCProxyConfig struct {
 	// Socket is the path to the mc-proxy gRPC admin API Unix socket.
@@ -177,6 +198,9 @@ func applyAgentDefaults(cfg *AgentConfig) {
 	if cfg.Metacrypt.Issuer == "" {
 		cfg.Metacrypt.Issuer = "infra"
 	}
+	if cfg.MCNS.Zone == "" {
+		cfg.MCNS.Zone = "svc.mcp.metacircular.net"
+	}
 }
 
 func applyAgentEnvOverrides(cfg *AgentConfig) {
@@ -213,6 +237,15 @@ func applyAgentEnvOverrides(cfg *AgentConfig) {
 	if v := os.Getenv("MCP_AGENT_METACRYPT_TOKEN_PATH"); v != "" {
 		cfg.Metacrypt.TokenPath = v
 	}
+	if v := os.Getenv("MCP_AGENT_MCNS_SERVER_URL"); v != "" {
+		cfg.MCNS.ServerURL = v
+	}
+	if v := os.Getenv("MCP_AGENT_MCNS_TOKEN_PATH"); v != "" {
+		cfg.MCNS.TokenPath = v
+	}
+	if v := os.Getenv("MCP_AGENT_MCNS_NODE_ADDR"); v != "" {
+		cfg.MCNS.NodeAddr = v
+	}
 }
 
 func validateAgentConfig(cfg *AgentConfig) error {

internal/config/config_test.go

@@ -171,6 +171,11 @@ func TestLoadAgentConfig(t *testing.T) {
 	if cfg.Metacrypt.Issuer != "infra" {
 		t.Fatalf("metacrypt.issuer default: got %q, want infra", cfg.Metacrypt.Issuer)
 	}
+
+	// MCNS defaults when section is omitted.
+	if cfg.MCNS.Zone != "svc.mcp.metacircular.net" {
+		t.Fatalf("mcns.zone default: got %q, want svc.mcp.metacircular.net", cfg.MCNS.Zone)
+	}
 }
 
 func TestCLIConfigValidation(t *testing.T) {
@@ -521,6 +526,81 @@ node_name = "rift"
 	}
 }
 
+func TestAgentConfigMCNS(t *testing.T) {
+	cfgStr := `
+[server]
+grpc_addr = "0.0.0.0:9444"
+tls_cert  = "/srv/mcp/cert.pem"
+tls_key   = "/srv/mcp/key.pem"
+[database]
+path = "/srv/mcp/mcp.db"
+[mcias]
+server_url   = "https://mcias.metacircular.net:8443"
+service_name = "mcp-agent"
+[agent]
+node_name = "rift"
+[mcns]
+server_url = "https://localhost:28443"
+ca_cert    = "/srv/mcp/certs/metacircular-ca.pem"
+token_path = "/srv/mcp/metacrypt-token"
+zone       = "custom.zone"
+node_addr  = "10.0.0.1"
+`
+	path := writeTempConfig(t, cfgStr)
+	cfg, err := LoadAgentConfig(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+
+	if cfg.MCNS.ServerURL != "https://localhost:28443" {
+		t.Fatalf("mcns.server_url: got %q", cfg.MCNS.ServerURL)
+	}
+	if cfg.MCNS.CACert != "/srv/mcp/certs/metacircular-ca.pem" {
+		t.Fatalf("mcns.ca_cert: got %q", cfg.MCNS.CACert)
+	}
+	if cfg.MCNS.Zone != "custom.zone" {
+		t.Fatalf("mcns.zone: got %q", cfg.MCNS.Zone)
+	}
+	if cfg.MCNS.NodeAddr != "10.0.0.1" {
+		t.Fatalf("mcns.node_addr: got %q", cfg.MCNS.NodeAddr)
+	}
+}
+
+func TestAgentConfigMCNSEnvOverrides(t *testing.T) {
+	minimal := `
+[server]
+grpc_addr = "0.0.0.0:9444"
+tls_cert  = "/srv/mcp/cert.pem"
+tls_key   = "/srv/mcp/key.pem"
+[database]
+path = "/srv/mcp/mcp.db"
+[mcias]
+server_url   = "https://mcias.metacircular.net:8443"
+service_name = "mcp-agent"
+[agent]
+node_name = "rift"
+`
+	t.Setenv("MCP_AGENT_MCNS_SERVER_URL", "https://override:28443")
+	t.Setenv("MCP_AGENT_MCNS_TOKEN_PATH", "/override/token")
+	t.Setenv("MCP_AGENT_MCNS_NODE_ADDR", "10.0.0.99")
+
+	path := writeTempConfig(t, minimal)
+	cfg, err := LoadAgentConfig(path)
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+
+	if cfg.MCNS.ServerURL != "https://override:28443" {
+		t.Fatalf("mcns.server_url: got %q", cfg.MCNS.ServerURL)
+	}
+	if cfg.MCNS.TokenPath != "/override/token" {
+		t.Fatalf("mcns.token_path: got %q", cfg.MCNS.TokenPath)
+	}
+	if cfg.MCNS.NodeAddr != "10.0.0.99" {
+		t.Fatalf("mcns.node_addr: got %q", cfg.MCNS.NodeAddr)
+	}
+}
+
 func TestDurationParsing(t *testing.T) {
 	tests := []struct {
 		input string

internal/runtime/podman.go

@@ -199,15 +199,16 @@ func (p *Podman) Push(ctx context.Context, image string) error {
 }
 
 // ImageExists checks whether an image tag exists in a remote registry.
+// Uses skopeo inspect which works for both regular images and multi-arch
+// manifests, unlike podman manifest inspect which only handles manifests.
 func (p *Podman) ImageExists(ctx context.Context, image string) (bool, error) {
-	cmd := exec.CommandContext(ctx, p.command(), "manifest", "inspect", "docker://"+image) //nolint:gosec // args built programmatically
+	cmd := exec.CommandContext(ctx, "skopeo", "inspect", "--tls-verify=false", "docker://"+image) //nolint:gosec // args built programmatically
 	if err := cmd.Run(); err != nil {
-		// Exit code 1 means the manifest was not found.
 		var exitErr *exec.ExitError
-		if ok := errors.As(err, &exitErr); ok && exitErr.ExitCode() == 1 {
+		if ok := errors.As(err, &exitErr); ok && exitErr.ExitCode() != 0 {
 			return false, nil
 		}
-		return false, fmt.Errorf("podman manifest inspect %q: %w", image, err)
+		return false, fmt.Errorf("skopeo inspect %q: %w", image, err)
 	}
 	return true, nil
 }

internal/runtime/runtime_test.go

@@ -90,18 +90,19 @@ func TestBuildRunArgs(t *testing.T) {
 	})
 
 	t.Run("full spec with env", func(t *testing.T) {
+		// Route-allocated ports: host port = container port (matches $PORT).
 		spec := ContainerSpec{
 			Name:    "svc-api",
 			Image:   "img:latest",
 			Network: "net",
-			Ports:   []string{"127.0.0.1:12345:8443"},
+			Ports:   []string{"127.0.0.1:12345:12345"},
 			Volumes: []string{"/srv:/srv"},
 			Env:     []string{"PORT=12345"},
 		}
 		requireEqualArgs(t, p.BuildRunArgs(spec), []string{
 			"run", "-d", "--name", "svc-api",
 			"--network", "net",
-			"-p", "127.0.0.1:12345:8443",
+			"-p", "127.0.0.1:12345:12345",
 			"-v", "/srv:/srv",
 			"-e", "PORT=12345",
 			"img:latest",

proto/mcp/v1/mcp.proto

@@ -38,7 +38,7 @@ service McpAgentService {
 
 message RouteSpec {
   string name = 1;      // route name (used for $PORT_<NAME>)
-  int32 port = 2;       // external port on mc-proxy
+  int32 port = 2;       // mc-proxy listener port (e.g. 443, 8443, 9443); NOT the container internal port
   string mode = 3;      // "l4" or "l7"
   string hostname = 4;  // optional public hostname override
 }