fnox-configuration

name

fnox-configuration

description

Guides fnox secrets management configuration via fnox.toml — file structure, secrets definition, profiles, hierarchical config, mise integration, import/export, and sync. Always use fnox as a mise integration, never as standalone shell integration. Triggers on: "set up fnox", "fnox.toml", "configure fnox", "fnox profiles", "fnox secrets", "mise fnox", "migrate to fnox", "fnox sync", "fnox import", "fnox export".

Fnox Configuration

Fnox is a secrets manager ("Fort Knox for your secrets") that stores encrypted secrets in fnox.toml and integrates with mise to load them as environment variables.

Key rule: always configure fnox through the mise integration, not shell integration.

When to Use This Skill

Use this skill when:

• Setting up or configuring fnox in a project
• Defining secrets in fnox.toml
• Creating or managing profiles (dev, staging, production)
• Configuring hierarchical secrets across monorepo services
• Migrating from .env files to fnox
• Syncing remote provider secrets to a local cache
• Troubleshooting secret loading issues

When NOT to Use This Skill

• Managing secrets with a different tool (Vault, Doppler, AWS SSM directly) — use their native tooling
• General .env file questions not involving fnox
• Setting up mise itself (without fnox) — use mise documentation
• Storing secrets as environment variables in CI without fnox — configure the CI provider directly

Core Principles

1. Mise integration only: Configure via mise.toml, not eval "$(fnox activate bash)"
2. tools = true is required: Without it, mise runs the plugin before fnox is in PATH
3. Profiles for environments: Use [profiles.staging.secrets], never separate .env.staging files
4. Hierarchical for monorepos: Child fnox.toml files override parent secrets
5. fnox.local.toml for personal overrides: Always gitignore it

Mise Integration Setup

Every project using fnox must have this in mise.toml:

[plugins]
fnox-env = "https://github.com/jdx/mise-env-fnox"

[tools]
fnox = "latest"

[env]
_.fnox-env = { tools = true }

To use a specific profile:

[env]
_.fnox-env = { tools = true, profile = "staging" }

For per-environment mise files (mise.staging.toml, mise.production.toml):

# mise.staging.toml
[env]
_.fnox-env = { tools = true, profile = "staging" }

MISE_ENV=staging mise env   # activates staging profile

fnox.toml File Structure

# Providers — how secrets are encrypted/stored
[providers]
age = { type = "age", recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"] }

# Secrets — the default (development) profile
[secrets]
API_URL = { default = "http://localhost:3000" }
DATABASE_URL = { provider = "age", value = "AGE-ENCRYPTED..." }
LOG_LEVEL = { default = "info" }

# Profile-specific secrets
[profiles.staging.secrets]
API_URL = { default = "https://staging.example.com" }
DATABASE_URL = { provider = "age", value = "AGE-ENCRYPTED-STAGING..." }

[profiles.production.providers]
aws = { type = "aws-sm", region = "us-east-1" }

[profiles.production.secrets]
API_URL = { default = "https://api.example.com" }
DATABASE_URL = { provider = "aws", value = "prod/database-url" }

Quick Reference

Task	Command
List secrets	fnox list
Get a secret	fnox get DATABASE_URL
Set a secret	fnox set DATABASE_URL "value" --provider age
Run with secrets	fnox exec -- node server.js
Use a profile	fnox exec --profile production -- ./deploy.sh
Export as .env	fnox export
Import from .env	fnox import -i .env --provider age
Sync to local cache	fnox sync --provider age --config fnox.local.toml
List profiles	fnox profiles
Check config files	fnox config-files

Progressive Disclosure

For detailed guidance on specific topics, load the appropriate reference:

• Mise integration details → Read references/mise-integration.md
• Profiles (multi-environment) → Read references/profiles.md
• Hierarchical config (monorepos) → Read references/hierarchical-config.md
• Import / Export → Read references/import-export.md
• Syncing to local cache → Read references/sync.md

Gitignore Rules

Always add to .gitignore:

fnox.local.toml
.fnox.local.toml

Commit fnox.toml (encrypted secrets are safe). Never commit fnox.local.toml.

Troubleshooting

Issue	Solution
Secrets not loading	Verify fnox.toml exists; run mise env to check
fnox: command not found	Ensure tools = true in mise.toml env plugin config
Cache not refreshing	Run mise cache clear
Wrong profile loading	Check FNOX_PROFILE env var; verify mise.toml profile option
Parent secrets not merging	Check fnox config-files to see which files are loaded