Core Options

checks

Additional flake checks contributed by stackpanel modules.

---

debug

Whether to enable Enable Stackpanel Debug Mode.

Example:

true

---

direnv.hide-env-diff

Hide the 'direnv: export +VAR...' log line (requires user's direnv.toml)

---

dirs

Directories used by stackpanel.

---

dirs.config

Directory for stackpanel configuration files.

---

dirs.data

Full data directory path (relative to project root). Computed as: dirs.home + "/data" This is read-only - configure dirs.home instead.

---

dirs.gen

Full generated files directory path (relative to project root). Computed as: dirs.home + "/gen" This is read-only - configure dirs.home instead.

---

dirs.home

Root directory for stackpanel files (relative to project root). This is the ONLY configurable directory option.

Subdirectories are automatically computed:

Example: ".stack" → keys at ".stack/keys", profile at ".stack/profile"

---

dirs.keys

Full keys directory path (relative to project root). Persistent credentials only. Computed as: dirs.home + "/keys"

---

dirs.profile

Full profile directory path (relative to project root). Ephemeral runtime/cache (safe to delete). Computed as: dirs.home + "/profile" Replaces legacy state/ for stackpanel.json, shell.log, etc.

---

dirs.state

DEPRECATED: Use dirs.profile. Alias for profile for backward compatibility.

---

enable

Whether to enable Enable Stackpanel.

Example:

true

---

git-hooks

Git hooks configuration fragment (consumed by git-hooks.nix).

---

github

DEPRECATED: Use stackpanel.project.owner and stackpanel.project.repo instead.

GitHub repository in 'owner/repo' format for this project. This value is used as a key for certain features like stable port calculation and user sync.

Example:

"darkmatter/stackpanel"

---

gitignore

Reserved options for managed .gitignore generation.

Stackpanel core owns a block-managed section in .gitignore and merges entries from this option. This provides a stable, explicit API for common .gitignore presets while still allowing modules to contribute entries.

The generated block is deduplicated and sorted.

---

gitignore.defaults

Toggle built-in .gitignore presets managed by Stackpanel.

---

gitignore.defaults.addProjectMarker

DEPRECATED: Use stackpanel.gitignore.defaults.projectMarker instead. Backward-compatible alias for including stackpanel.root-marker in .gitignore.

---

gitignore.defaults.localConfig

Include .stack/config.local.nix.

---

gitignore.defaults.projectMarker

Include the root marker file (stackpanel.root-marker).

---

gitignore.defaults.stackpanelState

Include .stack/state/.

---

gitignore.defaults.tasksDir

Include .tasks.

---

gitignore.enable

Whether Stackpanel should manage a .gitignore block.

---

gitignore.entries

Additional .gitignore entries to include in the managed block.

Example: [ "dist/" ".env.local" ]

---

moduleRequirements

Variable requirements declared by enabled modules. Modules add entries here to declare what environment variables they need. The agent/UI can query this to show what's missing.

Format: { moduleName = { requires = [ ... ]; provides = [ ... ]; }; }

---

moduleRequirements.<name>.provides

Environment variables provided by this module after setup

---

moduleRequirements.<name>.requires

Variables required by this module

---

moduleRequirements.<name>.requires.*.action

Action to resolve this variable if missing

---

moduleRequirements.<name>.requires.*.action.label

Button/link label

---

moduleRequirements.<name>.requires.*.action.type

Action type: add-secret, add-variable, external

---

moduleRequirements.<name>.requires.*.action.url

External URL for creating the value

---

moduleRequirements.<name>.requires.*.description

Description of the variable

---

moduleRequirements.<name>.requires.*.key

Environment variable name

---

moduleRequirements.<name>.requires.*.sensitive

Whether the value should be treated as a secret

---

name

Name of your project. May be used for naming things and diplay purposes.

---

project

Project metadata including type, owner, and repository information.

---

project.name

Project name (defaults to stackpanel.name)

---

project.owner

Owner/organization of the project repository

Example:

"darkmatter"

---

project.repo

Repository name

Example:

"stackpanel"

---

project.type

Project type (e.g., 'github', 'gitlab', 'local')

---

root

Absolute path to the project root. If set, this overrides PWD-based detection.

The stackpanel flake module sets this automatically to toString self — the flake source as copied into the Nix store — which works for both pure and impure evaluation. Override it only if you need a different path (for example to point at the user's working tree to read gitignored build artifacts).

---

root-marker

Filename for the root marker file written to the project root. Contains the absolute path to the project root, allowing tools to find the project from any subdirectory. Add to .dockerignore and .gitignore so containers create their own marker.

---

serializable

Serializable configuration data for the agent and CLI. Modules can contribute their JSON-safe config here. This data is included in stackpanelConfig for external tools.

---