Binky

One isolated local world per git worktree — ports, env, database, URLs.

So a swarm of coding agents runs in parallel on one machine without anything colliding.

Docs · Quickstart · Adapters · Commands · For agents · How it works · Troubleshooting

docker-compose was built for one process at a time. Binky is built for fifteen at once.

Status: alpha. The core works end to end — worktree isolation, ports, adapters, supervision, reconciler, admission, proxy, HTTPS. The config format is stable; the CLI may still move.

The problem

You point three agents at the same repo. The second one runs pnpm dev and gets EADDRINUSE. The third runs your migrations and drops the table the first was reading. You start hand-editing .env files, and now you're the scheduler.

Binky is the scheduler. One binky up <branch> per agent, and each gets its own ports, its own database, its own URLs — from the same committed config.

Install

Python 3.11+ and git, on Linux or Windows — the two platforms Binky is tested on for real. macOS isn't a supported target yet; a well-tested port would be a welcome contribution.

uv tool install binky          # or: pipx install binky
binky --version

Or from a clone, to run the unreleased main or to hack on it:

git clone https://github.com/andreisilva1/binky && cd binky
uv tool install .               # or: pipx install .

Adapters that need a driver ship as extras — installing Binky for Redis shouldn't pull boto3:

uv tool install "binky[postgres]"        # or [redis], [mysql], [mongodb], [s3], [kafka]
uv tool install "binky[all-adapters]"    # the whole matrix

Quickstart

Already have a docker-compose.yml? Start from it:

binky init                 # writes a binky.toml you can read and edit
binky check                # validate it

Or write it by hand — this is the whole config:

[project]
name = "acme"

[services.web]
cmd = "pnpm dev --port ${self.port}"
url = "web"                              # → web.<worktree>.acme.localhost
depends_on = ["api"]
env = { API_URL = "${api.url}" }

[services.api]
cmd = "go run ./cmd/server"
url = "api"                              # asking for a URL is what asks for a port
depends_on = ["db"]
env = { DATABASE_URL = "${db.url}" }

[services.db]
adapter = "postgres"                     # a private database per worktree
admin_url = "${env.POSTGRES_ADMIN_URL}"
migrate = "make migrate"
seed = "make seed"
clone_from = "golden"                    # migrate+seed once, then copy per worktree

Then bring worktrees up in parallel:

$ binky up login-fix
  api  pid 16560  :4846
  web  pid 29732  :4504
✓ up: login-fix (2 service(s))

$ binky up checkout-v2
  api  pid 21768  :4137
  web  pid 46336  :4605
✓ up: checkout-v2 (2 service(s))

$ binky status
acme
  checkout-v2  [running]
      api  :4137
      web  :4605
  login-fix  [running]
      api  :4846
      web  :4504

Two branches, four processes, four ports nobody chose by hand. Hand a worktree's coordinates to whoever needs them — a shell, an agent, a test run:

$ binky env login-fix --dotenv
WEB_URL=http://web.login-fix.acme.localhost
API_URL=http://api.login-fix.acme.localhost

And the rest of the lifecycle:

binky down login-fix       # pause (keeps files + ports); `up` again is instant
binky remove login-fix     # destroy it (refuses if there are uncommitted changes)

Nothing is hardcoded and nothing is discovered at runtime: every process boots already knowing the whole port map, its own and its dependencies'.

One rule to internalise. A service gets a port when it declares url or ports — asking is explicit. A service with neither gets none, which is correct for a worker or a one-shot job, and a trap if you then write ${self.port} in its cmd. Unknown tokens are left alone rather than blanked, so the literal ${self.port} reaches the shell and the process dies on its own argument parsing. binky check warns when a service does this.

What it costs to run N worlds

The claim is that N isolated worlds shouldn't cost N times one world. Measured, not asserted — benchmarks/worlds.py is in this repo and reproduces the table below (postgres:16, 200,000 rows per world, Docker Desktop on Windows 11):

The 8th world costs +150 MiB and +4.8s as its own container, or +17 MiB and +1.7s under Binky.

Read the first row too. At one world Binky is behind — it pays for a server plus a golden template nobody is using yet, and only earns that back on the second. And disk is not a win: CREATE DATABASE ... TEMPLATE is a file copy, not copy-on-write, so every world is still a full copy of the rows. What Binky removes is the server per world, not the bytes per world. It also doesn't make your own app processes cheaper — one dev server per worktree costs the same either way.

python benchmarks/worlds.py --sweep 1,2,4,8 --rows 200000

When you don't need Binky

Worth saying plainly, because the first row of that table already says it:

• One branch at a time. If you never have two worlds up at once, Binky is a daemon and a config file you didn't need. Use it when the second agent shows up.
• Everything already runs in containers, and that's fine. Binky's win is removing the server per world. If your compose stack is small enough that N copies fit comfortably, there's nothing to reclaim.
• You need real isolation, not local isolation. Binky runs your commands as you, on your machine. It is not a sandbox — see Security.

Adapters

An adapter carves an isolated slice of one shared server — a database, a key prefix, a bucket — instead of running one server per worktree. 16 names, 10 implementations, every one exercised against a real server in CI.

Protocol-compatible names share one implementation rather than a copy of it — valkey is the Redis adapter, percona is the MySQL one, opensearch is the Elasticsearch one.

clone_from: pay for migrate+seed once

With clone_from, the first binky up builds a golden template — provision, migrate, seed — and every worktree after that is a copy of it. The template is keyed by a hash of your migrate and seed commands, so changing either rebuilds it automatically.

Supported where the server can copy a slice server-side (postgres, mysql, mariadb, percona, mongodb). Where it isn't, or where a clone fails on something environmental — a client binary too old to authenticate, a missing grant — Binky falls back to provision+migrate+seed for that worktree and logs clone_fallback. Correctness never depends on cloning; only speed does.

One sharp edge worth knowing: the hash covers the migrate and seed commands, not the files they call. Editing a script those commands run does not rebuild the template — delete its marker under ~/.binky/golden/ to force one.

Writing your own

Two tiers, one contract. Both implement the same four verbs:

In-process adapters are Python classes in this repo, discovered by name. External adapters are executables in any language, discovered as binky-adapter-<name> on PATH and driven over a one-shot subprocess + JSON protocol:

$ binky-adapter-filestore provision   <<< '{"slice": "acme_login-fix", "config": {}}'
{"ok": true}
$ binky-adapter-filestore resolve     <<< '{"slice": "acme_login-fix", "config": {}}'
{"ok": true, "address": "file:///tmp/binky-filestore/acme_login-fix"}

Python authors get the protocol for free — binky.adapter_sdk.run() bridges a normal adapter class to it. See examples/adapters/filestore.py for a complete, dependency-free one in 30 lines.

Commands