# How to Install Macro Inc. Locally: A Complete Setup Guide for This Rust Micro-Service Workspace

> Install Macro Inc. locally by cloning the repo and entering the Nix shell. Easily run the full Docker-based stack on your machine with a simple command. Get started today!

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-20

---

**To install Macro Inc. locally, clone the repository, enter the Nix development shell with `nix develop`, then run `just run_local --no-doppler` to start the full Docker-based stack on your machine.**

Macro Inc. is a Rust-based, micro-service workspace that unifies email, chat, documents, tasks, AI agents, and CRM functionality into a single team operating system. Installing Macro Inc. locally requires emulating its production architecture—dozens of independent services communicating via HTTP APIs, queues, and event streaming. This guide walks through the exact steps to get a working development environment using the repository's built-in tooling and stubbed configuration.

## Prerequisites for Installing Macro Inc.

Before you can install Macro Inc. locally, you need two core tools on your system:

- **Nix** — The package manager that supplies the entire development toolchain
- **Docker** — With Compose v2 enabled for container orchestration

Nix handles everything else automatically: the `just` task runner, Cargo, the Rust toolchain, Bun runtime, `sqlx` CLI, and `cargo-zigbuild`. This eliminates version conflicts and ensures every contributor uses identical tooling, as defined in [`nix/tauri-dev-shells.nix`](https://github.com/macro-inc/macro/blob/main/nix/tauri-dev-shells.nix).

Verify Docker is running and accessible before proceeding. The repository includes a diagnostic command you can run after cloning.

## Step-by-Step Local Installation

### 1. Clone the Repository

```bash
git clone https://github.com/macro-inc/macro.git
cd macro

```

### 2. Enter the Nix Development Shell

```bash
nix develop

```

This drops you into a fully provisioned shell with all dependencies pre-configured. If you encounter errors, enable Nix's experimental features as documented in the repository README.

### 3. Verify Your Setup

Run the health check to catch port conflicts or missing tools before starting services:

```bash
just doctor-local

```

This validates Docker accessibility, toolchain availability, and required port availability, reporting any blocking issues immediately.

### 4. Start the Local Stack

Launch the complete environment with one command:

```bash
just run_local --no-doppler

```

The `--no-doppler` flag disables the production secrets manager (Doppler) and uses stubbed credentials baked into the codebase. The command executes a sequence defined in the root [`justfile`](https://github.com/macro-inc/macro/blob/main/justfile):

1. Builds all Rust service binaries
2. Launches Docker Compose with PostgreSQL, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth
3. Starts a reverse proxy
4. Prints the web UI URL (default: `http://localhost:3000/app`)

The stack runs attached to your terminal. While attached, press **`r`** to rebuild changed services or **`q`** to shut down cleanly. Always use **`q`** instead of closing the terminal—this ensures containers and volumes are removed properly.

### 5. Seed Sample Data (Recommended)

A fresh stack contains no users or content. Populate it with realistic test data:

```bash
just seed-scenario apply --file seed/scenarios/team-perms.json

```

This creates personas, teams, channels, documents, tasks, and emails based on the fixture defined in [[`seed/scenarios/team-perms.json`](https://github.com/macro-inc/macro/blob/main/seed/scenarios/team-perms.json)](https://github.com/macro-inc/macro/blob/main/seed/scenarios/team-perms.json). After seeding completes, you'll receive one-time login links like `http://alice.localhost:3000/app/login?...`—open these in separate browser tabs to interact as multiple users simultaneously.

## Understanding the Local Stack Architecture

When you install Macro Inc. locally, you're running a miniature version of its production architecture. Per the [[`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/CLAUDE.md)](https://github.com/macro-inc/macro/blob/main/CLAUDE.md) architecture overview, the stack includes these containerized components:

| Component | Purpose |
|-----------|---------|
| **PostgreSQL** | Primary relational database (MacroDB) for documents, users, tasks, messages |
| **Redis** | Caching layer and session management |
| **LocalStack** | AWS service emulation (S3, DynamoDB, and other cloud APIs) |
| **OpenSearch** | Full-text search index for document and message content |
| **Kafka** | Event streaming for asynchronous processing between services |
| **FusionAuth** | Authentication service with password-less login support |

This mirrors the production data storage model described in the repository: PostgreSQL for core data, S3 for files, OpenSearch for search, and Redis for caching.

## Running Multiple Isolated Instances

To install Macro Inc. locally for multiple parallel environments—useful for testing different feature branches or configurations—use named instances with deterministic port ranges:

```bash
just run_local --instance agent-a --no-doppler
just run_local --instance agent-b --no-doppler

```

Each instance receives its own Docker Compose project, isolated networks, and volumes. Port allocation is deterministic based on the instance name, preventing collisions.

For explicit port control:

```bash
just run_local --instance test --port-base 31000 --no-doppler

```

## Enabling Real Third-Party Integrations

The default stubbed configuration disables external services like Google OAuth and Stripe. To install Macro Inc. locally with real integrations, create a `local.env` file:

```bash
cat > local.env <<EOF
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET_KEY=your-secret
STRIPE_SECRET_KEY=sk_test_...
EOF

```

Then pass it to the startup command:

```bash
just run_local --no-doppler --env-file ./local.env

```

Only specify the integrations you need—the stubbed configuration supplies all internal values automatically.

## Key Configuration Files

These files govern how Macro Inc. builds and runs locally:

| File | Location | Purpose |
|------|----------|---------|
| `justfile` | Repository root | Task definitions: `run_local`, `doctor-local`, `seed-scenario` |
| [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) | Repository root | Workspace declaration listing all service crates |
| [`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) | `docs/` | Complete local development guide and troubleshooting |
| [`CLAUDE.md`](https://github.com/macro-inc/macro/blob/main/CLAUDE.md) | Repository root | Architecture overview, service boundaries, development workflows |
| `nix/tauri-dev-shells.nix` | `nix/` | Nix derivation for reproducible development environment |
| [`seed/scenarios/team-perms.json`](https://github.com/macro-inc/macro/blob/main/seed/scenarios/team-perms.json) | `seed/scenarios/` | Sample data fixture for realistic demo environments |

## Summary

- **Install Nix and Docker** as the only host prerequisites—Nix provides everything else via `nix develop`
- **Use `just run_local --no-doppler`** to start the complete stack with stubbed credentials
- **Run `just doctor-local` first** to validate your environment before starting services
- **Press `q` to shut down cleanly** and avoid orphaned containers
- **Seed data with `just seed-scenario`** to create test users and content immediately
- **Create named instances** with `--instance` for parallel isolated environments
- **Add `local.env` with `--env-file`** to enable real third-party integrations when needed

## Frequently Asked Questions

### What operating systems support local installation of Macro Inc.?

Any system that runs Nix and Docker works. The Nix development shell abstracts all toolchain dependencies, so Linux, macOS (Intel and Apple Silicon), and WSL2 on Windows all function identically once those two prerequisites are installed.

### Why does Macro Inc. require so many services for local development?

Macro Inc.'s architecture splits functionality into dozens of micro-services that communicate via HTTP APIs, SQS queues, Redis, and Lambda functions. The local stack replicates this with PostgreSQL for data, Redis for caching, LocalStack for AWS emulation, OpenSearch for search, Kafka for events, and FusionAuth for authentication—enabling realistic development without cloud dependencies.

### Can I develop on Macro Inc. without using Nix?

Nix is the officially supported and documented path. While technically possible to install the Rust toolchain, Bun, `just`, `sqlx`, and `cargo-zigbuild` manually, the [`nix/tauri-dev-shells.nix`](https://github.com/macro-inc/macro/blob/main/nix/tauri-dev-shells.nix) file ensures version compatibility that manual installation cannot guarantee. The repository's documentation assumes Nix usage throughout.

### How do I reset my local database and start fresh?

Stop the stack with `q`, then remove Docker volumes with `docker compose down -v` (or `docker compose -p <instance-name> down -v` for named instances). Restart with `just run_local --no-doppler` and optionally re-seed with `just seed-scenario apply --file seed/scenarios/team-perms.json`.