feat: auto-resolve base images for all drivers

Author: mostlydev

cmd/claw/agent.go

@@ -623,7 +623,7 @@ func resolveAgentAddConfig(ctx *agentAddContext, opts agentAddOptions) (*agentAd
 
 	if cfg.ClawType == "" {
 		if promptMode {
-				value, err := promptSelect(reader, os.Stdout, "Claw type", []string{"openclaw", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "hermes", "generic"}, 0)
+			value, err := promptSelect(reader, os.Stdout, "Claw type", scaffoldClawTypes, 0)
 			if err != nil {
 				return nil, err
 			}
@@ -1013,7 +1013,7 @@ func rewireContracts(servicesNode *yaml.Node, sourcePath, targetPath string) int
 
 func init() {
 	agentAddCmd.Flags().StringVar(&agentNameFlag, "agent", "", "Agent name (service and directory name)")
-	agentAddCmd.Flags().StringVar(&agentTypeFlag, "type", "", "Claw type (openclaw, nanoclaw, microclaw, nullclaw, nanobot, picoclaw, hermes, generic)")
+	agentAddCmd.Flags().StringVar(&agentTypeFlag, "type", "", "Claw type ("+strings.Join(scaffoldClawTypes, ", ")+")")
 	agentAddCmd.Flags().StringVar(&agentModelFlag, "model", "", "Primary model (provider/model)")
 	agentAddCmd.Flags().StringVar(&agentCllamaFlag, "cllama", "", "Use cllama proxy (yes/no/inherit)")
 	agentAddCmd.Flags().StringVar(&agentPlatformFlag, "platform", "", "Platform handle (discord, slack, telegram, none)")

cmd/claw/agent_test.go

@@ -170,12 +170,12 @@ func TestAgentAddTypeDefaults(t *testing.T) {
 		baseImage string
 	}{
 		{name: "generic", agentName: "genericone", clawType: "generic", baseImage: "alpine:3.20"},
-		{name: "nanoclaw", agentName: "nanoclawone", clawType: "nanoclaw", baseImage: "node:22-slim"},
-		{name: "microclaw", agentName: "microclawone", clawType: "microclaw", baseImage: "node:22-slim"},
-		{name: "nullclaw", agentName: "nullclawone", clawType: "nullclaw", baseImage: "node:22-slim"},
+		{name: "hermes", agentName: "hermesone", clawType: "hermes", baseImage: "hermes:latest"},
+		{name: "nanoclaw", agentName: "nanoclawone", clawType: "nanoclaw", baseImage: "nanoclaw-orchestrator:latest"},
+		{name: "microclaw", agentName: "microclawone", clawType: "microclaw", baseImage: "microclaw:latest"},
+		{name: "nullclaw", agentName: "nullclawone", clawType: "nullclaw", baseImage: "nullclaw:latest"},
 		{name: "nanobot", agentName: "nanobotone", clawType: "nanobot", baseImage: "nanobot:latest"},
-		{name: "picoclaw", agentName: "picoclawone", clawType: "picoclaw", baseImage: "docker.io/sipeed/picoclaw:latest"},
-		{name: "hermes", agentName: "hermesone", clawType: "hermes", baseImage: "ghcr.io/mostlydev/hermes-base:v2026.3.17"},
+		{name: "picoclaw", agentName: "picoclawone", clawType: "picoclaw", baseImage: "picoclaw:latest"},
 	}
 
 	for _, tc := range tests {
@@ -217,7 +217,7 @@ func TestAgentAddTypeFlagUsageListsAllScaffoldTypes(t *testing.T) {
 	}
 
 	usage := flag.Usage
-	for _, typ := range []string{"openclaw", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "hermes", "generic"} {
+	for _, typ := range []string{"openclaw", "hermes", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "generic"} {
 		if !strings.Contains(usage, typ) {
 			t.Fatalf("expected agent add --type usage to include %q, got: %s", typ, usage)
 		}

cmd/claw/compose_test.go

@@ -82,7 +82,7 @@ func TestResolveComposeGeneratedPathWithPodFileMissingGenerated(t *testing.T) {
 }
 
 func TestBuiltinDriversRegistered(t *testing.T) {
-	for _, clawType := range []string{"openclaw", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw"} {
+	for _, clawType := range []string{"openclaw", "hermes", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw"} {
 		if _, err := driver.Lookup(clawType); err != nil {
 			t.Fatalf("expected driver %q to be registered in CLI package: %v", clawType, err)
 		}

cmd/claw/init.go

@@ -431,7 +431,7 @@ func resolveInitConfig(dir string, opts initScaffoldOptions, interactive bool) (
 
 	if cfg.ClawType == "" {
 		if interactive {
-				v, err := promptSelect(reader, os.Stdout, "Claw type", []string{"openclaw", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "hermes", "generic"}, 0)
+			v, err := promptSelect(reader, os.Stdout, "Claw type", scaffoldClawTypes, 0)
 			if err != nil {
 				return nil, fmt.Errorf("prompt claw type: %w", err)
 			}
@@ -695,7 +695,7 @@ func init() {
 	initCmd.Flags().StringVar(&initFromPath, "from", "", "Path to existing OpenClaw config directory to migrate from")
 	initCmd.Flags().StringVar(&initProject, "project", "", "Project name used for x-claw.pod and image prefix")
 	initCmd.Flags().StringVar(&initAgent, "agent", "", "Primary agent name (service + directory name)")
-	initCmd.Flags().StringVar(&initType, "type", "", "Claw type (openclaw, nanoclaw, microclaw, nullclaw, nanobot, picoclaw, hermes, generic)")
+	initCmd.Flags().StringVar(&initType, "type", "", "Claw type ("+strings.Join(scaffoldClawTypes, ", ")+")")
 	initCmd.Flags().StringVar(&initModel, "model", "", "Primary model (provider/model)")
 	initCmd.Flags().StringVar(&initCllama, "cllama", "", "Use cllama proxy (yes/no)")
 	initCmd.Flags().StringVar(&initPlatform, "platform", "", "Platform handle (discord, slack, telegram, none)")

cmd/claw/init_test.go

@@ -126,12 +126,12 @@ func TestInitScaffoldTypeDefaults(t *testing.T) {
 		baseImage string
 	}{
 		{name: "generic", clawType: "generic", baseImage: "alpine:3.20"},
-		{name: "nanoclaw", clawType: "nanoclaw", baseImage: "node:22-slim"},
-		{name: "microclaw", clawType: "microclaw", baseImage: "node:22-slim"},
-		{name: "nullclaw", clawType: "nullclaw", baseImage: "node:22-slim"},
+		{name: "hermes", clawType: "hermes", baseImage: "hermes:latest"},
+		{name: "nanoclaw", clawType: "nanoclaw", baseImage: "nanoclaw-orchestrator:latest"},
+		{name: "microclaw", clawType: "microclaw", baseImage: "microclaw:latest"},
+		{name: "nullclaw", clawType: "nullclaw", baseImage: "nullclaw:latest"},
 		{name: "nanobot", clawType: "nanobot", baseImage: "nanobot:latest"},
-		{name: "picoclaw", clawType: "picoclaw", baseImage: "docker.io/sipeed/picoclaw:latest"},
-		{name: "hermes", clawType: "hermes", baseImage: "ghcr.io/mostlydev/hermes-base:v2026.3.17"},
+		{name: "picoclaw", clawType: "picoclaw", baseImage: "picoclaw:latest"},
 	}
 
 	for _, tc := range tests {
@@ -163,7 +163,7 @@ func TestInitTypeFlagUsageListsAllScaffoldTypes(t *testing.T) {
 	}
 
 	usage := flag.Usage
-	for _, typ := range []string{"openclaw", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "hermes", "generic"} {
+	for _, typ := range []string{"openclaw", "hermes", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "generic"} {
 		if !strings.Contains(usage, typ) {
 			t.Fatalf("expected init --type usage to include %q, got: %s", typ, usage)
 		}

cmd/claw/scaffold_helpers.go

@@ -22,6 +22,8 @@ const (
 
 var validNamePattern = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_-]*$`)
 
+var scaffoldClawTypes = []string{"openclaw", "hermes", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "generic"}
+
 func shouldPromptInteractively() bool {
 	info, err := os.Stdin.Stat()
 	if err != nil {
@@ -153,29 +155,29 @@ func parseClawType(value string) (string, error) {
 	switch v {
 	case "":
 		return "", fmt.Errorf("claw type is required")
-	case "openclaw", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "hermes", "generic":
+	case "openclaw", "hermes", "nanoclaw", "microclaw", "nullclaw", "nanobot", "picoclaw", "generic":
 		return v, nil
 	default:
-		return "", fmt.Errorf("invalid claw type %q (allowed: openclaw, nanoclaw, microclaw, nullclaw, nanobot, picoclaw, hermes, generic)", value)
+		return "", fmt.Errorf("invalid claw type %q (allowed: %s)", value, strings.Join(scaffoldClawTypes, ", "))
 	}
 }
 
 func defaultBaseImageForClawType(clawType string) string {
 	switch strings.TrimSpace(strings.ToLower(clawType)) {
 	case "openclaw":
 		return "openclaw:latest"
+	case "hermes":
+		return "hermes:latest"
 	case "nanoclaw":
-		return "node:22-slim"
+		return "nanoclaw-orchestrator:latest"
 	case "microclaw":
-		return "node:22-slim"
+		return "microclaw:latest"
 	case "nullclaw":
-		return "node:22-slim"
+		return "nullclaw:latest"
 	case "nanobot":
 		return "nanobot:latest"
 	case "picoclaw":
-		return "docker.io/sipeed/picoclaw:latest"
-	case "hermes":
-		return "ghcr.io/mostlydev/hermes-base:v2026.3.17"
+		return "picoclaw:latest"
 	case "generic":
 		return "alpine:3.20"
 	default:

cmd/claw/scaffold_helpers_test.go

@@ -8,12 +8,12 @@ import (
 func TestParseClawTypeAcceptsSupportedValues(t *testing.T) {
 	tests := []string{
 		"openclaw",
+		"hermes",
 		"nanoclaw",
 		"microclaw",
 		"nullclaw",
 		"nanobot",
 		"picoclaw",
-		"hermes",
 		"generic",
 	}
 
@@ -36,8 +36,10 @@ func TestParseClawTypeRejectsUnknownValue(t *testing.T) {
 	if !strings.Contains(err.Error(), "invalid claw type") {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if !strings.Contains(err.Error(), "nanobot") || !strings.Contains(err.Error(), "hermes") {
-		t.Fatalf("expected error to list nanobot/hermes, got: %v", err)
+	for _, expected := range []string{"hermes", "nanobot", "picoclaw"} {
+		if !strings.Contains(err.Error(), expected) {
+			t.Fatalf("expected error to list %s, got: %v", expected, err)
+		}
 	}
 }
 
@@ -48,12 +50,12 @@ func TestDefaultBaseImageForClawType(t *testing.T) {
 		want     string
 	}{
 		{name: "openclaw", clawType: "openclaw", want: "openclaw:latest"},
-		{name: "nanoclaw", clawType: "nanoclaw", want: "node:22-slim"},
-		{name: "microclaw", clawType: "microclaw", want: "node:22-slim"},
-		{name: "nullclaw", clawType: "nullclaw", want: "node:22-slim"},
+		{name: "hermes", clawType: "hermes", want: "hermes:latest"},
+		{name: "nanoclaw", clawType: "nanoclaw", want: "nanoclaw-orchestrator:latest"},
+		{name: "microclaw", clawType: "microclaw", want: "microclaw:latest"},
+		{name: "nullclaw", clawType: "nullclaw", want: "nullclaw:latest"},
 		{name: "nanobot", clawType: "nanobot", want: "nanobot:latest"},
-		{name: "picoclaw", clawType: "picoclaw", want: "docker.io/sipeed/picoclaw:latest"},
-		{name: "hermes", clawType: "hermes", want: "ghcr.io/mostlydev/hermes-base:v2026.3.17"},
+		{name: "picoclaw", clawType: "picoclaw", want: "picoclaw:latest"},
 		{name: "generic", clawType: "generic", want: "alpine:3.20"},
 		{name: "unknown", clawType: "something-else", want: "alpine:3.20"},
 	}

docs/plans/2026-03-21-base-image-provider-all-drivers.md

@@ -0,0 +1,119 @@
+# Base Image Auto-Resolution for All Drivers
+
+**Date:** 2026-03-21
+**Status:** Approved
+
+## Problem
+
+Most Clawfiles in-tree use repo-local driver tags such as `openclaw:latest`, `hermes:latest`, `microclaw:latest`, and `nullclaw:latest`, but not all of them. Current exceptions include:
+
+- `examples/picoclaw/Clawfile` using `FROM docker.io/sipeed/picoclaw:latest`
+- nanoclaw examples using `FROM nanoclaw-orchestrator:latest`
+
+Today, only the openclaw driver implements `BaseImageProvider`, so only it auto-builds when the local base image is missing. Users of the other six drivers must manually build or pull base images before `claw build` works.
+
+Maintaining Clawdapus-owned pre-built images for every runtime is the wrong burden. Some upstreams already publish official images, some publish installers or packages, and nanoclaw currently needs a Clawdapus-compatible orchestrator wrapper. The implementation needs to follow the packaging reality of each driver instead of forcing one recipe style onto all of them.
+
+## Solution
+
+Each driver ships a `baseimage.go` file implementing `BaseImageProvider`. When `claw build` encounters a missing `FROM` image, the existing `ensureBaseImage()` in `internal/build/build.go` already handles resolution — no changes needed to the build pipeline. We just need to fill in the missing implementations.
+
+Each `baseimage.go` produces a self-contained Dockerfile string. The rule is:
+
+- prefer the real upstream packaging path
+- use a local compatibility alias over an official upstream image when that is the upstream distribution model
+- use a source-build wrapper only when no stable published base fits the current Clawdapus runtime contract
+
+That keeps the images real, but avoids rebuilding tooling that upstream already ships.
+
+## Per-Driver Dockerfile Recipes
+
+### openclaw (already exists — no changes)
+
+- Base: `node:22-slim`
+- Install: `curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard --method npm`
+- Entrypoint: `openclaw gateway --port 18789 --bind loopback`
+- Extras: build-essential, python3, cmake (native deps for npm packages)
+
+### hermes
+
+- Tag: `hermes:latest`
+- Base: `ghcr.io/astral-sh/uv:python3.11-bookworm-slim`
+- Install: clone `https://github.com/NousResearch/hermes-agent` and `uv pip install --system "/opt/hermes-agent[messaging,cron]"`
+- Entrypoint: `hermes gateway start`
+- Extras: `bash`, `ca-certificates`, `curl`, `git`, `jq`, `procps`, `tini`
+- Notes: use the real Hermes repo and install the packaged CLI entrypoint instead of a stub shell script
+
+### nanobot
+
+- Tag: `nanobot:latest`
+- Base: `ghcr.io/astral-sh/uv:python3.12-bookworm-slim`
+- Install: `uv pip install --system --no-cache nanobot-ai`
+- Entrypoint: `nanobot gateway`
+- Extras: `ca-certificates`, `curl`, `git`, `jq`, `procps`, `tini`
+
+### picoclaw
+
+- Tag: `picoclaw:latest`
+- Base: `docker.io/sipeed/picoclaw:latest`
+- Install: none; local base image is a compatibility alias over the upstream image
+- Entrypoint: `picoclaw gateway`
+- Extras: inherit upstream runtime as-is
+- Notes: this keeps the local `picoclaw:latest` tag usable for auto-resolution without forking the upstream container recipe
+
+### nullclaw
+
+- Tag: `nullclaw:latest`
+- Base: `ghcr.io/nullclaw/nullclaw:latest`
+- Install: none; local base image is a compatibility alias over the upstream image
+- Entrypoint: inherited upstream `nullclaw gateway --port 3000 --host ::`
+- Extras: inherit upstream runtime as-is
+- Notes: this avoids reimplementing the upstream Zig build and preserves the current HOME/config behavior the driver already targets
+
+### microclaw
+
+- Tag: `microclaw:latest`
+- Base: `ghcr.io/microclaw/microclaw:latest`
+- Install: add `procps` and create `/app/config` for the file mount used by the driver
+- Entrypoint: `microclaw start`
+- Extras: inherit upstream runtime plus `procps`
+- Notes: the upstream image is the real runtime; the only local change is making the image satisfy Clawdapus healthcheck and mount assumptions
+
+### nanoclaw
+
+- Tag: `nanoclaw-orchestrator:latest`
+- Builder: `node:22-bookworm-slim` + clone `https://github.com/qwibitai/nanoclaw.git` + `npm ci && npm run build`
+- Runtime: `node:22-bookworm-slim` + Docker CLI copied from `docker:27-cli`
+- Entrypoint: `node /workspace/dist/index.js`
+- Extras: `ca-certificates`, `git`, `procps`, `python3`, `make`, `g++`, `tini`, global `@anthropic-ai/claude-code`
+- Notes: nanoclaw is the one driver that still needs a source-build compatibility image because Clawdapus expects an orchestrator container with Docker CLI access and Claude Code SDK wiring
+
+## File Layout
+
+### New files (one per driver)
+
+- `internal/driver/hermes/baseimage.go`
+- `internal/driver/nanobot/baseimage.go`
+- `internal/driver/nanoclaw/baseimage.go`
+- `internal/driver/nullclaw/baseimage.go`
+- `internal/driver/microclaw/baseimage.go`
+- `internal/driver/picoclaw/baseimage.go`
+
+### New test files (one per driver)
+
+- `internal/driver/<name>/baseimage_test.go` — same pattern as openclaw: assert interface satisfaction, non-empty tag/dockerfile
+
+### No changes needed
+
+- `internal/build/build.go` — `ensureBaseImage()` already handles the resolution
+- `internal/driver/types.go` — `BaseImageProvider` interface already exists
+- `internal/driver/openclaw/baseimage.go` — already correct
+- Rollcall `Dockerfile.*-base` files — stay as spike test fixtures
+
+### Adjacent doc cleanup
+
+- fix stale Hermes upstream references to point at `https://github.com/NousResearch/hermes-agent`
+
+## Follow-up
+
+- optional cleanup: decide later whether to standardize `examples/picoclaw/Clawfile` on local `picoclaw:latest`; the current fully qualified upstream image still works via Docker's normal pull path

examples/quickstart/README.md

@@ -40,10 +40,12 @@ cp .env.example .env
 
 ```bash
 source .env
-claw build -t quickstart-assistant ./agents/assistant
+claw build -t quickstart-assistant:latest ./agents/assistant
 claw up -f claw-pod.yml -d
 ```
 
+On the first run, `claw build` auto-builds the local `openclaw:latest` base image if it is missing.
+
 ## 4. Verify
 
 ```bash