[jelloeater-agent]

What

Adds Colima as a recognized docker engine on macOS, and makes the local docker provider behave correctly on it — plus clear guidance where colima's file-sharing can't host a local box. Reference design context: #207 (remote-docker) explicitly called out OrbStack/Colima as the break case, and remote-docker already supports colima Macs via its login-shell transport; this closes the local-engine gap.

Changes

Engine detection (packages/sandbox-docker/src/sync/host-export.ts)

• DockerEngine gains colima; the probe reads docker info --format '{{.OperatingSystem}}|{{.Name}}' and keys off colima — the VM hostname colima writes into the guest /etc/hosts at start (verified from colima's own start logs). engine.kind: colima is now a valid pin (config type + JSON schema + config docs).
• All downstream branches are orbstack vs everything-else, so colima already behaves like Docker Desktop everywhere else (URLs, portless, stats) — no other behavior changes.

host-gateway fix (docker.ts, create.ts)

• runBox always passed --add-host=host.docker.internal:host-gateway. On colima this overrides colima's native host.docker.internal → macOS host mapping (192.168.5.2 / host.lima.internal) with the VM's docker0 gateway (172.17.0.1) — the box then can't reach the host relay, breaking create and host actions. The flag is now gated on a new addHostGateway spec field, set to false for colima. Every other engine keeps the exact current behavior.

Fail-fast guard for colima local boxes (create.ts, in-box-git.ts)

• Colima's file sharing (virtiofs on vz, sshfs on qemu) presents bind-mounted macOS files with macOS ownership (uid 501), while the box's agent runs as vscode/uid 1000. agentbox's local provider bind-mounts the host .git/ and runs git worktree add as the box user — on colima that's a cryptic EACCES at create (unless the mac uid happens to be 1000). create now probes writability of each bind as the box user when the engine is colima, and on failure tears down the container + provisional record and throws a clear, actionable error: use remote-docker against this machine (agentbox remote-docker add <alias> localhost, needs SSH/Remote Login) — which does work on colima (cloud-style sync, no .git bind) — or Docker Desktop/OrbStack.

Diagnostics + docs

• Doctor/install hints name Colima; buildVncUrls accepts the wider engine union; README, local-docker.mdx (new Colima section), remote-docker.mdx, configuration.mdx carried the notes.

Tests

• 8 new/updated tests: colima detection (OS|Name probe + pin), host-gateway default/skip, unwritableGitBind probe behavior, schema/coerce colima cases.
• Green: @agentbox/sandbox-docker (363), @agentbox/config (238), @madarco/agentbox CLI (1662), full pnpm build, eslint, prettier.

Not verified (honest limitations)

• No macOS/colima available in the dev environment — colima semantics (hostname colima, host.docker.internal mapping, file-ownership presentation per mount type) are verified against colima/lima issue reports and colima's own config (dnsHosts: host.docker.internal: host.lima.internal, VM /etc/hosts wiring), not a live colima run. The remote-docker-on-colima path was already documented as supported by feat(provider): remote-docker — run boxes on a machine you own, over SSH #207.

[vercel]

@jelloeater-agent is attempting to deploy a commit to the madarco's projects Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

All contributors have signed the CLA. Thank you!
_{Posted by the CLA Assistant Lite bot.}

[jelloeater-agent]

I have read the CLA Document and I hereby sign the CLA

[jelloeater-agent]

recheck

[Jelloeater]

Signed this FYI

[madarco]

Thanks @Jelloeater @jelloeater-agent, great contrib! I don’t have colima installed, the PR say you didn’t test this on colima?

[jelloeater-agent]

Correct — I could not test this on a live colima install, and I wanted to be transparent about that in the PR. The dev environment here is Linux with no macOS, so there is no colima VM available.

What the colima-specific changes are based on instead:

• Detection — colima writes its VM hostname into the guest /etc/hosts at start (echo -e "127.0.0.1\tcolima" >> /etc/hosts, visible in colima start logs) and the docker context is named colima, so docker info --format "{{.OperatingSystem}}|{{.Name}}" returns colima in the Name field. That is how the probe keys off it.
• host-gateway skip — colima natively maps host.docker.internal to the macOS host (its config ships dnsHosts: host.docker.internal: host.lima.internal, 192.168.5.2), and passing --add-host=host.docker.internal:host-gateway overrides that mapping with the VM docker0 gateway (172.17.0.1), which would break the box-to-host relay. This is documented in colima issues feat(cli): gate --dangerously-with-credentials off under a control box (thin CLI Step 13) #287/docs(update): stop claiming self-update deletes the box image #277/#949.
• bind-ownership — colima virtiofs/sshfs presents bind-mounted macOS files with macOS ownership (uid 501), so the box agent (uid 1000) cannot write a bind-mounted .git; that failure mode is covered by colima/lima issues (feat(cli): agentbox attach [box] — agent-agnostic reattach, never auto-starts #83, feat(box): --persistent on every create surface #362, #1067, #1406, lima #4053).

The design is defensive on purpose: detection keys off the daemon Name, the host-gateway flag is omitted only for colima (every other engine gets byte-identical docker args), and the fail-fast probe verifies the .git bind is actually writable by the box user before proceeding — if colima on a real Mac ever behaves differently, create stops with a clear error pointing to remote-docker instead of failing cryptically mid-setup. The remote-docker-on-colima path itself was already supported and documented by #207.

If you do get a chance to run it on a colima Mac, apps/web/content/docs/local-docker.mdx (Colima section) lists exactly the two behaviors to check. Happy to iterate on anything you find.

[madarco]

thanks @Jelloeater if you use colima please test this before submitting, otherwise I'll add to my backlog and add colima support myself in the future

[jelloeater-agent]

Understood, and that is completely fair — untested engine-specific code should not land as "verified". To be clear on where that leaves this PR:

• I (jelloeater-agent) cannot run a live colima check from my dev environment — it is Linux, no macOS, so a colima VM with the macOS file-ownership semantics cannot be reproduced here. A Linux colima run would only exercise detection, not the macOS-specific bind-ownership behavior, so it would not validate what actually needs validating.
• The code is deliberately conservative for exactly this situation: detection keys off the daemon Name, the host-gateway flag is omitted only for colima (all other engines keep byte-identical docker args), and the .git-writability probe makes local colima creates fail fast with a pointer to remote-docker rather than crash cryptically mid-setup. engine.kind: colima is accepted but nothing in this PR changes behavior for any engine except colima itself.

So the decision is yours: merge as-is with the documented caveat (the fail-fast guard means a real colima user gets a clear error, not breakage, even if my assumptions were wrong), or put it in your backlog and use the detection/gating work here as a starting point. Either way, happy to iterate if you or @Jelloeater can run the two check points in the local-docker.mdx Colima section.