Frequently asked questions

A native macOS app that runs your whole local development stack, the apps, workers, one-shot jobs, and tunnels, from a single .stacksmith.yml file. It handles dependency-aware startup, health checks, per-component logs, and role-aware failure diagnosis from one window.

Those are excellent, lightweight process runners: you list your processes and they start them together, usually in one terminal. Stacksmith works at a higher level and adds:

• Dependency-aware ordering. Declare that the worker waits until the API is healthy, or that a migration completes first, using explicit conditions (started, healthy, port_listening, completed). Most Procfile runners start everything at once with no readiness model.
• Health checks. HTTP or command probes gate readiness, so "running" means "actually ready".
• Roles. It separates long-running apps and workers from one-shot jobs, and models tunnels and their public URLs.
• Diagnosis. When something fails it shows the affected component, the evidence, and a recommended action, optionally as a plain-language brief generated on-device, instead of leaving you to scroll a merged log.
• A native GUI and an MCP server so AI assistants can inspect and control the stack.

The trade-off: foreman, overmind, hivemind, and mprocs are free, open-source, cross-platform, terminal-native, and trivial to script in CI. Stacksmith is a paid macOS GUI app (Apple silicon, macOS 26). If you just need to start a handful of processes together, those tools are simpler and lighter. If you want readiness, dependencies, health, and guided debugging in one place, that is where Stacksmith helps.

process-compose is the closest in capability: a docker-compose-style process orchestrator with dependencies, health checks, and a TUI, and it is free, open-source, cross-platform, and works in CI. If you want orchestration in the terminal or in automated pipelines, process-compose is a great fit. Stacksmith covers similar ground but focuses on a native macOS experience: a graphical control surface, role-aware diagnosis, on-device AI incident briefs, tunnel modelling, and an MCP integration for AI agents. Pick process-compose for cross-platform, CI, and terminal use; pick Stacksmith if you work on a Mac and want the GUI, diagnosis, and agent integration.

docker-compose orchestrates containers. Stacksmith runs your processes directly on your Mac, the same way you would by hand, so there is no image build or virtualization overhead and your ports, paths, and tooling are the local ones. Use docker-compose when you specifically want containers; use Stacksmith to orchestrate native local processes.

Yes. There is a one-time 7-day free trial with full functionality and no licence key required. After that, a one-time purchase unlocks it. Stacksmith is in beta and offered at a reduced beta price of $9.99; the price rises to $19.99 when it leaves beta, and anyone who buys during beta keeps their price.

Stacksmith is usable day to day but still maturing: you may hit bugs, and features can change between updates. It is provided as-is (see the Terms). We ship updates often and welcome reports via GitHub issues.

If you can start it from a shell command, Stacksmith can run it: Rust, Go, Node, Python, Ruby, databases, queue workers, ngrok tunnels, and so on. You describe each process in .stacksmith.yml. See the docs for the format.

Yes. Stacksmith runs everything locally and never uploads your project files, code, or logs. The optional AI diagnosis uses Apple's on-device models, so nothing leaves your Mac, and analytics are off by default. See the Privacy Policy.

Yes, for project-scoped development secrets. Save them from the key button in the project toolbar or from Project > Manage Secrets..., then reference them in .stacksmith.yml with ${secret.NAME}. Stacksmith stores the values in the macOS Keychain and only shows the saved names in the app.

Use ${secret.NAME} for sensitive values that should stay out of files. Use ${dotenv.NAME} for local development settings that already live in .env. Use ${env.NAME} only when the value is intentionally supplied to the Stacksmith app process, because it reads from Stacksmith's own parent environment.

Usually no. Stacksmith reads .env from the project root by default when it exists. Add environment.dotenv.files only when you want custom or multiple files, such as reading .env first and letting .env.local override it.

The component does not start. Stacksmith shows a non-sensitive error naming the missing reference, such as ${secret.DATABASE_URL}, but it does not reveal any resolved values.

No. Stacksmith keeps resolved values out of its configuration, snapshots, and app-managed logs, but a child process can still print its own environment. Treat launched processes the same way you would in a terminal and avoid commands that echo secrets.

Yes. Stacksmith bundles an MCP server, and there is an installable agent skill for Claude Code and Codex so an assistant can author your .stacksmith.yml and start, stop, and inspect components.

macOS 26 or later on Apple silicon. The app is Developer ID signed and notarized by Apple.

The app itself is not open source, but releases and public issue tracking live on GitHub.