← Projects

forkspace(active)

Isolated local dev/test environments for multi-repo compose stacks.

forkspace runs many copies of one Docker Compose stack on one machine. Git worktrees already give each branch or agent its own files, but every copy still reaches for the same port 3306 and the same MySQL data directory, so two test runs against “the” local database corrupt each other. forkspace gives each copy its own lane, and for each service in that lane it lets you choose how much to copy.

forkspace up dev
forkspace up test --fork agent-a
forkspace up test --fork agent-b
forkspace down test --fork agent-a
Status
v0.2, open source
Distribution
CLI + browser playground
Evidence
stress test: 4 concurrent forks created in 0.13s, 3 schema histories in one MySQL

Each service picks its isolation

An environment in forkspace.yml lists the compose services it claims, and each service declares an isolation level. A fork of that environment gets something different from each level:

containernamespacesharedbaselineagent-a34063416mainagent_a8100
Figure 1 What the fork agent-a gets for one service, by isolation level. container: its own compose service, with its own volume and host port (MySQL on 3416 beside the baseline's 3406). namespace: a token minted from the fork name, here a database agent_a inside the baseline MySQL. shared: the baseline service as it is, here DynamoDB on 8100.

The usual test setup puts MySQL on namespace and everything else on shared: one MySQL container holds a database per fork, while DynamoDB, the queue and object storage stay single. A fork that needs its own MySQL after all asks for it on the command line with --isolate mysql.

services:
  mysql:
    isolation: namespace
    exports:
      DATABASE_URL: "mysql://root:root@{host}:{port}/{ns}"
  dynamodb:
    isolation: shared
    exports:
      DYNAMO_ENDPOINT: "http://{host}:{port}"

forkspace names things; it does not drive databases. It mints the namespace token from the fork name (lowercase, dashes become underscores, at most 32 characters), so agent-a becomes agent_a, fills it into the export templates, and writes the result to an env file the tests source. Creating and dropping the database is the job of your repo’s own hook scripts: a fork runs forkCreate then seed on the way up and forkDestroy on the way down.

Ports come from slots

Each fork takes a slot, the lowest one whose ports are free, and every port it owns is the service’s base port plus the slot times slotSize:

slot 0slot 1slot 2mysql340634163426app410041104120baselineagent-aagent-b
Figure 2 Host ports in the test environment with slotSize 10. Slot 0 is the baseline; each fork takes the lowest free slot and every port it owns moves by the same step. A service on namespace or shared isolation keeps the baseline's port, so only container-isolated services and allocations take a slot's port.

A fork must never land on another service’s baseline port. forkspace check tests the config for that before anything starts: two services whose base ports sit a whole number of slots apart, fewer than 32, are an error, unless they are the same compose service shared between environments. Each instance is also its own compose project, fs-<workspace>-<env>-<fork>, so containers and volumes never share names.

Lifetimes

An environment marked persistent, like dev, keeps its volumes through down. Any other environment drops them, so a test run starts clean, seeded, and with no state left from the previous one. A baseline runs bootstrap then seed when it comes up.

Playground

A browser playground simulates forkspace without Docker: a terminal, guided scenarios, a command panel and a live forkspace.yml editor. Try it. The full command reference, hooks and env contract are in the GitHub README.