---
title: Quickstart
description: "Clone matrix-core, build the nine Go modules, compile your first intent, drive an end-to-end walk, and run the per-user daemon."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

This guide takes you from a fresh clone to a running daemon. Matrix is a polyglot monorepo of independently buildable Go modules plus MCP tool servers.

## Prerequisites

<Columns cols={2}>
  <Card title="Go 1.22+" icon="golang">
    The toolchain is pinned across every module.
  </Card>
  <Card title="GNU make 4.x" icon="hammer">
    The root `Makefile` drives all module builds and tests.
  </Card>
  <Card title="Node 20+, npx, Python 3.11+, uv" icon="boxes-stacked">
    Required for the MCP-server-driven flows (filesystem, fetch, git, browser, …).
  </Card>
  <Card title="Docker + buildx" icon="docker">
    Only needed to build the per-user daemon image.
  </Card>
</Columns>

## 1. Clone and build

```bash
git clone https://github.com/paxlabs-inc/matrix-core.git
cd matrix-core
make build      # compile all nine Go modules
make install    # drop the runnable CLIs into ./bin
make test       # go test -count=1 -race ./... per module
make ci         # gofmt-check + vet + tests (mirrors GitHub Actions)
```

<Tip>
Need `golangci-lint` locally? Run `make lint-install` (pinned to v1.61.0) then `make lint`.
</Tip>

## 2. Configure secrets

```bash
cp .env.example .env
# FIREWORKS_API_KEY / TOGETHER_API_KEY — required for any non-dry-run compile
# MATRIX_DAEMON_TOKEN — set if running the daemon with auth
```

`.env` is gitignored; `.env.example` documents every variable Matrix reads.

## 3. Compile your first intent

```bash
./bin/mclc compile \
  -skill skills/writing-plans/SKILL.mtx \
  -prose "Build a deployment pipeline for my Node.js app" \
  -verb  build
```

With `FIREWORKS_API_KEY` set the compiler emits a real Intent Frame (verb, typed objects, blocking unknowns). Without keys it falls back to dry-run mode and prints the fully-interpolated prompt structure.

## 4. Drive an end-to-end walk

```bash
./bin/mcl-execute walk \
  -prose       "Summarise the README and write it to /tmp/summary.md" \
  -manifest    agents/default.json \
  -cortex-root ./runs/dev-cortex \
  -skills-root ./skills
```

This loads the agent manifest, spawns the MCP servers it declares, compiles the prose into an Intent + PlanTree, walks the plan, journals every step as a cortex Event, and ends with `cortex.Attest` writing `KindAttest` + `KindLearnWeights` atomically.

## 5. Run the daemon

<Steps>
  <Step title="Start the per-user daemon">
    ```bash
    ./bin/mcl-execute daemon \
      -addr        :8080 \
      -cortex-root ./runs/dev-cortex \
      -manifest    agents/default.json \
      -skills-root ./skills
    ```
  </Step>
  <Step title="Talk to it">
    The daemon exposes an HTTP + SSE surface. The most common routes:

    | Method | Path | Purpose |
    | --- | --- | --- |
    | GET | `/healthz` | Liveness + SSE broker stats |
    | POST | `/chat` | Converse with the agent (Neo front door) |
    | GET | `/events` | Server-Sent Events tail (transcript) |
    | POST | `/messages` | Submit a prose message (rigorous rail) |
    | GET | `/intents/{id}` | Read the intent envelope chain by ID |
    | GET | `/me` | Per-user settings + identity |
    | POST | `/shutdown` | Graceful drain |
  </Step>
</Steps>

<Note>
The full route reference, request/response shapes, and per-service APIs live under [API Reference](/api-reference/daemon).
</Note>

## What's next

<Columns cols={2}>
  <Card title="Core concepts" icon="lightbulb" href="/concepts">
    The mental model behind intents, plans, cortex, and replay.
  </Card>
  <Card title="Architecture" icon="sitemap" href="/developer/architecture">
    Module boundaries, cross-cutting flows, and invariants.
  </Card>
</Columns>