Add Cmdop to a container

The usual reason to reach for Docker here is not “run Cmdop in a container” — it is “the container I already ship should be reachable.” That takes two lines, and it changes nothing about how your image behaves.

The two lines

FROM your-image                                    # unchanged
COPY --from=markolofsen/cmdop:latest /cmdop /usr/local/bin/cmdop
ENTRYPOINT ["cmdop", "sidecar", "--"]
CMD ["your-app", "--your", "flags"]                # unchanged

Then hand the container the fleet’s join key:

docker run -d \
  -e CMDOP_SERVER_URL=https://your-team.cmdop.dev \
  -e CMDOP_JOIN_KEY=cmdop_enroll_xxxxxxxx \
  -e CMDOP_MACHINE_NAME=api-01 \
  -e HOME=/state -v cmdop-state:/state \
  your-image

The machine appears in your fleet on startup, with terminal, file access, AI chat and remote execution — from a browser, the CLI, or your phone.

A working version of exactly this, on an ordinary Node app, is examples/simple in the public repository.

What sidecar does

sidecar starts the agent in the background, then execs your command. That word is the whole design: your process replaces the wrapper and becomes PID 1.

• docker stop delivers SIGTERM to your application, so your graceful shutdown runs unchanged.
• The container’s exit code is your exit code.
• restart: policies behave exactly as before.
• Everything after -- passes through untouched.

Three consequences worth knowing before you ship it:

Where the relay is

CMDOP_SERVER_URL points at a relay — the thing machines join and you connect through. A container added this way is a member: it dials out, and it never listens. Something else has to be the relay:

In every case the relay is where cmdop server join-key prints the key that goes in CMDOP_JOIN_KEY — the two settings always come from the same place.

Hosting a relay is a different job from joining one: a relay listens, holds server.db, owns the console password, and on the managed tier registers a public address. See self-hosted relay.

Two credentials, and they are not the same thing

This is the part that trips people up. Joining the fleet and paying for inference are separate.

With the join key alone the machine connects and the terminal and file access work fine; AI chat just has nothing to think with.

Settings that are not optional

One rule about that volume: it is for state, never for executables. A binary installed into a volume is seeded once, at first container creation, and then outlives every later image build — so a rebuild silently keeps running the old one. Copy cmdop to an image path, as the Dockerfile above does.

Other settings

Any base image

The binary links no libc, so Alpine, Debian, distroless and even scratch all work. Nothing else needs to be present in the image.

The image, and why it has one tag

markolofsen/cmdop is a source of the binary, not something you run: it carries no shell and adds only the file it copies. It is built for linux/amd64 and linux/arm64 from the published release binary, verified against its SHA256SUMS.

:latest is the only tag, and that is deliberate — the agent keeps itself current at runtime, checking daily and applying updates in place, so a container built months ago runs today’s version without a rebuild. Your application image stays fixed; the management agent does not. It is the same bargain Tailscale, the Datadog agent and cloudflared make.

If your deployment must be immutable, that default is switchable:

Fetching the binary at build time instead

If you would rather not pull from a registry, the installer works too:

RUN curl -fsSL https://install.cmdop.com | sh -s -- --prefix=/usr/local/bin

On Alpine that needs apk add --no-cache curl ca-certificates first; Debian-family images usually have both. The COPY --from form is preferred because it fetches nothing at build time and its layer is cacheable.

Related

• Docker overview
• Configuration and persistence
• Claude Code and Codex
• Troubleshooting
• Fleets
• Self-hosted relay