Services

Stackpanel can run background services for your local development environment—databases, caches, object stores, and anything else your app depends on. Services get deterministic ports, start and stop together, and are configured from the same Nix source of truth as the rest of your environment.

Global Services

The fastest way to add a service is through stackpanel.globalServices. These are preconfigured, opinionated setups for common infrastructure:

stackpanel.globalServices = {
  enable = true;
  project-name = "myapp";

  postgres.enable = true;
  redis.enable = true;
  minio.enable = true;
};

That's it. Enabling a global service gives you:

• The service binary on your PATH (e.g., psql, redis-cli, mc)
• A deterministic port computed from your project name
• An environment variable with the assigned port (STACKPANEL_POSTGRES_PORT, etc.)
• A managed process via process-compose
• CLI commands to start, stop, restart, and check status

Managing Services

Once services are configured, you can manage them through the CLI:

# Start all services
stackpanel services start

# Stop all services
stackpanel services stop

# Check status
stackpanel services status

# Restart a specific service
stackpanel services restart postgres

# View logs
stackpanel logs postgres

Or through Studio, which provides a visual dashboard for all running services.

The Service Type System

Under the hood, global services are built on stackpanel.services—a canonical type system for describing any background process. Each service has:

You can use this lower-level API to define custom services that don't fit the global service presets. See Custom Services for details.

Available Services

How Services Run

Services are orchestrated by process-compose, a lightweight process manager. When you run stackpanel services start, process-compose launches all enabled services, respects dependency ordering, runs health checks, and streams logs.

The Stackpanel Agent wraps process-compose and provides:

• A REST API for starting, stopping, and querying services
• SSE events for real-time status updates in Studio
• File watching to restart services when configuration changes
• Log aggregation and streaming

stackpanel services start
  → Agent starts process-compose
    → PostgreSQL starts on port 4237
    → Redis starts on port 4252
    → Health checks pass
    → Services reported as ready

Reference

• Options Reference → GlobalServices for all global service options
• Options Reference → Services for the lower-level service type system
• CLI → Services for CLI commands