Local dev stack manager. Auto-allocates ports, manages Docker Compose services, generates .env files, and provides a single CLI for the entire local development lifecycle.

When you work on multiple projects that each run PostgreSQL, Redis, and object storage locally, port conflicts are inevitable. Vivarium solves this by assigning each project a unique index and deterministically computing all ports from it. No conflicts. No manual bookkeeping.

• Convention over configuration. Sensible defaults for ports, service names, and env vars mean minimal config for common stacks.
• Generated artifacts are ephemeral. Compose files and .env files are regenerated on every setup. Don't edit them by hand.
• One command to rule them all. vivarium setup does everything: allocates ports, generates config, starts services, runs post-setup hooks.
• No runtime dependencies beyond Docker. Node.js is only needed to run the CLI itself.

If these opinions don't align with your workflow, this may not be the right tool for you.

• Node.js >= 20
• Docker with Compose v2 (included in Docker Desktop)
• AWS CLI -- only required if using the S3 service

npm install -g vivarium-cli

1. Create a vivarium.json in your project root:

{
  "services": {
    "postgres": { "user": "myapp", "password": "myapp", "database": "myapp" },
    "redis": true
  },
  "packages": {
    "backend": {
      "envFile": "backend/.env",
      "postSetup": ["pnpm db:migrate"]
    },
    "frontend": {
      "envFile": "frontend/.env"
    }
  }
}

2. Run setup:

vivarium setup

For the full configuration schema and all available options, see the documentation.

Full documentation is at vivarium.niranjan.io.

• CLI reference
• Configuration schema
• Environment variables
• Port allocation
• MCP proxy
• Architecture

git clone https://github.com/niranjan94/vivarium.git
cd vivarium
pnpm install

Contributions are welcome -- open an issue or submit a pull request. Report bugs and suggest features at github.com/niranjan94/vivarium/issues.

MIT -- Niranjan Rajendran