How to stop parallel coding agents fighting over ports and databases

Separate Git worktrees prevent file collisions, but parallel coding agents can still fight over ports, databases, containers, caches, and test artifacts. Assign every agent a unique runtime namespace and generate its environment from that assignment before starting any dev server or test suite.

Why do agents still collide in separate worktrees?

Two agents in separate worktrees may still connect to:

• port 3000,
• the same local PostgreSQL database,
• the same Redis keyspace,
• the same Docker Compose project,
• the same browser-test output directory,
• the same cloud development resources,
• the same rate-limited third-party account.

These collisions create flaky tests and misleading results even when Git is clean. One agent may reset the shared test database while another is asserting against it. Both agents blame their code because neither sees the other process.

Give every agent its own runtime slot

Assign a short safe slug and derive all resources from it:

Store the values in an ignored worktree-specific file:

AGENT_SLOT=claude-billing
WEB_PORT=3101
API_PORT=4101
DATABASE_URL=postgresql://localhost/app_claude_billing
COMPOSE_PROJECT_NAME=app_claude_billing

Validate slugs before interpolating them into identifiers or shell commands. Prefer a small allowlisted pattern such as lowercase letters, numbers, and hyphens.

How should each agent get a separate database?

Use one database, schema, or disposable container per agent. A separate database provides the clearest boundary for migrations and fixtures. If schemas are used, confirm the application and migration tool correctly respect the schema on every connection.

Never let an unattended development agent run destructive tests or migrations against production. Use synthetic or appropriately minimized development data.

How do you run Docker Compose from several worktrees?

Compose project names determine container, network, and volume namespaces. Give each agent a unique project name and avoid fixed container names in Compose files. Fixed host ports will still collide, so parameterize them.

Which test outputs and caches need isolation?

Configure unique output directories for screenshots, coverage, traces, and temporary downloads. Shared read-only package caches can save time, but tools that mutate caches unsafely may need per-agent locations.

External APIs also require coordination. Separate credentials do not remove account-level rate limits or spending caps. Use mocks when possible and track aggregate usage.

What should you check before starting each agent?

Before an agent starts work, verify:

1. Its branch and worktree are correct.
2. Assigned ports are free.
3. The database name belongs to its slot.
4. No production hostname appears in environment variables.
5. Its Compose project name is unique.
6. Output directories are scoped to the worktree.
7. The expected test command succeeds in isolation.

On a persistent Matrix computer, use named terminal sessions to keep each runtime identifiable and Symphony to inspect parallel work. For the Git layer, read Git worktrees for coding agents.

Common questions about parallel-agent runtime conflicts

Why do tests fail only when two agents run?

Look for shared databases, fixed ports, global temporary directories, Compose names, rate limits, and tests that assume exclusive access to mutable data.

Is a different port enough?

No. Ports solve listener collisions. Databases, queues, caches, files, containers, and external accounts can still be shared.

Should every agent get a separate VM?

That provides stronger isolation and may be appropriate for untrusted or resource-heavy work. For trusted development tasks, worktrees plus explicit runtime namespaces are often faster and cheaper.