Quickstart

This guide walks you through creating a minimal Sigil environment with a Postgres database and a service that connects to it.

1. Create a config file

Create sigil.config.ts in your project root:

import { Environment, Postgres, Service } from "sigil";
import path from "path";

const root = import.meta.dir;
const env = new Environment("my-app");

// Add a Postgres database
const db = env.add(
  new Postgres("db", {
    port: 5432,
    database: "myapp",
    username: "postgres",
    password: "postgres",
  })
);

// Add your backend service
env.add(
  new Service("api", {
    command: ["node", "server.js"],
    cwd: path.join(root, "backend"),
    env: {
      DATABASE_URL: db.connectionString,
    },
    readyCheck: {
      url: "http://localhost:3000/health",
      timeout: 30000,
    },
  })
);

export default env;

2. Start the environment

sigil up

Sigil will:

1. Pull the Postgres Docker image (first run only)
2. Start a Postgres container
3. Wait for the database to be ready
4. Start your backend service with DATABASE_URL injected
5. Poll the health endpoint until the service is ready

Output looks like:

[sigil] Starting environment "my-app"...
[sigil] Starting entity: db
[sigil] Pulling image postgres:16...
[sigil] Container sigil-db started on port 5432
[sigil] Starting entity: api
[api] Server listening on port 3000
[sigil] All entities started. Press Ctrl+C to stop.

3. Check status

In another terminal:

sigil status

Instance: default (PID 12345, running, started 2m ago)
  Config: /path/to/sigil.config.ts
  Entities:
    db                   running
    api                  running

4. Tear down

sigil down

Or press Ctrl+C in the terminal running sigil up.

Named instances

You can run multiple instances simultaneously:

sigil up dev      # starts instance named "dev"
sigil up test     # starts instance named "test"
sigil status      # shows both
sigil down dev    # stops only "dev"

Next Steps

• Concepts — Understand entities, interfaces, and the lifecycle model
• Full-Stack Example — A complete app with Postgres + FastAPI + React