Host Zeroshot with Docker

Check the security boundary first

A target is the long-running service that accepts Zeroshot runs. Each run gets its own working directory and separate home directories for the agent CLIs. This keeps run files apart, but the container is still meant for one group of mutually trusted users and workloads.

1. Pull the image

Run this on the VM. The image is public, so Docker doesn't need a registry login. latest can change; pin a release tag or digest when you need the VM to use a fixed build.

docker pull \
  ghcr.io/the-open-engine/zeroshot-target:latest

2. Start on loopback

The 127.0.0.1 binding keeps port 8080 on the VM itself instead of exposing it to the network. The named volume keeps target state outside the container, and the restart policy brings the target back after Docker or the VM restarts.

docker run -d \
  --name zeroshot-target \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v zeroshot-data:/var/lib/zeroshot/native-v2 \
  ghcr.io/the-open-engine/zeroshot-target:latest

3. Open the tunnel and register the target

On your workstation, open this SSH tunnel and leave the terminal running while you use the target. It maps workstation port 8080 to port 8080 on the VM's loopback address. Skip the tunnel when the CLI runs on the VM.

ssh -N \
  -L 8080:127.0.0.1:8080 \
  user@your-vm

The next commands save the name vm for that local endpoint, then record the repository and default merge branch. --direct means the CLI will connect without target login.

zeroshot target add vm \
  --direct \
  --url http://127.0.0.1:8080

zeroshot target setup vm \
  --repository your-org/your-repo \
  --branch main

4. Submit a run

Reuse input.json and runtime.json from the Quickstart. The CLI sends only the environment values declared by the RuntimePlan. In this command, OPENAI_API_KEY supplies the declared model connection, while GH_TOKEN is a separate credential for repository checkout and delivery.

export OPENAI_API_KEY="..."
export GH_TOKEN="$(gh auth token)"

zeroshot run \
  --target vm \
  --title "Health-check endpoint" \
  --template software-change \
  --ship \
  --input ./input.json \
  --runtime-config ./runtime.json

Check runs and update the container

Use the registered target name vm with the normal run commands. Direct targets never report the Cloud-only queued state.

zeroshot list --target vm
zeroshot status <run-id> --target vm
zeroshot watch <run-id> --target vm
zeroshot logs <run-id> --target vm

For an update, pull the image tag or digest you want and recreate the container with the same zeroshot-data volume. If you omit that volume, the replacement target starts without the saved target state.

Keep the endpoint private

Keep port 8080 on loopback and reach it through SSH, a VPN, or another private network control. Don't publish the endpoint to the internet. TLS can encrypt the connection, but it doesn't add caller authentication to a direct target.

If you put a private HTTPS reverse proxy in front of the target, forward WebSocket upgrades on /native-v2/oecp. Set the server's --public-origin to that HTTPS origin; otherwise the CLI can't open the OECP connection through the proxy.

Open the target image in GitHub Container Registry · Read the target image setup guide · Get the Quickstart run files