Binky MCP server

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 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:

Shortened. The full README is on GitHub.