Getting Started (How to Use)

Once Gantry is installed, you can transition a repository into an operational, healthy environment in three steps:

1. Initialize Gantry: Generate the lockfile configuration by running gantry init. This scans your Docker Compose, package.json files, and env templates.
2. Verify the Plan: Run gantry plan to preview the execution graph of OCI services and native application tasks.
3. Launch the Stack: Execute gantry start to spin up container services, run setup/migration scripts, and start local development servers.

To check stack parameters (such as mapped ports, active process IDs, and health check state) at any time, run:

$ gantry status

When you are finished developing, gracefully stop the environment with gantry stop. To erase container instances and wipe local volume storage, append the destroy flag:

$ gantry stop --destroy

OCI Containers & Local Apps

Gantry provides a unified orchestration layer coordinating containerized backing services and local native processes concurrently.

1. Container Reconciliation

Instead of rebuild-heavy container restarts, Gantry analyzes container configurations (ports, volumes, environment, hashes). If a container already matches the current gantry.yml state, Gantry reuses it. If configurations differ, Gantry safely tears down and replaces it.

2. Local Process Execution

Backing services run inside containers, while applications (Node/Bun/Python) run directly on the host machine using Bun.spawn. This avoids virtualization overhead while retaining dynamic connection binding.

3. Dynamic Port & Endpoint Mapping

Ports bind to random free loopback addresses (like 127.0.0.1:49153) to prevent collisions. Gantry resolves environment connections dynamically:

apps:
  web:
    dependencies: [db]
    env:
      # Resolved and bound dynamically at launch
      DATABASE_URL: "${services.db.url}"

AI Coding Agent Integration Playbook

AI Coding Agents (like Devin, Auto-GPT, or custom script engines) require stable, machine-readable environments. Gantry serves as the agent-ready state contract:

1. JSON State map

Agents should invoke gantry status --json to inspect active PIDs, loopback connection strings, container IDs, and health parameters in a structured format:

$ gantry status --json
{
  "project": "my-app",
  "ok": true,
  "services": {
    "db": { "status": "ready", "port": 49153, "url": "postgres://..." }
  }
}

2. Credentials Redaction

By default, Gantry masks passwords and generated credentials as [redacted] in log streams and JSON outputs. Agents requiring plaintext keys must explicitly pass the include-secrets option:

$ gantry status --json --include-secrets

3. Automated Setup Flow

A typical agent workflow looks like this:

# 1. Initialize lockfile
gantry init
# 2. Assert no local configuration drift
gantry sync
# 3. Spin up environment
gantry start --json
# 4. Run tests or execute modifications
gantry status --json

Drift Detection & Syncing

Maintaining separate configuration manifests always risks configuration drift. Gantry eliminates this by treating existing files (like docker-compose.yml and package.json) as the primary source of truth.

The generated gantry.yml acts as a lockfile. When running gantry sync, Gantry compares the lockfile with repository files:

$ gantry sync
changed  db  compose.yaml
Run gantry sync --write to update config.

If a drift is found, Gantry exits with code 1. This makes it suitable for CI pre-commit checks to enforce configuration integrity:

# Enforces synchronization in build pipelines
gantry sync

CLI Command Reference

Gantry exposes a standard command surface built for local terminal use and automation tooling.