siding

module
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: Apache-2.0

README

siding

siding gives every git worktree its own Docker Compose stack, at its own *.localhost address, and tells you and your coding agents whether it actually runs and what it costs.

Pre-alpha (v0.5). Stacks per worktree, routing through one local proxy, the verdict of siding status, the overview siding ui, a memory budget with a queue, learned peaks and idle stacks that make room, snapshots and seeding, a build limit, gc, lint and a skill for coding agents work; expect rough edges and changes before v1. The plan is in openspec/changes/ (one change per phase), what siding does today in openspec/specs/.

Why siding

Coding agents work best in parallel: one per task, each in its own git worktree. Writing the code is then the easy part. What stays open is whether it runs: an agent reports "done" after the unit tests pass, but the app, with its database, its API and its frontend, never started. And if you start it, the worktrees get in each other's way:

  • They collide. Two copies of the same compose file fight over port 3000, a fixed container_name or a shared volume. The agent edits the compose file to get around it, or stops the other branch's stack.
  • "Started" is not "runs". docker compose up -d returns as soon as the containers exist. Whether the API crashed two seconds later, or listens on the wrong interface, nobody checks.
  • Nobody knows which is which. localhost:3000, localhost:3001, localhost:3002: which tab is which branch, and why does the login of one break the other's session?
  • The laptop fills up. Five stacks at a gigabyte or two each, and the machine swaps.

siding fixes this for apps that already run with Docker Compose, without changing them:

  • One stack per worktree. Your unchanged compose file runs as its own Compose project per branch, with its own containers, volumes and network. siding adds one override that removes published ports, so nothing collides.
  • One address per branch. One local proxy routes http://shop.feature-login.localhost to that branch's stack: a stable address, its own origin and its own cookies.
  • A verdict, not a guess. siding up --wait ends with Ready only when every healthcheck is healthy and every routed service answers through the proxy. Otherwise it names the service, the reason, a hint and its last log lines, as JSON an agent acts on. A skill teaches your agent to do exactly that before it says "done".
  • One view of everything. siding ps and siding ui show every stack on the machine, its address and what it costs. A memory budget queues or makes room instead of letting the machine swap, and siding gc removes what is merged.

What it looks like for an agent:

$ siding up --wait --json        # abridged
{ "kind": "Status", "verdict": "Failed",
  "failure": { "service": "api", "reason": "Exited", "hint": "exited with code 1; see its last log lines",
               "logs": ["connecting to postgres://app:***@db/app", "cannot connect to db"] } }

The agent fixes api, runs it again, and reports Ready with http://shop.feature-login.localhost for you to try.

siding is not an agent manager, not a sandbox for the agent, not Kubernetes and not production. It runs your stacks locally, and uninstalling it leaves plain Compose projects that keep running.

Get started

siding needs Docker with Compose 2.24 or later, and git. Your compose file stays as it is. The steps below follow the order you walk them in; each links to the details in the reference.

1. Install siding
curl -fsSL https://raw.githubusercontent.com/tweinmann/siding/main/install.sh | sh

The script downloads the latest release for your machine (macOS or Linux, arm64 or amd64), checks it against the release's SHA256SUMS, installs it as ~/.local/bin/siding without sudo, and tells you if that directory is not on your PATH. Run it again to update. SIDING_VERSION=v0.5.0 installs a given release, SIDING_INSTALL_DIR=/usr/local/bin another directory (with sudo sh if it needs root).

To read the script before it runs:

curl -fsSLO https://raw.githubusercontent.com/tweinmann/siding/main/install.sh
less install.sh && sh install.sh
Without the script

Download the binary for your platform and SHA256SUMS from the latest release, then:

shasum -a 256 -c SHA256SUMS --ignore-missing      # sha256sum on Linux
chmod +x siding-darwin-arm64                       # siding-<os>-<arch> of your platform
sudo mv siding-darwin-arm64 /usr/local/bin/siding
xattr -d com.apple.quarantine /usr/local/bin/siding  # macOS, after a browser download: the binary is not signed yet
siding version

With Go: go install github.com/tweinmann/siding/cmd/siding@latest.

The binaries are static and need nothing but Docker and git. To build siding yourself, see Developing siding.

2. Once per machine: the proxy
siding setup                 # Traefik as siding-proxy on 127.0.0.1:80

Every stack is then reached at http://<repo>.<branch>.localhost. Port taken, budget, build slots: see The proxy and Memory budget and idle stacks.

3. Once per repository: prepare it
cd shop
siding lint                  # what breaks parallel stacks, before the first up
siding up --wait             # the stack of this worktree, and its verdict

Fix what lint reports as errors in your compose file; siding never edits it. Take its LocalhostURL warnings seriously: behind the proxy, localhost inside a container is that container, so services call each other by name (http://api:3000), and the browser uses paths on the stack's address (/api) instead of a fixed http://localhost:3000. Label the service that is the app's root dev.siding.route: "/", and give services healthchecks, so that Ready means ready (Routing).

Teach your coding agent to use siding (For coding agents):

siding skill --install       # .claude/skills/siding/SKILL.md; --dir for another harness
git add .claude/skills/siding && git commit -m "Add the siding skill"

Commit it: a new worktree only has committed files. --install also prints a section for AGENTS.md and the permissions that let the agent run siding up, status, logs and ps without asking; add them where your harness reads them.

To start every new worktree with data instead of empty, fill a stack with test data and save it as the snapshot default (Snapshots and seeding):

siding snapshot save default # every new stack of this repository starts from it
4. Per task: a worktree and an agent
git worktree add ../shop-feature-x -b feature/x
cp .env ../shop-feature-x/   # git does not copy untracked files such as .env
cd ../shop-feature-x

If you forget, siding up refuses with EnvFileMissing and the cp command to run, instead of starting the stack with blank values (Env files).

Start your agent there. After a change, it runs siding up --wait --json, fixes what the verdict names, and reports the stack's address, e.g. http://shop.feature-x.localhost, for you to try. Each worktree's stack has its own containers, volumes, address and cookies.

5. Keep an eye on it
siding ps                    # every stack on this machine: state, address, memory
siding ui                    # the same as a page at http://siding.localhost
siding open                  # this worktree's stack in the browser

When a new stack does not fit into the memory budget, stacks nobody requested for a while make room (Memory budget and idle stacks).

6. After the merge
siding gc                    # remove the stacks of merged branches; --dry-run first
git worktree remove ../shop-feature-x

See gc for what counts as merged and what stays.

Reference

The proxy
siding setup                 # Traefik as siding-proxy on 127.0.0.1:80
siding setup --port 8080     # if port 80 is taken, or inside siding's devcontainer

Every stack is reached through this one proxy at http://<repo>.<branch>.localhost. Browsers resolve *.localhost to your machine by themselves, and so does curl on Linux. The curl of macOS does not: there, use curl -H "Host: shop.feature-login.localhost" http://127.0.0.1/, or add the host to /etc/hosts, as for other tools. Running siding setup again changes nothing unless the port differs.

Starting a stack
siding up                    # e.g. shop on feature/login: http://shop.feature-login.localhost/
siding up -- --build web     # arguments after -- go to docker compose up
siding up --wait             # and wait for the verdict, like siding status --wait

up runs your compose file as the Compose project <repo>-<branch> with one more file, .siding/override.yml. That file resets every published port, so branches never fight over ports, and puts siding's labels and routes on the services. .siding/ ignores itself in git.

Env files

git worktree add copies only what git tracks, so a new worktree has no .env and none of the untracked files the compose file names in env_file. Compose would start the stack anyway, with blank values. So in a linked worktree, siding up refuses with EnvFileMissing when it lacks .env or a required env_file that the main worktree has and git does not track; the hint gives the cp command, and siding lint warns MissingEnvFile for the same files. siding never copies them itself: they hold secrets, and which values a branch needs is your call. If a worktree needs none, an empty file will do (touch .env).

Routing
  • A service labelled dev.siding.route: "/" is the stack's root, dev.siding.route: "/api" answers under that path (the path is passed on unchanged), dev.siding.route: "false" hides a service.
  • Every service with one container port (from ports or expose) also answers at http://<service>.<repo>.<branch>.localhost. With several ports, dev.siding.port: "3000" names the HTTP one.
  • Published ports are gone, also a database's. Reach it with docker compose -p <repo>-<branch> exec db psql ….
Verdict and exit codes
siding status                # Ready, Starting, Failed, TimedOut or Stopped, per service
siding status --wait         # until Ready, Failed or Stopped, at most --timeout (3m)
siding ps                    # every stack on this machine: state, address, memory

Ready means every service with a healthcheck is healthy and every service with a route answers through the proxy. A failure names the service, the reason, a hint and its last log lines. Stopped means no container runs and none failed; siding up starts it again. Exit codes: 0 Ready, 1 Failed, 2 TimedOut, Stopped or still starting. Every command prints one JSON document with --json, for scripts and agents.

Lint rules
siding lint                  # exits 1 when it finds an error; --json for a LintReport

lint checks the compose file siding would use and never changes it.

Rule Severity Finds
ContainerName error a fixed container_name: a second stack cannot start
FixedNetworkName error an own network with a fixed name, shared by every stack
FixedVolumeName error (info with dev.siding.shared) an own volume with a fixed name, so every stack shares its data
InvalidRoute, AmbiguousPort error route labels siding up would refuse
HostPath warning a bind mount of a path outside the worktree, shared by every stack
NetworkMode warning network_mode: siding cannot route the service
NoHealthcheck warning no healthcheck and no route: Ready only means it started
LocalhostURL warning an environment value with localhost:<port> or 127.0.0.1:<port>: behind the proxy it reaches the service's own container; the finding names the variable, never its value
MissingEnvFile warning in a new worktree, an untracked env file of the main worktree that is missing (Env files)
PublishedPort info published ports, which siding resets
NoRoot info HTTP services, but none at /
Snapshots and seeding
siding snapshot save base    # copy this stack's named volumes into the snapshot "base"
siding snapshot ls           # the snapshots of this repository
siding snapshot rm base      # --dry-run lists it first

A snapshot is a copy of every named volume of a stack, kept as Docker volumes on this machine per repository. While it copies, save stops the services that use those volumes, so a database is copied in a consistent state, and starts them again. Snapshots outlive stacks: down --volumes and gc never remove them; siding teardown --snapshots does.

siding up --seed base        # on the stack's first up: its volumes start as copies of "base"
siding up --seed none        # start empty, even with a snapshot default

The snapshot named default needs no flag: a stack's first up without --seed seeds from it and says so on stderr, so an agent's first up in a new worktree gets the data without knowing about snapshots. Save a newer state with siding snapshot save default --force; without a snapshot default, a first up starts empty. none cannot be a snapshot's name.

A new worktree's stack can start with data instead of empty. On its first up (the project has no containers and no volumes yet), --seed <snapshot> creates its volumes as copies of the snapshot before Compose starts it; a later up never seeds again. Per service, the label dev.siding.seed chooses:

services:
  db:
    image: postgres:17
    labels:
      dev.siding.seed: script                       # run a command once on the first up
      dev.siding.seed.command: "psql -U app -f /seed/dev.sql"
  cache:
    image: redis:7
    labels:
      dev.siding.seed: none                         # never seeded, starts empty
  # without the label, or with dev.siding.seed: volume, the volumes come from --seed or default

The seed command runs with docker compose exec as soon as the service is ready. If it fails, the verdict is Failed with the reason SeedFailed and the command's output.

Memory budget and idle stacks
siding setup --budget 12g        # memory for all stacks together; "default" is 75 % of Docker's
siding up --force                # start even if the stack does not fit

Before up starts a stack, siding adds the memory the other stacks use now to what this stack will need: per service the highest use siding has seen for it in this repository, plus a quarter and at most its limit; else its mem_limit (or deploy.resources.limits.memory); else 256 MiB. siding learns those peaks whenever it reads memory (ps, ui, up, a Ready status) and keeps them in ~/.siding/peaks.json, a cache you can delete at any time. If that exceeds the budget, up refuses with exit code 3 and says how much is missing. Setting mem_limit on big services makes the estimate right.

With siding up --wait, a stack that does not fit waits in line instead, until another stack frees memory or --timeout (3 minutes) is up; then it exits 3. Stacks start in the order they began to wait. siding ps and siding ui show the line. A waiting up that you stop with Ctrl-C, or that is killed, leaves the line. siding ps shows the total against the budget.

Before a stack waits or is refused, idle stacks make room for it. up stops other stacks that had no request through the proxy for 5 minutes, the one idle longest first, as many as the new stack needs, and only when that makes it fit; it says on stderr which ones it stopped. Stopping removes nothing: containers stop, volumes and networks stay. A stopped stack reports the verdict Stopped (exit code 2), and siding up in its worktree starts it again, in Compose's order; a request to its address does not start it (the proxy answers 404).

siding setup --idle 15m          # another idle threshold; "default" is 5m
siding setup --idle off          # never stop a stack to make room

A request is anything that passes the proxy, siding status checks included. Work that does not, such as tests through docker compose exec or a queue worker, does not count, so such a stack can be stopped while it is busy; raise the threshold or turn it off if that matters. The proxy records only the router and the time of each request, in its container log, which Docker keeps at 30 MiB; no URL, header or cookie is kept. After upgrading siding, run siding setup once, so the proxy records requests: until then, no stack is stopped to make room.

Overview
siding ui                    # http://siding.localhost while it runs; Ctrl-C stops it

The page lists every stack with its address and memory, the total against the budget, and what siding gc would remove. It refreshes itself and is read-only; /api/stacks and /api/gc return the documents of siding ps --json and siding gc --dry-run --json. It listens on this machine only, and nothing of it keeps running after Ctrl-C. After upgrading siding, run siding setup once, so the proxy knows the route.

Builds
siding setup --builds 2      # at most two stacks build images at once; "default" is half the CPUs

When a stack has services with build:, up takes one of these build slots while Compose builds and starts it, and waits for a free one first (within --timeout). Stacks of images only never wait. The slots are lock files under ~/.siding/builds; a stopped or killed up frees its slot at once.

Logs, address, and taking it down
siding logs -f api           # docker compose logs of the stack
siding open                  # the stack's address in the browser; siding open api for a service
siding down                  # remove containers and networks; volumes and data stay
siding down --volumes        # also the data; refused while the branch is unmerged or the
                             # worktree dirty, unless --force; --dry-run lists it first
gc
siding gc --dry-run          # what can go, and what stays and why
siding gc                    # asks, then removes; --yes for scripts

gc removes the stacks of merged branches whose worktree is clean, with their volumes, and the containers of stacks whose worktree you deleted (their volumes only if the branch is merged). A branch counts as merged when the default branch has moved past it, or when its upstream branch is gone, as after a squash-merged pull request and git fetch --prune. gc never deletes worktrees or branches, and never the stack of the default branch or of a branch without commits of its own.

In a devcontainer

siding works inside a devcontainer that runs its own Docker daemon (Docker-in-Docker), as this repository's does. Then:

  • siding ps, siding ui and the budget see the stacks of that container, not the whole machine; for one view of everything, run siding on the machine itself;
  • forward the proxy's port (forwardPorts with requireLocalPort) and run siding setup --port with it; each devcontainer needs its own port;
  • the container has its own image cache.

Mounting the host's Docker socket into the devcontainer (Docker-outside-of-Docker) is not supported: it gives everything in the container root on the host, the opposite of why agents run in devcontainers, and bind mounts break unless the paths match inside and out.

For coding agents

siding skill prints a skill, in the Agent Skills format, that tells an agent to run siding up --wait --json after a change, to act on the verdict, and to report the stack's address. It names no harness, so the same file works wherever skills are read.

siding skill --install                          # .claude/skills/siding/SKILL.md at the worktree's top
siding skill --install --dir ~/.claude/skills   # for every repository, nothing to commit
siding skill --install --dir <skills dir>       # the skills directory of another harness
siding skill > SKILL.md                         # print it, write nothing

--install replaces an older copy, so run it again after upgrading siding. It then prints two snippets and writes neither: a short section for AGENTS.md, which many harnesses read, and the permissions for siding's reading commands, as an entry for Claude Code's .claude/settings.json and as a plain list for other harnesses. Only those four commands: stopping and removing stacks and their data stays your decision.

Removing siding
siding teardown              # remove the proxy; stacks keep running, --dry-run lists it
siding teardown --snapshots  # and every snapshot of this machine

Without siding, your stacks are plain Compose projects that keep running; docker compose -p <repo>-<branch> down removes one. ~/.siding is a cache you can delete.

Developing siding

Everything runs inside the devcontainer, which has its own Docker daemon; nothing is installed on your machine and siding's tests never touch your Docker containers.

  1. Open the repository in VS Code and choose Dev Containers: Reopen in Container (needs Docker Desktop, OrbStack or Docker Engine).

  2. In the container's terminal:

    Command Purpose
    just test formatting, vet, unit tests with -race, golangci-lint, OpenSpec validation, the test of install.sh (as in CI)
    just golden rewrite golden files after an intended output change
    just build build bin/siding
    just dist <version> the release binaries and SHA256SUMS in dist/, as CI builds them for a v* tag
    just build-darwin build bin/siding-darwin-arm64 and -amd64, to run siding on your Mac
    just smoke-docker Compose, ports: !reset [] and Traefik routing against the container's own daemon
    just smoke-stacks siding's own commands end to end against the container's own daemon

    To try siding by hand: just build, then bin/siding setup --port 8080 (the port the devcontainer forwards), and bin/siding up --wait in a project; its address, http://<repo>.<branch>.localhost:8080, opens in the browser on your machine. Port 8080 must be free on your machine: VS Code reports it when it is not, rather than forwarding to another port. Then free it, or change the port in .devcontainer/devcontainer.json and pass the same one to siding setup --port.

To remove everything siding development left on your Docker host, run hack/nuke.sh in a terminal on the host (--dry-run lists it first).

Working agreements, guardrails and safety rules are in CLAUDE.md.

License

Apache-2.0, see LICENSE.

Directories

Path Synopsis
cmd
siding command
Command siding gives every git worktree its own Docker Compose stack, and one view of all of them.
Command siding gives every git worktree its own Docker Compose stack, and one view of all of them.
internal
budget
Package budget decides whether another stack fits into the memory the machine has for siding.
Package budget decides whether another stack fits into the memory the machine has for siding.
buildslot
Package buildslot limits how many siding processes build images at the same time: N lock files under ~/.siding/builds, held with flock.
Package buildslot limits how many siding processes build images at the same time: N lock files under ~/.siding/builds, held with flock.
cli
Package cli holds siding's commands: flags, arguments and output.
Package cli holds siding's commands: flags, arguments and output.
compose
Package compose runs docker compose and reads the normalised configuration it prints.
Package compose runs docker compose and reads the normalised configuration it prints.
docker
Package docker reads the state of stacks from the Docker Engine API.
Package docker reads the state of stacks from the Docker Engine API.
fail
Package fail holds the error type every siding command fails with: a stable code that agents may branch on, a message, and an optional hint on what to do next.
Package fail holds the error type every siding command fails with: a stable code that agents may branch on, a message, and an optional hint on what to do next.
gc
Package gc decides which stacks can go: a pure function from what Docker and git know about each stack to the actions siding gc takes.
Package gc decides which stacks can go: a pure function from what Docker and git know about each stack to the actions siding gc takes.
git
Package git answers what siding needs to know about a worktree by running the git CLI: where it is, which branch it is on, and whether removing its stack's data could lose work.
Package git answers what siding needs to know about a worktree by running the git CLI: where it is, which branch it is on, and whether removing its stack's data could lose work.
idle
Package idle tells when a stack was last requested through the proxy, from the proxy's access log: one JSON line per request with only the router and the time (phase 4 design D3, D4).
Package idle tells when a stack was last requested through the proxy, from the proxy's access log: one JSON line per request with only the router and the time (phase 4 design D3, D4).
lint
Package lint finds what in a compose file breaks parallel stacks or weakens siding's verdict.
Package lint finds what in a compose file breaks parallel stacks or weakens siding's verdict.
overview
Package overview holds what siding ui needs besides the page: the route file through which siding-proxy reaches it, and the addresses it listens on.
Package overview holds what siding ui needs besides the page: the route file through which siding-proxy reaches it, and the addresses it listens on.
probe
Package probe asks the proxy whether a routed service answers, without DNS: the request goes to 127.0.0.1 on the proxy's port with the stack's host in the Host header.
Package probe asks the proxy whether a routed service answers, without DNS: the request goes to 127.0.0.1 on the proxy's port with the stack's host in the Host header.
proxy
Package proxy describes siding-proxy: one Traefik with the Docker provider, run as its own Compose project, through which every stack is reached by host and path.
Package proxy describes siding-proxy: one Traefik with the Docker provider, run as its own Compose project, through which every stack is reached by host and path.
queue
Package queue is the line of up --wait processes waiting for memory.
Package queue is the line of up --wait processes waiting for memory.
seed
Package seed decides how a stack's first up fills it with data: which volumes come from a snapshot, and which services run a seed command.
Package seed decides how a stack's first up fills it with data: which volumes come from a snapshot, and which services run a seed command.
snapshot
Package snapshot names, labels and groups snapshots: copies of a stack's named volumes, kept as Docker volumes.
Package snapshot names, labels and groups snapshots: copies of a stack's named volumes, kept as Docker volumes.
stack
Package stack derives everything about a stack that follows from its worktree and its compose file without asking Docker: names, labels, routes and the override siding writes.
Package stack derives everything about a stack that follows from its worktree and its compose file without asking Docker: names, labels, routes and the override siding writes.
testutil
Package testutil holds helpers shared by tests.
Package testutil holds helpers shared by tests.
verdict
Package verdict decides whether a stack runs: Ready only when every service is up, healthy where it has a healthcheck, and answering through the proxy where it has a route path.
Package verdict decides whether a stack runs: Ready only when every service is up, healthy where it has a healthcheck, and answering through the proxy where it has a route path.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL