WorktreeOS

wos is a CLI for deploying the current Git worktree via Docker Compose. The Compose file is generated from a small deploy config (.wos/deploy.yaml), a local daemon owns the Docker operations, and a web UI gives every worktree its own detail page for logs, status, and controls.

What WorktreeOS does

Generates Compose from the deploy config

Describe your app, dependencies, and ports in .wos/deploy.yaml. WorktreeOS generates the Docker Compose file for the current worktree — or plugs into an existing docker-compose.yaml in compose mode.

A deployment per worktree

Each worktree gets a stable project name, stable host ports, and an isolated session. Run several branches side by side without port clashes.

Daemon-backed

A local daemon owns Docker operations, session files, and service-log followers, and coordinates up/down per session over a Unix socket.

Web UI for every worktree

Init logs, service logs, operation progress, status, and stop/restart controls live in the web UI — opened with wos web.

Find your way around

Get Started Prerequisites, install, a minimal deploy config, and your first wos up / wos web / wos down.

Concepts Worktrees, the daemon and web UI, and the deployment lifecycle.

Guides Task-oriented walkthroughs: running a worktree, the web UI, selective and detached startup, WSL access.

Configuration Generated mode, compose mode, services, ports, healthchecks, dependencies, clone volumes, cache, targets, and arguments.

Reference CLI commands, the full deploy-config field reference, storage and sessions, and daemon behavior.

Troubleshooting Config errors, daemon errors, port conflicts, healthcheck failures, and init/volume failures.