Ship products, not plumbing.

Reproducible dev environments, service orchestration, secrets management, and deployment —
powered by Nix, driven by a local agent, managed through a web studio or CLI.
No Nix knowledge required.

---

Warning

Stackpanel is alpha software — we do not recommend using it yet. It is under active development; APIs, configuration, and generated output may change without notice and things will break. Feel free to experiment and report issues, but don't build anything you care about on it yet.

Why Stackpanel?

Stackpanel is based upon a single foundational belief that half of all source code in our repositories today should actually be built.

Every new project means re-establishing the same foundations: database setup, environment variables, IDE config, deployment boilerplate. The value of your application lives in your source code, not in the glue around it. We believe that if you have a typescript project, any file that doesn't end in .ts is potential cruft, and that your build tool should be lower in the stack, and that build tool should be Nix.

Stackpanel replaces that glue with a single config.nix file. Deterministic ports, encrypted secrets, service orchestration, VS Code integration, TLS certificates, and deployment — all computed from one config. No lock-in: generated files are standard formats in standard locations. Eject anytime.

How It Works

The heart of Stackpanel is a local Go agent that runs on your machine and a web Studio that connects directly to it. When we say agent, we don't mean an LLM... We mean the before-times definition of a simple server you run off your machine that allows file editing to occur. The Studio is the interface; the agent does the work — reading and writing your project's files on disk. When you change something in the Studio (add an app, set a secret, enable a service), the agent serializes that change into your local .stack/config.nix and related files, then lets Nix take it from there. You manage your whole stack through the UI and never have to hand-write Nix.

This solves the second huge issue that almost everyone runs into with Nix - the learning curve is just too high for the average developer. The benefits of Nix are real - and now you don't even have to know you're using it. At a high-level, the architecture is like this:

Browser (Studio UI)
  │
  ├─ HTTP + Connect-RPC ──→ Go Agent (localhost:9876)   ← runs on your machine
  │                           ├── reads/writes .stack/config.nix, secrets, codegen
  │                           ├── nix eval (config, ports, packages)
  │                           ├── process-compose (service lifecycle)
  │                           ├── Caddy (reverse proxy, TLS)
  │                           └── Step CA (certificates)
  │
  └─ tRPC ──→ Cloud API (optional — accounts & billing)
                ├── Auth / Github Integration
                └── Anything else that would require a server in order to work

• Go agent (local) — a localhost HTTP server (default port 9876) that runs on your machine and is the single writer for your project files. The Studio talks to it directly over HTTP + Connect-RPC. It serializes UI changes into .stack/config.nix and secrets, runs nix eval to resolve your config, manages services via process-compose, and watches the filesystem (changes stream back to the UI over SSE).
• Web Studio — a React app (TanStack Start) for managing your entire stack visually: apps, services, secrets, config, deploys, and more. It connects straight to the local agent — there's no cloud round-trip to edit your project.
• Nix — the engine under the agent. Your .stack/config.nix is the source of truth; on shell entry Nix evaluates it to compute ports, provision the devshell, and generate files. The agent writes that config for you, so editing Nix by hand is optional.
• Cloud API (optional) — a web service for accounts, auth, and billing. It is not in the local development path; the Studio and agent work without it. Necessarily a server will have to be involved for certain features, mainly around deployment, team collaboration, and you feeding us via paid addons 😅

Quick Start

Prerequisites

• Nix with flakes enabled (Determinate Nix Installer recommended)
• direnv (optional but recommended)

Create a New Project

nix flake init -t github:darkmatter/stackpanel

echo 'use flake .' > .envrc
direnv allow

Add to an Existing Project

Auto-installer (If you are comfortable with nix, manual install is recommended):

# If you have a complex nix projet, this might fail
nix run github:darkmatter/stackpanel -- init

Manual install:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-parts.url = "github:hercules-ci/flake-parts";
    stackpanel.url = "github:darkmatter/stackpanel";
  };

  outputs = inputs @ {self, stackpanel, ...}:
    # This is essentially a wrapper around flake-parts `mkFlake`, should be
    # safe to replace if you're currently using flake-parts
    stackpanel.lib.mkFlake {
      inherit inputs self;

      perSystem = {pkgs, ...}: {
        packages.hello = pkgs.hello;
      };
    };
}

Configuration

Everything lives in .stack/config.nix:

{ config, ... }:
{
  stackpanel = {
    enable = true;

    # Apps — ports are computed deterministically from the project name
    apps.web.port = 3000;
    apps.api.port = 3001;

    # Services
    globalServices = {
      postgres.enable = true;
      redis.enable = true;
      minio.enable = true;
    };

    # Secrets (AGE/SOPS encrypted, team-based)
    secrets = {
      master-key.enable = true;
      apps.api.dev = {
        DATABASE_URL = "postgres://...";
        API_KEY = "secret:api-key";
      };
    };

    # IDE integration
    ide.vscode.enable = true;

    # Shell prompt theming
    theme.enable = true;

    # TLS via Step CA
    # step-ca.enable = true;

    # AWS Roles Anywhere
    # aws.roles-anywhere.enable = true;

    # Deployment
    deployment.alchemy = {
      deploy.enable = true;
      deploy.auto-provision-state-store = true;
    };
  };
}

Features

Nixpkgs Integration

Binary Cache

Inspector

Module Registry

Process Compose Integration

Age-Encrypted Secrets (SOPS)

Team Collaboration + Onboarding

Deterministic Ports

How many times have you run docker compose up just to have it fail due to conflicting ports? And so you use 5433 instead and before you know it, you can't figure out which one is for which app. Well never again! We use the github ref (org/repo) to determinstically compute a number between 3000-9999. Then we round down to the nearest 100, giving you about 70 namsepaces which should be enough. So each project has 100 ports, and within that range we again determinstically compute a port based on the name of the service. So postgres for darkmatter/stackpanel will always use the same port, regardless of what machine it runs on.:

my-project → base port 4200
  web      → 4200
  api      → 4201
  postgres → 4210
  redis    → 4211

Secrets Management

Team-based encrypted secrets with AGE/SOPS. Open source, version controlled, and uses simple tag-based grouping to remove the possibilty of duplication:

stackpanel.secrets = {
  master-key.enable = true;
  apps.api.dev = {
    DATABASE_URL = "postgres://...";
    STRIPE_KEY = "secret:stripe-key";
  };
};

IDE Integration

Auto-generated VS Code workspace with correct terminal environment, extension recommendations, debugger configurations, and task runners. Zed support coming soon.

Web Studio

A local web UI for managing your entire stack:

• Dashboard — overview of all apps, services, and health checks
• Services — start/stop/restart databases and services
• Secrets — manage encrypted environment variables
• Configuration — edit config.nix with a visual editor
• Deploy — trigger deployments to cloud infrastructure
• Processes — view and manage running processes
• Terminal — embedded terminal with devshell environment
• Packages — browse and add nixpkgs packages
• Extensions — install stackpanel extension modules

CLI (stackpanel)

The Go-based CLI provides everything the Studio does, plus more:

stackpanel commands          # List/run devshell scripts (interactive TUI)
stackpanel config show       # Print resolved configuration
stackpanel config example    # Generate example config
stackpanel env               # Show environment variables
stackpanel logs              # Tail service logs
stackpanel deploy            # Deploy to cloud
stackpanel agent             # Start the localhost agent server
stackpanel caddy             # Manage the shared Caddy reverse proxy
stackpanel init              # Initialize a new project
stackpanel nixify            # Generate Nix config for an existing project
stackpanel healthcheck       # Run health checks
stackpanel codegen           # Run host-side code generators
stackpanel flake             # Manage the Nix flake

Nix Module System

Stackpanel's core is an adapter-agnostic Nix module system. All logic lives in nix/stackpanel/ with zero dependency on devenv, NixOS, or any specific module host. Thin adapters translate to each target:

Namespace	Purpose
stackpanel.apps	App definitions with computed ports and URLs
stackpanel.services	Canonical service type system
stackpanel.globalServices	Convenience services (postgres, redis, minio)
stackpanel.devshell	Shell environment, packages, hooks, env vars, generated files
stackpanel.scripts	Shell commands (shown in TUI and Studio)
stackpanel.modules	Extension module registry
stackpanel.secrets	Master-key secrets management
stackpanel.ide	VS Code and Zed integration
stackpanel.theme	Starship prompt theming
stackpanel.step-ca	Certificate management
stackpanel.aws	AWS Roles Anywhere
stackpanel.process-compose	Process orchestration
stackpanel.deployment	Alchemy / cloud deployment

Deployment

Stackpanel supports deploying to cloud infrastructure via Alchemy, with support for Cloudflare Workers, microVMs (NixOS on OVH/Hetzner), and more. Colmena and nixos-anywhere are available for bare-metal NixOS deployments.

Project Structure

stackpanel/
├── apps/
│   ├── web/              # Studio UI (React + TanStack Start)
│   ├── api/              # Cloud API (Hono on Cloudflare Workers)
│   ├── docs/             # Documentation site (Next.js + Fumadocs)
│   ├── stackpanel-go/    # CLI + localhost agent (Go + Cobra + Bubble Tea)
│   └── tui/              # Terminal UI components (TypeScript + Ink)
├── packages/
│   ├── api/              # Shared business logic
│   ├── auth/             # Better-Auth config
│   ├── db/               # Drizzle ORM + Neon PostgreSQL
│   ├── ui/               # Shared UI components
│   ├── config/           # Config utilities
│   ├── infra/            # Infrastructure-as-code (Alchemy)
│   ├── proto/            # Connect-RPC protocol definitions
│   ├── sdk/              # Stackpanel SDK
│   ├── gen/              # Generated types
│   ├── agent-client/     # Go agent HTTP client
│   ├── scripts/          # Build and CI scripts
│   ├── docs-content/     # Shared documentation content
│   └── znv/              # Zod + env parsing
├── nix/
│   ├── stackpanel/       # Core Nix module system (adapter-agnostic)
│   ├── flake/            # Flake outputs (flakeModules, templates, devShells)
│   └── internal/         # Internal config for developing stackpanel itself
├── docs/                 # Architecture docs, specs, and design notes
└── examples/             # Example projects

Development

# Enter the dev shell
nix develop
# or with direnv
direnv allow

# Start all services
dev

# Individual apps
bun run dev:web       # Studio UI
bun run dev:server    # Cloud API
bun run dev:agent     # Go agent (alias for stackpanel agent)

Documentation

Full docs at stackpanel.com:

• Quick Start
• Concepts
• Configuration Reference
• Secrets Management
• Architecture

License

MIT — see LICENSE for details.