feat: add local container provider

* feat: add local container provider

* fix: harden local container bootstrap

* fix: clean local container lease keys

* fix: reject local container actions runners

Author: steipete

CHANGELOG.md

@@ -11,6 +11,7 @@
 - Added explicit AWS Fast Snapshot Restore promotion support for hot developer-image AMIs via `crabbox image promote --fast-snapshot-restore --fsr-az <az>` and the AWS developer-image mint wrapper.
 - Added `crabbox image fsr-status` and the coordinator Fast Snapshot Restore status route for checking live AWS snapshot/AZ state after promotion.
 - Added a light/dark mode toggle to the Crabbox documentation site that defaults to the system color scheme, persists the choice in local storage, and applies before first paint to avoid a flash.
+- Added `provider: local-container` with `docker`, `container`, and `local-docker` aliases for local Linux container leases and optional desktop/browser/WebVNC smoke boxes through Docker-compatible runtimes such as Docker Desktop, OrbStack, and Colima.
 
 ### Changed
 

README.md

@@ -32,6 +32,9 @@ Supported providers:
   direct Linux VMs.
 - [Proxmox](docs/providers/proxmox.md) (`provider: proxmox`): direct Linux QEMU
   VM clones from private Proxmox VE templates.
+- [Local Container](docs/providers/local-container.md)
+  (`provider: local-container`, alias `docker`): local Linux containers through
+  a Docker-compatible runtime such as Docker Desktop, OrbStack, or Colima.
 - [Static SSH](docs/providers/ssh.md) (`provider: ssh`): existing Linux, macOS,
   Windows, or WSL2 hosts.
 - [exe.dev](docs/providers/exe-dev.md) (`provider: exe-dev`): exe.dev VMs
@@ -304,6 +307,21 @@ exeDev:
 
 Authenticate with `ssh exe.dev`; VM creation requires an active exe.dev plan.
 
+Optional local container:
+
+```yaml
+provider: local-container
+localContainer:
+  runtime: docker
+  image: debian:bookworm
+  workRoot: /work/crabbox
+```
+
+`provider: docker` is an alias for `local-container`; the backend uses standard
+Docker-compatible CLI commands, so OrbStack works when it is the active Docker
+context. Add `--desktop --browser` for local Xvfb/XFCE/x11vnc/noVNC browser
+smoke tests before moving the same workflow to remote capacity.
+
 Optional Islo sandbox:
 
 ```yaml

docs/README.md

@@ -87,7 +87,7 @@ Pick whichever matches your intent:
 - **Start here:** [Getting started](getting-started.md), [How Crabbox Works](how-it-works.md), [Concepts and glossary](concepts.md).
 - **Get the mental model:** [Architecture](architecture.md), [Orchestrator](orchestrator.md).
 - **Use the CLI:** [CLI](cli.md), [Commands](commands/README.md), [Features](features/README.md), [Configuration](features/configuration.md), [Jobs](features/jobs.md), [Actions hydration](features/actions-hydration.md), [Capsules](features/capsules.md), [Checkpoints](features/checkpoints.md), [Browser portal](features/portal.md), [Telemetry](features/telemetry.md).
-- **Pick or add a target:** [Provider reference](providers/README.md), [Providers feature overview](features/providers.md), [Provider authoring](features/provider-authoring.md), [Provider backends](provider-backends.md), [AWS](providers/aws.md), [Azure](providers/azure.md), [Google Cloud](providers/gcp.md), [Hetzner](providers/hetzner.md), [Proxmox](providers/proxmox.md), [Parallels](providers/parallels.md), [Static SSH](providers/ssh.md), [Blacksmith Testbox](providers/blacksmith-testbox.md), [Namespace Devbox](providers/namespace-devbox.md), [Semaphore](providers/semaphore.md), [Sprites](providers/sprites.md), [Daytona](providers/daytona.md), [Islo](providers/islo.md), [E2B](providers/e2b.md), [Modal](providers/modal.md), [Tensorlake](providers/tensorlake.md), [Cloudflare](providers/cloudflare.md), [Interactive desktop and VNC](features/interactive-desktop-vnc.md).
+- **Pick or add a target:** [Provider reference](providers/README.md), [Providers feature overview](features/providers.md), [Provider authoring](features/provider-authoring.md), [Provider backends](provider-backends.md), [AWS](providers/aws.md), [Azure](providers/azure.md), [Google Cloud](providers/gcp.md), [Hetzner](providers/hetzner.md), [Proxmox](providers/proxmox.md), [Parallels](providers/parallels.md), [Local Container](providers/local-container.md), [Static SSH](providers/ssh.md), [Blacksmith Testbox](providers/blacksmith-testbox.md), [Namespace Devbox](providers/namespace-devbox.md), [Semaphore](providers/semaphore.md), [Sprites](providers/sprites.md), [Daytona](providers/daytona.md), [Islo](providers/islo.md), [E2B](providers/e2b.md), [Modal](providers/modal.md), [Tensorlake](providers/tensorlake.md), [Cloudflare](providers/cloudflare.md), [Interactive desktop and VNC](features/interactive-desktop-vnc.md).
 - **Operate it:** [Operations](operations.md), [Observability](observability.md), [Troubleshooting](troubleshooting.md), [Performance](performance.md).
 - **Set it up or audit it:** [Infrastructure](infrastructure.md), [Security](security.md), [Source Map](source-map.md).
 

docs/features/README.md

@@ -39,6 +39,7 @@ Read when:
 - [Google Cloud](../providers/gcp.md): GCP Compute Engine Linux SSH leases.
 - [Hetzner](hetzner.md): Linux-only managed Hetzner behavior, classes, and cleanup.
 - [Proxmox](../providers/proxmox.md): direct Proxmox VE Linux QEMU VM clones.
+- [Local Container](../providers/local-container.md): local Linux containers through Docker-compatible runtimes.
 - [Blacksmith Testbox](blacksmith-testbox.md): delegated Testbox backend behavior.
 - [Namespace Devbox](namespace-devbox.md): Namespace Devbox SSH leases with Crabbox sync/run.
 - [Namespace Devbox setup](namespace-devbox-setup.md): CLI install, auth token profile, and live checks.

docs/features/configuration.md

@@ -284,6 +284,29 @@ static:
   workRoot: /Users/steipete/crabbox
 ```
 
+### Local Container
+
+```yaml
+provider: local-container
+localContainer:
+  runtime: docker
+  image: debian:bookworm
+  user: crabbox
+  workRoot: /work/crabbox
+  cpus: 0
+  memory: ""
+  network: bridge
+```
+
+`provider: docker`, `provider: container`, and `provider: local-docker` are
+aliases for `local-container`. The backend uses Docker-compatible CLI commands,
+so Docker Desktop, OrbStack, Colima, and similar local runtimes work when their
+Docker context is active.
+
+Use `--desktop --browser` to bootstrap Xvfb, XFCE, x11vnc, noVNC/websockify,
+desktop input tools, screenshot tools, ffmpeg, and a packaged browser inside
+the container.
+
 ### Blacksmith Testbox
 
 ```yaml

docs/features/providers.md

@@ -30,6 +30,7 @@ Direct provider backends can also run without the Crabbox coordinator:
 ```text
 proxmox    Proxmox VE QEMU VM clones exposed as SSH leases
 parallels  Parallels Desktop linked clones exposed as SSH leases
+local-container  Local Linux containers and desktop/browser smoke boxes
 exe-dev    exe.dev VMs exposed as SSH leases
 semaphore  Semaphore CI jobs exposed as SSH leases
 namespace  Namespace Devboxes exposed as SSH leases
@@ -50,6 +51,7 @@ tensorlake Tensorlake Firecracker sandboxes with delegated command execution
 - [Hetzner](../providers/hetzner.md): Linux-only managed provider behavior, classes, and cleanup.
 - [Proxmox](../providers/proxmox.md): direct Proxmox VE Linux QEMU VM clones.
 - [Parallels](../providers/parallels.md): direct local or remote Mac Parallels Desktop VM clones, named VM snapshot templates, and small Mac fleets.
+- [Local Container](../providers/local-container.md): local Linux containers and desktop/browser smoke boxes through Docker-compatible runtimes.
 - [Static SSH](../providers/ssh.md): existing Linux, macOS, and Windows SSH hosts.
 - [exe.dev](../providers/exe-dev.md): exe.dev VMs exposed as SSH leases.
 - [Blacksmith Testbox](../providers/blacksmith-testbox.md): delegated Testbox backend behavior.
@@ -179,6 +181,12 @@ and optional snapshot, starts it, discovers the guest IP through `prlctl`, then
 uses normal Crabbox SSH sync/run/release. It supports Linux, macOS, and Windows
 templates when the guest already exposes the matching SSH contract.
 
+Use `--provider local-container` or `--provider docker` with a local
+Docker-compatible runtime for zero-cloud Linux smoke tests. The provider starts
+a labeled container, publishes SSH on loopback, syncs into the container over
+SSH, and removes it on `stop`. It does not bind-mount the repo or the Docker
+socket by default.
+
 Crabbox can also wrap Blacksmith Testboxes with `provider: blacksmith-testbox`. That backend does not use the Crabbox broker or direct cloud credentials. It shells out to the authenticated Blacksmith CLI for `testbox warmup`, `run`, `status`, `list`, and `stop`, while Crabbox keeps local slugs, repo claims, config, and timing summaries. See [Blacksmith Testbox](blacksmith-testbox.md).
 
 Crabbox can use Namespace Devboxes with `provider: namespace-devbox`. Namespace

docs/provider-backends.md

@@ -176,6 +176,7 @@ internal/providers/aws
 internal/providers/azure
 internal/providers/gcp
 internal/providers/proxmox
+internal/providers/localcontainer
 internal/providers/ssh
 internal/providers/blacksmith
 internal/providers/namespace
@@ -213,6 +214,7 @@ internal/providers/azure                  # Azure SSH lease backend
 internal/providers/gcp                    # Google Cloud SSH lease backend
 internal/providers/hetzner                # Hetzner SSH lease backend
 internal/providers/proxmox                # Proxmox VE SSH lease backend
+internal/providers/localcontainer         # local Docker-compatible container SSH backend
 internal/providers/ssh                    # static SSH backend
 internal/providers/blacksmith             # Blacksmith delegated backend
 internal/providers/namespace              # Namespace Devbox SSH backend

docs/providers/README.md

@@ -17,6 +17,7 @@ static SSH provider for existing machines.
 | [Hetzner](hetzner.md) | SSH lease | Linux | fast Linux capacity at low cost |
 | [Proxmox](proxmox.md) | SSH lease | Linux | private Proxmox VE QEMU VM templates |
 | [Parallels](parallels.md) | SSH lease | Linux, macOS, Windows | local or remote Mac Parallels template/fleet clones |
+| [Local Container](local-container.md) | SSH lease | Linux | zero-cloud Linux and desktop/browser smoke tests through Docker-compatible runtimes |
 | [Static SSH](ssh.md) | SSH lease | Linux, macOS, Windows | reusing an existing host |
 | [exe.dev](exe-dev.md) | SSH lease | Linux | disposable exe.dev VMs with Crabbox sync |
 | [Blacksmith Testbox](blacksmith-testbox.md) | delegated run | Linux | existing Blacksmith Testbox workflows |
@@ -47,6 +48,7 @@ default.
 ```sh
 crabbox warmup --provider aws --class beast
 crabbox run --provider hetzner -- pnpm test
+crabbox run --provider docker -- pnpm test
 crabbox run --provider blacksmith-testbox --id tbx_123 -- pnpm test
 crabbox run --provider namespace-devbox --id blue-lobster -- pnpm test
 ```
@@ -65,6 +67,8 @@ Proxmox and delegated providers do not use the Crabbox coordinator:
 
 - Proxmox clones private QEMU VM templates through the Proxmox VE REST API.
 - Parallels clones local or remote Mac Parallels Desktop VMs through `prlctl`.
+- Local Container starts labeled Linux containers through a Docker-compatible
+  local runtime such as Docker Desktop, OrbStack, or Colima.
 - exe.dev creates and deletes VMs through the exe.dev SSH API.
 - Blacksmith uses the authenticated Blacksmith CLI.
 - Daytona uses Daytona API and SDK/toolbox APIs.
@@ -84,11 +88,12 @@ Proxmox and delegated providers do not use the Crabbox coordinator:
   `portMappings["22"]` report the public TCP mapping, Crabbox reuses its
   normal SSH sync/run path against `root@<pod-ip>:<public-port>`.
 
-Namespace Devbox and Semaphore are SSH lease providers that do not use the
-Crabbox coordinator. Namespace provisions through the authenticated `devbox`
-CLI; Semaphore provisions through the Semaphore REST API; Sprites provisions
-through the Sprites API and reaches SSH through `sprite proxy`; exe.dev
-provisions through `ssh exe.dev` and returns a normal VM SSH target.
+Local Container, Namespace Devbox, and Semaphore are SSH lease providers that do
+not use the Crabbox coordinator. Local Container provisions through `docker`;
+Namespace provisions through the authenticated `devbox` CLI; Semaphore
+provisions through the Semaphore REST API; Sprites provisions through the
+Sprites API and reaches SSH through `sprite proxy`; exe.dev provisions through
+`ssh exe.dev` and returns a normal VM SSH target.
 
 ## Feature Matrix
 
@@ -100,6 +105,7 @@ provisions through `ssh exe.dev` and returns a normal VM SSH target.
 | Hetzner | yes | yes | yes | Linux VNC/code | yes | no |
 | Proxmox | yes | yes | yes | no | yes | no |
 | Parallels | yes | yes | yes | host-dependent | yes | no |
+| Local Container | yes | yes | yes | local VNC/WebVNC; no code | yes | no |
 | Static SSH | yes | resolves host | yes | host-dependent | yes | no |
 | exe.dev | yes | yes | yes | no | yes | no |
 | Blacksmith Testbox | yes | yes | no | no | no | yes |
@@ -116,8 +122,8 @@ provisions through `ssh exe.dev` and returns a normal VM SSH target.
 | RunPod | yes | yes | yes | no | yes | no |
 
 Actions runner hydration requires a normal SSH lease on Linux and is core-over-SSH.
-Use AWS, Google Cloud, Hetzner, Proxmox, Parallels, Static SSH, exe.dev, Namespace Devbox,
-Semaphore, Sprites, or RunPod for that path.
+Use AWS, Google Cloud, Hetzner, Proxmox, Parallels, Static SSH, exe.dev,
+Namespace Devbox, Semaphore, Sprites, or RunPod for that path.
 
 ## Implementation
 

docs/providers/local-container.md

@@ -0,0 +1,150 @@
+# Local Container Provider
+
+Read when:
+
+- choosing `provider: local-container`, `provider: docker`, or `provider: container`;
+- using Docker Desktop, OrbStack, Colima, Lima, or another Docker-compatible local runtime;
+- changing `internal/providers/localcontainer`.
+
+Local Container is an SSH lease provider for Linux containers on the local
+machine. Crabbox uses the configured Docker-compatible CLI to start a labeled
+container, publish its SSH port on loopback, syncs the current checkout into the
+container over SSH, runs the command, and removes the container on stop.
+
+## When To Use
+
+Use Local Container when:
+
+- you want a zero-cloud Linux smoke path;
+- the local Docker-compatible runtime is already warm;
+- you want a local visible desktop, browser, screenshot, or input smoke before
+  spending cloud capacity;
+- you want the same Crabbox sync, logs, artifacts, scripts, and `ssh` workflow
+  before moving to remote capacity.
+
+Use AWS, Azure, Google Cloud, Hetzner, Proxmox, or another remote provider when
+you need stronger host separation, larger capacity, cross-OS coverage,
+coordinator-backed portal desktops, shared team infrastructure, or
+provider-owned cleanup.
+
+## Quick Start
+
+```sh
+docker info
+crabbox run --provider local-container -- pnpm test
+crabbox warmup --provider docker --slug local-smoke
+crabbox run --provider docker --id local-smoke -- pnpm test:changed
+crabbox ssh --provider docker --id local-smoke
+crabbox stop --provider docker local-smoke
+```
+
+Desktop/browser smoke:
+
+```sh
+crabbox warmup --provider docker --desktop --browser --slug local-ui
+crabbox desktop doctor --provider docker --id local-ui
+crabbox screenshot --provider docker --id local-ui --output desktop.png
+crabbox desktop click --provider docker --id local-ui --x 120 --y 120
+crabbox webvnc --provider docker --id local-ui
+```
+
+`docker` is an alias for `local-container`. The provider talks only to the
+Docker-compatible CLI and daemon; it does not use Docker Desktop-specific APIs.
+OrbStack works when it is the active `docker` context.
+
+## Config
+
+```yaml
+provider: local-container
+localContainer:
+  runtime: docker
+  image: debian:bookworm
+  user: crabbox
+  workRoot: /work/crabbox
+  cpus: 0
+  memory: ""
+  network: bridge
+```
+
+Provider flags:
+
+```text
+--local-container-runtime <path-or-name>
+--local-container-image <image>
+--local-container-user <user>
+--local-container-work-root <path>
+--local-container-cpus <n>
+--local-container-memory <size>
+--local-container-network <network>
+```
+
+Environment overrides:
+
+```text
+CRABBOX_LOCAL_CONTAINER_RUNTIME
+CRABBOX_LOCAL_CONTAINER_IMAGE
+CRABBOX_LOCAL_CONTAINER_USER
+CRABBOX_LOCAL_CONTAINER_WORK_ROOT
+CRABBOX_LOCAL_CONTAINER_CPUS
+CRABBOX_LOCAL_CONTAINER_MEMORY
+CRABBOX_LOCAL_CONTAINER_NETWORK
+```
+
+## Behavior
+
+1. `warmup` or a fresh `run` creates a per-lease SSH key.
+2. The provider runs `docker run -d` with Crabbox labels, loopback SSH port
+   publishing, and public-key auth environment for the bootstrap script.
+3. The container installs `openssh-server`, `git`, `rsync`, `curl`, and `sudo`
+   when the image is Debian/Ubuntu-compatible and missing those tools.
+4. With `--desktop`, the container installs and starts Xvfb, XFCE, x11vnc,
+   xdotool, screenshot tools, ffmpeg, noVNC, and websockify without requiring
+   systemd.
+5. With `--browser`, the container installs a real package-manager browser
+   where the image provides one and writes `/var/lib/crabbox/browser.env`.
+6. Crabbox waits for SSH readiness, syncs tracked and nonignored files into
+   `localContainer.workRoot`, and uses the normal SSH executor.
+7. `status`, `list`, and `stop` inspect or remove labeled containers.
+
+## Limits
+
+- Linux target only.
+- No Crabbox coordinator support; lifecycle is local to the machine running the
+  CLI.
+- Desktop, browser, VNC, WebVNC, screenshot, video, and desktop input helpers
+  are local-only. `webvnc` starts noVNC/websockify on the target and tunnels it
+  over SSH; it does not use the authenticated Crabbox portal.
+- No code-server, Tailscale bootstrap, or native checkpoint support yet.
+- `warmup --actions-runner` is not supported; use normal `crabbox run` for
+  local container smoke tests or a remote SSH provider for GitHub runner
+  registration.
+- The Docker daemon is a powerful local capability. Do not treat this as the
+  same host isolation boundary as a remote VM or microVM.
+- The current checkout is synced into the container by default. Crabbox does not
+  bind-mount the repo or mount the Docker socket.
+- The default `debian:bookworm` image bootstraps packages on first start. Use a
+  prebuilt image with SSH/Git/rsync/desktop/browser packages when startup time
+  matters.
+
+## Runtime Notes
+
+The provider expects Docker-compatible behavior for:
+
+- `docker run`;
+- `docker ps`;
+- `docker inspect`;
+- `docker rm`;
+- labels;
+- loopback port publishing.
+
+That keeps the backend portable across Docker Desktop, OrbStack, Colima, and
+other runtimes that expose the standard Docker CLI. Remote Docker contexts are
+not the intended MVP path because Crabbox connects to the published SSH port
+from the local machine.
+
+## Related
+
+- [Provider reference](README.md)
+- [Static SSH](ssh.md)
+- [Sync](../features/sync.md)
+- [Provider backends](../provider-backends.md)