Concepts

Environment

An Environment is the top-level container. It holds a collection of entities that together form your local stack.

const env = new Environment("my-app");

When you call env.up(), all entities start sequentially in the order they were added. When you call env.down(), they stop in reverse order.

Entities

An Entity is anything that runs — a database, a service process, a browser instance. Each entity has:

• A name (unique within the environment)
• A status lifecycle: pending → starting → running → stopping → stopped (or error)
• A start() and stop() method
• Zero or more interfaces

Built-in entity types

Entity	What it does	Backed by
Postgres	Runs a PostgreSQL database	Docker container
Service	Runs any command as a process	Bun.spawn subprocess
Browser	Launches a browser instance	Puppeteer (coming soon)

Interfaces

An Interface describes how an entity is exposed — its protocol, port, and connection details.

// Postgres exposes a PostgresInterface
db.connectionString  // "postgresql://postgres:postgres@localhost:5432/myapp"

// A Service can hold any interface
new Service("frontend", config, [new BrowserInterface(3000)])
new Service("backend", config, [new APIInterface(8000)])

Interfaces provide:

• protocol — "http", "tcp", "ws", or "grpc"
• port — The port number
• host — Defaults to "localhost"
• getConnectionString() — A URL for connecting
• isReady() — An async readiness check

Startup Order

Entities start sequentially in the order you call env.add(). This matters because later entities often depend on earlier ones:

// db starts first
const db = env.add(new Postgres("db", { ... }));

// backend starts after db is running — can use db.connectionString
const backend = env.add(new Service("backend", {
  env: { DATABASE_URL: db.connectionString },
  ...
}));

// frontend starts after backend is running
env.add(new Service("frontend", { ... }));

Shutdown happens in reverse order: frontend → backend → db.

Instance Namespacing

Each sigil up creates a named instance (default name: "default"). Instance state is stored at .sigil/instances/<name>.json in your project directory.

This means:

• Multiple instances can run simultaneously with different names
• sigil down finds the right process to stop via the state file
• sigil status shows all running instances
• Stale state files (from crashed processes) are automatically cleaned up

Config File

A sigil.config.ts file exports an Environment as its default export. Sigil dynamically imports this file at runtime — no build step needed.

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

const env = new Environment("my-app");
// ... add entities ...
export default env;

See the Config File Reference for full details.