Coding Agent Runner

Windshift can run coding agents server-side, spawning one ephemeral Docker container per agent run. The runner image bundles the ws CLI, pi, and Windshift guard/configuration files. A run starts when a workspace has an agent binding and a work item is assigned to the bound agent user; on success, Windshift opens a draft pull request with the result.

Note: This is the operator-facing guide for running coding agents inside Windshift. For wiring an editor agent like Claude Code or Cursor to the ws CLI, see Coding Agents.

How the Runner Is Initialized

The coding-agent harness is initialized when the Windshift server starts and CODING_AGENT_RUNNER_IMAGE is set. On startup, Windshift wires:

Component	Responsibility
`WorktreeManager`	Prepares a per-run git worktree on the host
`RunTokenService`	Mints a short-lived `ws` API token for the acting agent identity
`DockerPiRunner`	Starts the runner container with `docker run`
`AgentPRService`	Opens a draft pull request after a successful run

Docker Access Requirement

Windshift does not call the Docker API directly. It shells out to the Docker CLI and runs a command shaped like:

docker run -i --rm ... "$CODING_AGENT_RUNNER_IMAGE"

The Windshift server process must therefore have access to a Docker daemon.

Windshift Running on a Host

If Windshift runs directly on a VM or bare-metal host, install Docker on that host and ensure the Windshift process user can run docker.

Windshift Running in Docker

If Windshift itself runs in a container, mount the host Docker socket into the Windshift container so its Docker CLI can talk to the host daemon:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Worktree Path Requirement

CODING_AGENT_WORKTREE_ROOT must be an absolute path where Windshift creates per-run git worktrees.

If Windshift runs in Docker while using the host Docker socket, the worktree path must also be visible to the host Docker daemon. Mount the same absolute host path into the Windshift container:

environment:
  - CODING_AGENT_WORKTREE_ROOT=/var/lib/windshift/coding-agent-worktrees
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - /var/lib/windshift/coding-agent-worktrees:/var/lib/windshift/coding-agent-worktrees

This same-path mount matters because Windshift prepares the worktree, then the host Docker daemon bind-mounts that path into the runner container as /workspace.

Required Configuration

CODING_AGENT_RUNNER_IMAGE=ghcr.io/windshiftapp/coding-agent-runner:latest
CODING_AGENT_WORKTREE_ROOT=/var/lib/windshift/coding-agent-worktrees

If runner containers cannot reach the browser-facing BASE_URL, also set:

CODING_AGENT_WS_API_URL=https://windshift.example.com

Important: Use CODING_AGENT_WS_API_URL especially when BASE_URL is localhost from the user's browser perspective — inside the runner container, localhost refers to the runner container itself, not Windshift.

Optional Runner Resource Configuration

CODING_AGENT_DOCKER_BINARY=docker
CODING_AGENT_NETWORK=coding-agent-egress
CODING_AGENT_PIDS_LIMIT=512
CODING_AGENT_MEMORY=4g
CODING_AGENT_CPUS=2

Variable	Default	Description
`CODING_AGENT_DOCKER_BINARY`	`docker`	Docker CLI binary to invoke
`CODING_AGENT_NETWORK`	`coding-agent-egress`	Docker network for runner containers
`CODING_AGENT_PIDS_LIMIT`	`512`	Max process IDs per runner container
`CODING_AGENT_MEMORY`	`4g`	Memory limit per runner container
`CODING_AGENT_CPUS`	`2`	CPU limit per runner container

By default, the runner uses a Docker network named coding-agent-egress. Operators should create this network and apply their own egress restrictions. To intentionally use Docker's default bridge network instead:

CODING_AGENT_NETWORK=bridge

Minimal Docker Compose Example

services:
  windshift:
    image: ghcr.io/windshiftapp/windshift:latest
    environment:
      - BASE_URL=https://windshift.example.com
      - CODING_AGENT_RUNNER_IMAGE=ghcr.io/windshiftapp/coding-agent-runner:latest
      - CODING_AGENT_WORKTREE_ROOT=/var/lib/windshift/coding-agent-worktrees
      - CODING_AGENT_WS_API_URL=https://windshift.example.com
    volumes:
      - windshift-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/windshift/coding-agent-worktrees:/var/lib/windshift/coding-agent-worktrees

volumes:
  windshift-data:

See Environment Variables for the full configuration reference.