# How to Run Macro Locally with Stubbed Secrets: Complete Setup Guide > Run Macro locally with stubbed secrets using the no-doppler flag for immediate development. Get started fast without needing external API keys. - Repository: [Macro/macro](https://github.com/macro-inc/macro) - Tags: how-to-guide - Published: 2026-08-21 --- **Running Macro locally requires only Nix and uses the `--no-doppler` flag to launch a fully stubbed development stack with placeholder values for all secrets, enabling immediate local development without external API keys.** The Macro collaboration platform (`macro-inc/macro`) ships with a deterministic local development environment that eliminates the need for production credentials. By leveraging the stubbed secrets system, developers can spin up the entire service architecture—including Postgres, Redis, OpenSearch, Kafka, and FusionAuth—using only code-defined placeholder configuration values. This approach allows you to **run macro locally with stubbed secrets** while maintaining full platform functionality for authentication, document storage, and real-time collaboration. ## Prerequisites: Install Nix Macro requires **Nix** as the sole host-level dependency. Nix provides the Docker CLI, Docker Compose, and all Rust toolchains required for the build without polluting your system. Install Nix using the official installer: ```bash curl -L https://nixos.org/nix/install | sh ``` After installation, restart your shell or run `exec $SHELL` to ensure the Nix daemon is available. ## Enter the Nix Development Shell Navigate to the repository root and enter the development shell. This command makes `just`, Cargo, Bun, `sqlx`, and Docker tooling available automatically. ```bash git clone https://github.com/macro-inc/macro.git cd macro nix develop ``` Inside this shell, you have access to all build tools defined in the project's Nix flake, ensuring reproducible builds across all developer machines. ## Start the Stack with Stubbed Secrets To launch the local stack without Doppler or real API keys, use the `--no-doppler` flag. According to the `justfile`, this command generates Docker Compose configurations in `infra/local/generated/` and starts all services using stubbed values. ```bash just run_local --no-doppler ``` The `--no-doppler` flag instructs Macro to use **code-defined configuration** with deterministic stub values for every secret. Internal plumbing keys such as `REDIS_HOST`, `MACRO_DB_URL`, and `OPENSEARCH_USERNAME` are pre-configured to local-compatible defaults in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml), requiring no manual editing. Third-party integration keys for Google, GitHub, Stripe, and CloudFront remain stubbed, meaning those specific flows are gracefully disabled while the core platform—authentication, document storage, email handling, and search—functions out of the box. ## Override Secrets for Real Integrations While the stubbed configuration supports most development workflows, you may need to test live third-party integrations. Create a `local.env` file containing real API keys, then pass it using the `--env-file` flag to override specific stubs while keeping others placeholdered. Create `local.env`: ```bash STRIPE_SECRET_KEY=sk_live_XXXXXXXXXXXXXXXX STRIPE_PRICE_ID=price_XXXXXXXXXXXXXXXX ``` Restart the stack with your overrides: ```bash just run_local --no-doppler --env-file ./local.env ``` Values provided in `--env-file` take precedence over stub defaults, enabling selective integration testing without exposing unnecessary secrets. ## Verify the Local Environment Once `just run_local` completes, the terminal displays the frontend URL (typically `http://localhost:3000/app/`) and backend service endpoints. Authentication uses a passwordless flow: enter any email address on the login screen, and the one-time code appears instantly in **Mailpit** at `http://localhost:8025`. This local email catcher eliminates the need for real SMTP credentials. To populate the environment with realistic demo data, run: ```bash just seed-scenario apply --file seed/scenarios/team-perms.json ``` This command creates sample users, teams, channels, documents, and tasks as defined in the scenario file. ## Key Files in the Local Stack Understanding these source files helps debug the stubbed environment: - **[`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md)** — Comprehensive guide on launch procedures, stub behavior, and integration overrides. - **`justfile`** — Defines the `run_local`, `seed-scenario`, and `doctor-local` commands orchestrating the workflow. - **[`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml)** — Core service definitions for Postgres, Redis, LocalStack, OpenSearch, and Kafka used by the local stack. - **[`seed/scenarios/team-perms.json`](https://github.com/macro-inc/macro/blob/main/seed/scenarios/team-perms.json)** — Sample dataset creating users, teams, channels, documents, tasks, and permissions for demonstration purposes. ## Summary - **Nix** is the only host dependency required to run Macro locally, providing Docker and Rust toolchains through `nix develop`. - The **`just run_local --no-doppler`** command launches a fully functional stack using stubbed secrets for all internal and third-party services. - **Stubbed secrets** use deterministic placeholder values pre-configured in the codebase, eliminating manual `.env` setup. - To test live integrations, create a **`local.env`** file and pass it via **`--env-file ./local.env`** to override specific stubs. - Local authentication codes appear in **Mailpit** at `localhost:8025`, and sample data can be loaded via `just seed-scenario`. ## Frequently Asked Questions ### What services run in the stubbed local stack? The stack launches Postgres, Redis, LocalStack (for S3-compatible storage), OpenSearch, Kafka, and FusionAuth inside Docker containers. According to [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml), these services communicate over a generated local network with pre-configured credentials that require no manual setup. ### Can I test third-party integrations like Stripe or Google Login locally? Yes. While the default stubbed configuration disables these flows, you can enable them by creating a `local.env` file with real API keys and launching with `just run_local --no-doppler --env-file ./local.env`. This overrides only the specified secrets while keeping all other services stubbed. ### How do I view emails sent by the local stack? All outbound emails from the local environment are captured by **Mailpit**, accessible at `http://localhost:8025`. This includes passwordless login codes, invitation emails, and notification digests, eliminating the need for external SMTP configuration. ### Is Doppler required for local development? No. The `--no-doppler` flag explicitly bypasses the Doppler secrets manager, instructing the application to load configuration from code-defined stubs. This allows offline development and CI/CD pipelines to run without Doppler access tokens.