PreviewCTL

Preview environments,
one command away.

Define your entire stack in a single YAML file. PreviewCtl spins up ephemeral Docker environments locally — with dependency resolution, secret injection, and automatic cleanup.

Get Started GitHub

go install github.com/previewctl/previewctl-cli@latest

Everything you need for local preview environments

PreviewCtl handles the orchestration so you can focus on building your application.

📦

One YAML, Full Stack

Define services, databases, workers, and their dependencies in a single preview.yml config file.

🔀

DAG-Based Ordering

Services start in the correct order. PreviewCtl resolves dependency graphs so postgres starts before your API.

🐳

Multiple Build Types

Build from Dockerfiles, Nixpacks, or Railpack — or use pre-built images. Mix and match per service.

🔐

Secret Injection

Reference secrets with ${secrets.KEY} syntax. Pass them via --secret flags or .env files.

🌐

Service Networking

Containers are wired together automatically. Reference other services with ${services.api.host} templating.

⏱️

TTL & Auto-Cleanup

Set a TTL on preview environments and they clean themselves up. No stale containers lingering.

Your entire stack in one file

A single .previewctl/preview.yml describes your services, builds, dependencies, and environment variables. Run previewctl up and everything comes alive.

• Service-to-service references with ${services.*} templating
• Auto-generated passwords with ${Generate(16)}
• External secrets via ${secrets.*}
• Dependency ordering with depends_on

preview.yml

version: 1

preview:
  ttl: 24h

services:
  frontend:
    build:
      type: dockerfile
      context: .
      dockerfile: frontend/Dockerfile
    port: 3000
    env:
      API_URL: http://${services.api.host}:${services.api.port}
    depends_on:
      - api

  api:
    build:
      type: railpack
      context: ./api
    port: 8080
    env:
      DATABASE_URL: ${services.postgres.env.POSTGRES_URL}
      STRIPE_API_KEY: ${secrets.STRIPE_API_KEY}
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16
    port: 5432
    env:
      POSTGRES_DB: mydb
      POSTGRES_PASSWORD: ${Generate(16)}

  redis:
    image: redis:7
    port: 6379

Ready to spin up your first preview?

Get started in under a minute.

1 go install github.com/previewctl/previewctl-cli@latest

2 previewctl init

3 previewctl up

Read the Guide