Crux Daemon · 0. Internals and operation

This set documents how the Crux Daemon is built and how you run it. It is explanation and reference, not a tutorial. If you want to extend the daemon, you want a different set; if you want the route list, you want a third. Section 0.5 tells you which.

0.1 What the Crux Daemon is

corecruxd is a single Rust binary that stores an agent's memory on your own disk and serves it over three network protocols. It is one long-running process. It opens three TCP listeners, HTTP on 14800, MCP on 14801, gRPC on 4007, and keeps everything it knows in one directory on disk.

Four properties define it, and each is verifiable:

Property	Value	Where to check
Language and floor	Rust, MSRV `1.88.0`	Cargo.toml:47, rust-toolchain.toml:2
Memory safety	`unsafe_code = "forbid"` workspace-wide; there is no `unsafe` Rust in the workspace	Cargo.toml:115
Compute	CPU-only. No CUDA, no GPU code path, no `cuda` cargo feature anywhere in the repository	docs/adr/003-cpu-only-crux-daemon.md
Licence discipline	Apache-2.0 licence headers on 100% of `.rs` files	Cargo.toml:46

Those four are not marketing lines. unsafe_code = "forbid" is a compiler-enforced lint, not a policy document. The CPU-only claim is checkable with a grep. The licence-header claim is checkable with grep -rL "Licensed under" --include=*.rs crates/, which returns nothing.

0.2 The mental model

Draw it once and the rest of the set follows.

                     one process: corecruxd
   ┌───────────────────────────────────────────────────────────┐
   │                                                           │
   │   :14800  HTTP (axum)  ─┐                                 │
   │   :14801  MCP  (axum)  ─┼──►  AppState  ──►  stores       │
   │   :4007   gRPC (tonic) ─┘     (~90 fields)                │
   │                                                           │
   └───────────────────────────────┬───────────────────────────┘
                                   │
                                   ▼
                     <data_dir>/   one directory, all state
                       facts.jsonl        the memory
                       shards/            the event store
                       LOCK               one daemon per dir

Three things about that picture are load-bearing.

One process, not three services. The three listeners are three tokio tasks joined with tokio::try_join! (main.rs:1594). Any one of them failing takes the whole process down. There is no partial availability.

One directory, not a database. Everything the daemon knows lives under data_dir. The primary user-data file is a single append-only JSON-lines journal, facts.jsonl. Back that directory up and you have backed up the daemon. Delete facts.jsonl and the daemon starts clean, healthy, and empty, and will not tell you anything is missing. Chapter 6 is the map.

Configuration is environment variables. The daemon takes no runtime flags. corecruxd --data-dir /x starts normally and silently ignores the flag (main.rs:231). There are 393 environment variables and an optional YAML file covering 26 keys. Chapter 5 is the complete list.

0.3 The one thing that surprises everyone

The daemon refuses to start without CORECRUXD_AUTH_MODE. There is no default:

CORECRUXD_AUTH_MODE must be set explicitly; see config.example.env

That is one of 25 conditions that make the daemon exit non-zero before serving. Chapter 4 lists all 25 with the exact operator fix for each. If you are here because the daemon will not start, go there first.

0.4 What is real, and what is a skeleton

The Community Edition binary in this repository does not implement everything its own proto files declare. Two facts you need before you plan an integration:

The gRPC plane is inert. All 10 registered RPCs on port 4007 return unimplemented, including AppendBatch and ReadStream (grpc.rs:758). The port binds and answers; no RPC does anything. Use HTTP.
POST /v1/admin/append always returns the platform-upgrade response (append.rs:45), because the dataplane pool is hard-coded to None (main.rs:565). It is not a subscription problem. It is not enabled by any flag in this build.

All four optional cargo features are off by default, so a stock cargo build --release has no OpenTelemetry export, no WASM extension host, no ONNX embedder, and no /v1/gpu1/* or /v1/cloud/access-contract routes at all (Cargo.toml:10).

Chapter 16 publishes all eight blocker-severity defects found in a 2026-07-27 audit, each with its evidence and its workaround. Read it before you trust anything else here.

0.5 Which set covers what

Three documentation sets cover the daemon. They do not overlap.

Set	Covers	Where
This set, internals and operation	How the daemon is built, configured, started, laid out on disk, secured, observed and run in production	`/docs/daemon/*`
Developer guide, extending it	Integration packs, capabilities and grants, signing and trust, external tools, WASM extensions, connectors, Studio packs, the registry, the MCP surface, the security model, troubleshooting	/docs/extending/01-architecture and its 12 sibling chapters
API reference	Every HTTP route, every MCP tool, request and response shapes	The API reference set

If you are about to write code that calls the daemon, the developer guide and the API reference are your documents. If you are about to run the daemon, or debug why it will not run, this one is.

0.6 Router: who you are, which chapter

You are	Start at
Setting up a workspace so agents pick up your rules	2. The config wizard
Evaluating whether to run this at all	16. Known defects, then 1. Architecture
Trying to make it start	4. Startup and lifecycle §4.3, the 25 refusal conditions
Configuring a deployment	5. Configuration reference §5.1 first (the traps), then the tables
Planning backup or disaster recovery	6. The data directory §6.5, "delete this and the daemon breaks"
Wiring authentication	7. Auth and scopes
Handling errors in a client	8. Errors
Wiring Prometheus, logs or tracing	9. Observability
Deploying to Docker, Compose or Kubernetes	17. Operations
Reading or contributing to the source	3. The crate map
Debugging at 3am	9. Observability §9.6 (the readiness gates), then 17. Operations §17.6

0.7 The whole set

#	Chapter	Mode	What it gives you
1	Architecture	Explanation	One process, three planes, the bind rails, the crate map at a glance, how a request moves
2	The config wizard	How-to	Day-one setup: composing `CLAUDE.md` and `AGENTS.md` from versioned profile fragments, drift detection, CI
3	The crate map	Reference	All 28 workspace crates plus the 3 out-of-workspace shell crates
4	Startup and lifecycle	Reference	The 67-step boot sequence, the 25 refusal conditions, background tasks, shutdown
5	Configuration reference	Reference	All 393 environment variables, 26 YAML keys, 9 boolean dialects
6	The data directory	Reference	Every file, what writes it, what breaks if you delete it, what grows without bound
7	Auth and scopes	Reference	Four auth modes, every scope, how checks work, the shadow-mode default
8	Errors	Reference	The RFC 9457 body shape and roughly 40 real HTTP error codes
9	Observability	Reference	Logging, 142 metrics, tracing, the 9 readiness gates
10	The memory substrate	Reference	The two substrates, the fact record, private scoping, `as_of`, freshness, contradictions
11	Retrieval and token budgets	Reference	The two retrieval lanes, what is unwired, the default embedder, budgets and coverage
12	Sessions, cases and handoffs	Reference	Session state, the case store, and what a handoff package is and is not
13	Receipts and proof	Reference	CROWN receipts, signing, offline verification, and precisely what they do not prove
14	Identity and capability	Reference	Passports, revocation, RCX capability tokens
15	Coordination and cost	Reference	The coordination plane, punchcards, the cost lens, export and custody
16	Known defects	Reference	Verified blocker-severity defects, dated and evidenced
17	Operations	How-to	Deployment shapes, health, backup, upgrade, troubleshooting
18	Runtime code intelligence	Reference	What ran, joined to what it is; tenant scoping; the volume and age limits

Chapters 10 to 15 are produced from a separate audit of the memory, retrieval, session, receipt, identity and coordination subsystems.

0.8 How to read a claim in this set

Every sentence that names a file, function, flag, route, type or constant carries a link to the line of source that makes it true. The links point at main on the public repository. If a link does not say what this set says it says, this set is wrong, file it.

Where a capability is built but gated, the flag is named and its default state is stated. Where a surface exists with nothing behind it, that is said plainly rather than softened. Chapter 16 exists because a documentation set that hides its defects cannot be trusted about anything else.

Sources

Cargo.toml:2-30, the 28 workspace members
Cargo.toml:47, MSRV 1.88.0
Cargo.toml:115, unsafe_code = "forbid"
crates/corecruxd/src/config.rs:805, HTTP port default 14800
crates/corecruxd/src/config.rs:826, MCP port default 14801
crates/corecruxd/src/config.rs:816, gRPC port default 4007
crates/corecruxd/src/main.rs:304, the auth-mode startup abort
crates/corecruxd/src/main.rs:565, dataplane_pool = None
crates/corecruxd/Cargo.toml:10, default = []