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

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.

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

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

2. Enter the Nix Development Shell

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:

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:

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:

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:

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). 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) 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:

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:

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:

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:

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	Repository root	Workspace declaration listing all service crates
docs/RUNNING_LOCALLY.md	docs/	Complete local development guide and troubleshooting
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	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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}