Docker Desktop Extension

README

# Shellharbor — Run OpenClaw on your Mac in one click

**Shellharbor** is a Docker Desktop extension that starts, isolates, and manages [OpenClaw](https://github.com/openclaw/openclaw) — your personal, open-source AI assistant — in a hardened, localhost-only container. After a one-line install, daily use is GUI-only.

- **One-click run** — start, stop, restart, and open the Control UI from a GUI.
- **Isolated by default** — read-only root filesystem, all capabilities dropped, `no-new-privileges`, bound to `127.0.0.1` only.
- **Managed lifecycle** — persistent state, a runtime that updates with the extension, and guided host-Ollama setup for offline local models.

*Community packaging. Not an official Docker or OpenClaw extension.*

## 60-second quick start

This repo packages OpenClaw as a Docker Desktop extension for macOS. It builds two local images, installs the extension into Docker Desktop, and gives you start/stop/restart controls plus a guided local Ollama setup flow.

Project landing page: <https://jcowhigjr.github.io/openclaw-docker-desktop-extension/>

Submission review packet: [docs/submission-readiness.md](docs/submission-readiness.md)

```bash
make install-dev
```

Optional local push guard:

```bash
make install-hooks
```

This installs the repo pre-push hook, which runs `make test-pre-push` before allowing a push.
The pre-push target also runs local security preflights where possible: Gitleaks when installed and `npm audit --audit-level=critical` for the UI package.

Then:

1. Open the `Shellharbor` extension in Docker Desktop.
2. Click `Start OpenClaw`.
3. Wait for the service status to show `OpenClaw is ready`.
4. Choose a first-run provider path in the extension:
   - `Free local (Ollama)`: detect a host Ollama model and apply it as the default, or follow the pull/install guidance when no model is ready yet.
   - `Hosted (Anthropic API key)`: continue with OpenClaw's existing provider auth or `.env` flow.
5. Click `Open Control UI`. The extension opens the canonical localhost Control UI and passes the gateway token through the URL fragment for dashboard bootstrap after a usable provider path is selected.

If Docker Desktop blocks local extensions, enable local or non-Marketplace extension installs first.

If anything fails or a chat appears to hang, run the two-minute [preflight checklist](docs/preflight-checklist.md) before debugging. Docker and Ollama are separate apps that update themselves and do not start at login; the checklist proves each one is not just running but actually able to do work.

If Manage → **Share** fails, read [user operations](docs/user-operations.md): Docker Desktop only shares Docker Hub–hosted extension images, so GHCR and unpublished installs cannot be shared.

## Fast command guide

Use these commands depending on where you are in the flow:

- `make install-dev`: build both local images and install the extension into Docker Desktop
- `make update-extension`: rebuild both local images and refresh an existing local install
- `make verify-release-tag RELEASE_TAG=vX.Y.Z`: maintainer check that the GitHub release exists, the GHCR tags and Docker Hub extension semver tag are public, and the published extension title label stayed validator-safe
- `make verify-release-bundle RELEASE_TAG=vX.Y.Z`: maintainer check that a release extension build points at the matching GHCR runtime image
- `make verify-release-install RELEASE_TAG=vX.Y.Z`: maintainer check that Docker Desktop can install and uninstall the GHCR extension image and Docker Hub Marketplace semver image
- `make publish-release RELEASE_TAG=vX.Y.Z`: maintainer fallback if a tag exists but the GitHub release needs to be repaired manually
- `make ship-release RELEASE_TAG=vX.Y.Z`: maintainer repair path that publishes the GitHub release if needed, verifies release tags, then validates Docker Desktop install/uninstall
- `make install-release RELEASE_TAG=vX.Y.Z`: install a tagged GHCR-published extension image after an anonymous GHCR preflight
- `make update-release RELEASE_TAG=vX.Y.Z`: update an installed GHCR-published extension image after the same preflight
- `make verify-release-channel RELEASE_CHANNEL=stable`: maintainer check that the floating channel tags are publicly readable
- `make verify-release-channel RELEASE_CHANNEL=stable EXPECTED_RELEASE_TAG=vX.Y.Z`: maintainer check that the floating channel still points at the intended release tag
- `make verify-channel-install RELEASE_CHANNEL=stable`: maintainer check that Docker Desktop can install and uninstall the floating channel image
- `make verify-channel-install RELEASE_CHANNEL=stable EXPECTED_RELEASE_TAG=vX.Y.Z`: maintainer check that the installable floating channel also matches the intended release tag
- `make create-smoke-report RELEASE_CHANNEL=stable RELEASE_TAG=vX.Y.Z`: scaffold a timestamped manual smoke-test packet under `docs/exploratory/`, including a best-effort `capture-artifacts.sh` helper
- `make install-channel RELEASE_CHANNEL=stable`: install the current published GHCR channel image with the same preflight
- `make update-channel RELEASE_CHANNEL=stable`: update an installed GHCR channel image with the same preflight
- add `DRY_RUN=1` to `install-release`, `update-release`, or `ship-release` to rehearse the documented release path without mutating Docker Desktop
- `make uninstall`: remove the extension from Docker Desktop
- `make capture-readme-screenshot`: rebuild the demo UI and refresh the checked-in README screenshot

## Release-image path

Tagged releases publish both images to GHCR through GitHub Actions and create the matching GitHub release automatically:

- extension image: `ghcr.io/jcowhigjr/openclaw-docker-desktop-extension:<tag>`
- runtime image: `ghcr.io/jcowhigjr/openclaw-docker-desktop-extension-runtime:<tag>`
- published architectures: `linux/arm64` and `linux/amd64`

### Automated release preparation (release-please)

On every push to `main` that touches extension-affecting paths, the **Prepare release** workflow runs [release-please](https://github.com/googleapis/release-please). It opens or updates a `chore: release X.Y.Z` pull request (docs/openspec/README-only changes are excluded). When that PR merges:

1. release-please creates a **draft** GitHub release and a `vX.Y.Z` tag (manifest baseline is `0.3.6`)
2. Prepare release calls the single **Publish** workflow with `promote_channel=true`
3. Publish builds multi-arch images, tags immutable semver + `v*` tags, and moves `stable` or `beta`

**Secret required:** repository secret `RELEASE_PLEASE_TOKEN` — a PAT that can open release PRs, create tags/releases, and invoke workflows (default `GITHUB_TOKEN` cannot re-trigger Publish from a tag it created). Without the secret, Prepare release fails closed instead of silently skipping automation.

Manual `v*` tag pushes and **Publish** `workflow_dispatch` remain supported repair paths.

The release workflow also publishes the extension image to Docker Hub for Docker Marketplace validation:

- Marketplace image: `docker.io/jcowhigjr/openclaw-docker-desktop-extension:<semver>`
- required GitHub Actions secrets: `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`

Docker's automated Marketplace submission validates the greatest semver tag on Docker Hub, so the non-`v` semver tag, for example `0.3.4`, must be public before submission.

Release builds of the extension pin the runtime to the matching GHCR runtime tag. Local development builds pin `openclaw-docker-extension-runtime:dev`.

The publish workflow also promotes both images onto floating channel tags on real tag pushes:

- `stable` for normal release tags such as `v0.2.0`
- `beta` for prerelease tags such as `v0.2.0-rc.1`

That gives end users a one-line extension install path.

Each extension release pins the runtime image it was built with. There is no separate runtime update control: installing a newer extension is how OpenClaw updates. When the extension opens (or on Start) and finds the service running an older image, it recreates the service from the pinned image and keeps the data volume. The runtime runs `openclaw doctor --fix` before the gateway starts, so OpenClaw's own migrations apply on the way up.

The standalone runtime publish workflow also refreshes `ghcr.io/jcowhigjr/openclaw-docker-desktop-extension-runtime:latest` on a daily schedule and can still be run manually with `workflow_dispatch`. It also publishes the older `ghcr.io/jcowhigjr/openclaw-docker-extension-runtime:latest` alias for existing local installs. That scheduled rebuild is how the wrapper picks up new `ghcr.io/openclaw/openclaw:latest` content when this repo has no file changes, so upstream OpenClaw updates become available after the next scheduled runtime rebuild and GHCR push, not instantly at the moment upstream publishes them.

A "what's new" surface after an update is still out of scope for MVP.

Maintainer preflight for a newly published tag:

```bash
make verify-release-tag RELEASE_TAG=vX.Y.Z
```

Local maintainer check before publishing a new tag:

```bash
make verify-release-bundle RELEASE_TAG=vX.Y.Z
```

That build-time check proves the extension bundle is wired to the matching GHCR runtime tag instead of falling back to the local dev runtime image.

That check verifies the requirements for the documented install path and Marketplace submission:

- the GitHub release exists for the tag
- both GHCR image tags exist
- both GHCR packages are public to anonymous users
- the Docker Hub extension semver tag exists for Marketplace validation
- the published extension title label remains validator-safe on GHCR and Docker Hub

If you want the full maintainer handoff in one command after the tag is published:

```bash
make ship-release RELEASE_TAG=vX.Y.Z
```

To rehearse the same maintainer flow without touching GitHub or Docker Desktop state:

```bash
make ship-release RELEASE_TAG=vX.Y.Z DRY_RUN=1
```

If you need to repair a tag after the publish workflow only partially completed:

```bash
make verify-rele

... (truncated)