ai-igniter-1.5.0 is not a library.

🚀 ai-igniter

Stop fighting port conflicts across git worktrees. Start coding.

Lightning-fast, standalone workspace & service orchestrator for AI worktrees and parallel development.

ai-igniter demo

💡 Why ai-igniter?

When using AI coding agents (Cursor Agent, Claude Code, Aider) or working across multiple Git worktrees in parallel, your local development quickly breaks:

💥 Port Conflicts: Multiple branches try to bind to 3000, 5432, or 9000 simultaneously.
🤯 Dirty .env Files: Manual updates of database URLs and credentials per worktree are fragile and tedious.
🐌 Heavy Orchestration Scripts: Fragile bash or Node glue-scripts to manage Docker containers, healthchecks, and migrations.

ai-igniter solves this completely. It replaces complex scripts with a single, standalone Rust binary that orchestrates isolated services, resolves dynamic ports, runs migrations & seeds, and injects clean environment variables automatically.

🏛️ The Three Pillars

1. 🚦 Automatic Port Resolution & Isolation

Dynamic Port Mapping: Every worktree gets its own isolated port space (deterministic base port for stable URLs/cookies + dynamic OS allocation if ports are squatted).
Safe Port Reclaiming: Ports held by inactive ai-igniter containers are automatically freed without losing your volumes. Containers from external tools are left untouched.
Git-Native Resolution: Strict git worktree resolution guarantees commands never accidentally target another project's worktree.

2. 🧱 Zero-Config "À la Carte" Services

Enable only what your project needs via ai-igniter.toml:

PostgreSQL: Instant container with TCP health checks, optional secondary (E2E) database, automatic migration runners, and one-time initial seeders.
Garage S3: Self-contained S3-compatible storage with automatic bucket creation, access keys, permissions, CORS, and website hosting endpoints.
Custom Docker Services: Any Docker image (e.g. Mailpit, Redis, Meilisearch) configured with custom ports and volumes in seconds.

3. 📝 Atomic Environment Management

Injects evaluated service URLs, credentials, and ports into a dedicated section of your target environment file (e.g., .env or .env.local).
Preserves all your existing custom variables outside the managed section.
One-time seed copying (copy_files) from your main repository checkout when creating new worktrees.

📖 Deep Dive: Want to understand the resolution hierarchy, deterministic port hashing, and anti-hijacking system? Check out the Workspace Resolution & Port Allocation Guide. For details on the dual-engine auto-updater and non-blocking background notifications, read the Update & Release Architecture Guide.

📦 Installation

Via Cargo (Recommended)

Install the latest release directly from crates.io:

cargo install ai-igniter

Pre-built Binaries

Pre-compiled standalone binaries for macOS, Linux, and Windows are also available on each release:

Download the archive for your platform from the GitHub Releases page:
- macOS (Apple Silicon / M-series): ai-igniter-aarch64-apple-darwin.tar.gz
- macOS (Intel): ai-igniter-x86_64-apple-darwin.tar.gz
- Linux (Static / musl): ai-igniter-x86_64-unknown-linux-musl.tar.gz
- Linux (glibc): ai-igniter-x86_64-unknown-linux-gnu.tar.gz
- Windows: ai-igniter-x86_64-pc-windows-msvc.zip
Extract and move the binary to your PATH:

# macOS / Linux example
tar -xzf ai-igniter-*-apple-darwin.tar.gz
sudo mv ai-igniter /usr/local/bin/

Note: For bleeding-edge/unreleased builds, you can also download binary artifacts directly from the GitHub Actions CI runs.

From Source (Development)

To build and install ai-igniter locally from source:

# Clone the repository
git clone https://github.com/ScreamZ/ai-igniter.git
cd ai-igniter

# Install locally with Cargo
cargo install --path .

Or build the release binary manually:

cargo build --release
sudo cp target/release/ai-igniter /usr/local/bin/

⚡ Quick Start

1. Initialize your project

Run the interactive wizard in your repository root:

ai-igniter init

This guides you through configuring services (PostgreSQL, S3), and creates an ai-igniter.toml configuration file.

2. Start developing

Spin up all workspace services, run migrations/seeds, update .env, and start your dev server in one step:

ai-igniter dev

Tip: When you press Ctrl+C, ai-igniter gracefully stops all associated Docker containers and child processes.

3. Or bootstrap without starting services

If you want to create your .env, seed files, compose file, and Docker volumes/containers ahead of time without running the services:

ai-igniter bootstrap
# or alias
ai-igniter setup

4. Teardown when finished

When you delete or archive a worktree, clean up all associated containers, networks, and volumes cleanly:

ai-igniter teardown

⚙️ Configuration (`ai-igniter.toml`)

Minimal Example

Here is all you need for a full Next.js / Node app with PostgreSQL:

name = "my-awesome-app"
env_file = ".env"
copy_files = []
dev_command = "bun run dev"

[services.postgres]
enabled = true
port_offset = 1
database = "app_db"
user = "app_user"
password = "app_password"
migrate_command = "bun run db:migrate"

[env_template]
DATABASE_URL = "{{services.postgres.url}}"
APP_URL = "http://localhost:{{ports.base}}"

name = "my-project"
env_file = ".env"                          # Target file receiving managed env vars
copy_files = []                            # Files to seed from root checkout on first use
dev_command = "bun run dev"                # Command executed after services are healthy
# base_port = 3000                         # Optional fixed base port
# compose_file = "docker-compose.dev.yml"  # Optional: use custom compose file

# Built-in PostgreSQL
[services.postgres]
enabled = true
port_offset = 1
image = "postgres:16"
database = "my-project"
user = "my-project"
password = "my-project"
e2e_database = "my-project_e2e"
migrate_command = "bun run db:migrate"
seed_command = "bun run db:seed"
# seed_check_sql = "SELECT count(*) FROM users"

# Built-in Garage S3
[services.garage]
enabled = true
port_offset = 3
web_port_offset = 4
image = "dxflrs/garage:v2.4.1"
access_key = "my-project-local-access-key"
secret_key = "my-project-local-secret-key-change-me"
buckets = ["my-project-assets"]
website_buckets = ["my-project-assets"]
website_root_domain = ".web.localhost"

# Custom Services (e.g. Mailpit)
[services.custom.mailpit]
image = "axllent/mailpit"
port_offset = 8
target_port = 8025
environment = { MP_MAX_MESSAGES = "500" }
command = ["--smtp-auth-accept-any"]
volumes = ["./.mailpit:/data", "mailpit-cache:/cache"]

# Dynamic environment template
[env_template]
DATABASE_URL = "{{services.postgres.url}}"
DATABASE_MIGRATION_URL = "{{services.postgres.url}}"
E2E_DATABASE_URL = "{{services.postgres.e2e_url}}"
S3_ENDPOINT = "{{services.garage.endpoint}}"
S3_ACCESS_KEY_ID = "{{services.garage.access_key}}"
S3_SECRET_ACCESS_KEY = "{{services.garage.secret_key}}"
S3_REGION = "{{services.garage.region}}"
S3_BUCKET = "my-project-assets"
S3_PUBLIC_URL = "http://my-project-assets{{services.garage.website_root_domain}}:{{services.garage.web_port}}"
MAIL_UI_URL = "http://localhost:{{services.mailpit.port}}"
APP_URL = "http://localhost:{{ports.base}}"

Available Template Placeholders

Placeholder	Description
`{{ports.base}}`	Primary workspace application port
`{{ports.<name>}}` / `{{ports.base + N}}`	Allocated port for a service, or base + arithmetic offset
`{{services.postgres.url}}` / `e2e_url`	Full PostgreSQL connection URLs with URL-encoded credentials
`{{services.postgres.port}}` / `host` / `user` / `password` / `database`	Granular PostgreSQL connection details
`{{services.garage.endpoint}}` / `access_key` / `secret_key` / `web_port`	Garage S3 connection & web endpoints
`{{services.<name>.port}}`	Host port for custom service declared in `[services.custom.<name>]`
`{{workspace.slug}}` / `{{workspace.hash}}` / `{{workspace.path}}`	Current workspace identity metadata

🤖 Orchestrator Integrations

Paseo (`paseo.json`)

{
  "worktree": {
    "teardown": "ai-igniter teardown"
  },
  "scripts": {
    "services": {
      "type": "service",
      "command": "ai-igniter dev"
    }
  }
}

Conductor / Cursor Worktrees / Standalone CLI

Add ai-igniter dev to your worktree initialization hook or launch task, and ai-igniter teardown on worktree deletion.

🛠️ CLI Command Reference

Command	Description
`ai-igniter init`	Interactive wizard to initialize `ai-igniter.toml`.
`ai-igniter bootstrap` (alias: `setup`)	Write `.env`, copy seed files, generate compose, and create Docker volumes & containers without starting.
`ai-igniter dev` (alias: `up`)	Start services, run migrations/seeds, write `.env`, and launch dev command.
`ai-igniter dev --reset`	Reset database/storage volumes to fresh state, re-seed, and start.
`ai-igniter dev --no-command`	Run and supervise background Docker services without launching `dev_command`.
`ai-igniter dev -- <cmd>`	Override the default `dev_command` (e.g. `ai-igniter dev -- cargo run`).
`ai-igniter teardown` (alias: `down`)	Stop and remove this workspace's containers, networks, and volumes.
`ai-igniter status`	Inspect allocated ports and container health for the current workspace.
`ai-igniter env`	Print or update (`--write`) evaluated environment variables.
`ai-igniter update` (alias: `upgrade`)	Check for and install updates via GitHub Releases (or `--cargo`).

🏗️ Architecture & Extensibility

ai-igniter is built in Rust with modularity in mind:

src/
├── cli.rs               # Clap definitions & CLI arguments
├── commands/            # init, dev, teardown, status, env, update
├── config.rs            # TOML parsing, validation & defaults
├── context.rs           # Workspace & port resolution engine
├── docker/              # Dynamic Compose generator & port reclaimer
├── env_writer.rs        # Atomic .env delimiter engine
├── services/            # Built-in providers (PostgreSQL, Garage S3, Custom)
└── supervisor.rs        # Process supervisor & signal trap (SIGINT/SIGTERM)

Adding a new built-in service

Create src/services/<service_name>.rs implementing the ServiceProvider trait.
Register it in BUILTIN_SERVICES in src/services/mod.rs.
All commands (init, dev, status, etc.) will automatically support your new service!

ai-igniter 1.5.0

🚀 ai-igniter

💡 Why ai-igniter?

🏛️ The Three Pillars

1. 🚦 Automatic Port Resolution & Isolation

2. 🧱 Zero-Config "À la Carte" Services

3. 📝 Atomic Environment Management

📦 Installation

Via Cargo (Recommended)

Pre-built Binaries

From Source (Development)

⚡ Quick Start

1. Initialize your project

2. Start developing

3. Or bootstrap without starting services

4. Teardown when finished

⚙️ Configuration (`ai-igniter.toml`)

Minimal Example

Available Template Placeholders

🤖 Orchestrator Integrations

Paseo (`paseo.json`)

Conductor / Cursor Worktrees / Standalone CLI

🛠️ CLI Command Reference

🏗️ Architecture & Extensibility

Adding a new built-in service

📄 License

ai-igniter 1.5.0

🚀 ai-igniter

💡 Why ai-igniter?

🏛️ The Three Pillars

1. 🚦 Automatic Port Resolution & Isolation

2. 🧱 Zero-Config "À la Carte" Services

3. 📝 Atomic Environment Management

📦 Installation

Via Cargo (Recommended)

Pre-built Binaries

From Source (Development)

⚡ Quick Start

1. Initialize your project

2. Start developing

3. Or bootstrap without starting services

4. Teardown when finished

⚙️ Configuration (ai-igniter.toml)

Minimal Example

Available Template Placeholders

🤖 Orchestrator Integrations

Paseo (paseo.json)

Conductor / Cursor Worktrees / Standalone CLI

🛠️ CLI Command Reference

🏗️ Architecture & Extensibility

Adding a new built-in service

📄 License

⚙️ Configuration (`ai-igniter.toml`)

Paseo (`paseo.json`)