FULL deployment profile¶

Nexus's full profile is the all-feature shared hub for a team. The shared/demo preset stack provisions PostgreSQL + Dragonfly (plus the Nexus server), the complete brick set, and local inference. Keyword search uses BM25S; Zoekt is an optional, separately-run code-search backend the preset does not start (see the user guide, "What about Zoekt?"). Use this profile for a shared node that exposes the full CLI/RPC surface; use sandbox for per-agent clients that connect to it.

Three things called "profile" (read this first)¶

nexus up runs the FULL deployment profile because docker-compose.yml sets NEXUS_PROFILE=full. No nexus init preset is literally named full; the shared and demo presets both run FULL.

What you get¶

Running¶

Via the daemon directly (supported)¶

nexusd --profile full --host 0.0.0.0 --port 2026 \
  --data-dir ./nexus-data --auth-type static --api-key "$NEXUS_API_KEY"

nexusd --profile remote is rejected: a daemon cannot be a thin client of another daemon.

Via the managed stack (known issue — see below)¶

nexus init --preset shared
nexus up                 # ⚠ currently exits rc=1 (see note)
eval $(nexus env)
nexus status

Known issue (Bug B, tracked): nexus up --preset shared currently returns a non-zero exit code because the nexus up health gate waits on a zoekt service that the shared preset does not start. The hub itself boots and serves correctly (/health, /api/v2/features, gRPC all work) — only the nexus up wrapper's aggregate exit status is wrong. This is a pre-existing nexus up health-gate defect, out of this docs/test issue's scope, tracked in the #4132 design spec ("Bug B"). Until it is fixed, prefer the direct daemon path above; if you use the stack, the containers are healthy despite the rc=1 (verify with nexus status / a direct curl $URL/health).

Auth¶

• static: --api-key / NEXUS_API_KEY / NEXUS_API_KEY_FILE. Request without a key → 401; with key → 200.
• database: --auth-type database + --database-url (or POSTGRES_URL) → DatabaseAPIKeyAuth. Use for multi-user key issuance/revocation.

Remote client¶

from nexus.sdk import connect

nx = connect(config={"profile": "remote",
                     "url": "http://hub:2026",
                     "api_key": "..."})

Set NEXUS_GRPC_PORT if the server's gRPC port is non-default. The HTTP URL alone is not sufficient.

Correctness check you can run¶

The FULL contract is locked by tests/unit/core/test_full_profile.py. Run:

pytest tests/unit/core/test_full_profile.py -v

You can also verify a running hub's resolved contract directly:

nexus profile contract

It prints JSON with a _sources map marking each field's provenance:

• hub-authoritative (from the hub's /api/v2/features): deployment_profile, bricks, disabled_bricks, mode, version.
• client-inferred (NOT hub-authoritative — derived from the hub's profile name via this CLI's DeploymentProfile; may differ under CLI/server version skew): client_inferred_drivers.
• local/contextual: auth_mode reflects the local nexus.yaml only for the locally-managed stack; for an explicit remote target (--url / NEXUS_URL / global --profile) it is "unknown".
• invariant: grpc_required is always true (the remote SDK path requires gRPC, not just HTTP).

nexus profile contract --url <hub> --api-key <key> targets a remote hub; nexus --profile <name> profile contract uses a saved connection profile.

Benchmark guidance¶

Boot time and idle RSS are setup-path metrics, not CI gates; the FULL stack (PostgreSQL + Dragonfly + the Nexus server) targets multi-GB RSS and a 15–60 s boot. health / features / Ping are control-plane calls with sub-100 ms expectations on a warm hub. There is no steady-state data-plane hot path in the startup story.

Troubleshooting¶

• Remote SDK hangs / connection refused: gRPC port unreachable — set NEXUS_GRPC_PORT, confirm nexus status shows gRPC healthy.
• 401 from every call: static auth with no NEXUS_API_KEY, or database auth with no issued key.

Filesystem surface¶

FULL exposes the file API over two transports against the Python nexusd daemon (shared/demo presets):

1. HTTP RPC — POST /api/nfs/{method} (generic Call) and the typed POST /api/v2/files/{write,read,exists,batch-read,…} routes. This is the only wire the hub actually binds.
2. Kernel syscalls — in-process calls when you embed NexusFS.

The CLI (nexus cat/write/stat/...) currently constructs a gRPC client when invoked against a remote URL (nexus.connect(profile= "remote") → RPCTransport). Against shared/demo that wire isn't bound, so the CLI is local-stack-only on the hub presets — remote use of the CLI requires the nexusd-cluster federation binary (Rust), which IS the only thing that binds typed gRPC (Ping/Read/Write/Delete/BatchRead — see rust/transport/src/grpc.rs). The standalone hub maps the gRPC port for compose compatibility but does not bind it (commit 607ae89b5 "delete legacy Python gRPC bridge"); dialing it returns "Connection reset by peer". The HTTP RPC POST /api/nfs/{method} is marked deprecated (sunset 2026-06-25, Issue #1133) for the day the hub adds gRPC; until then it remains the canonical wire for script/CLI HTTP clients.

Semantics that matter:

• read_range(start, end) is start-inclusive, end-exclusive. End past EOF returns the available bytes (bounded, not an error).
• rename_batch / delete_batch / write_batch are per-item independent (not atomic) — the result maps each literal path to {success, ...} or {success, error}.
• content_id is stable across write/stat/read for identical bytes; use the CAS helpers in nexus.lib.occ to compose If-Match writes (a stale content_id is rejected).
• Admin ops (backfill_directory_index, flush_write_observer) require admin; non-admin callers are refused server-side.
• macOS gRPC clients: nexus.connect(profile="remote", url="http://localhost:...") resolves localhost to 127.0.0.1 automatically. Docker Desktop / OrbStack only bind IPv4 (0.0.0.0) on host port maps; without this pin, macOS happy-eyeballs to ::1 first and gets "Socket closed".
• Stream commands (cat --stream, write --stream) honor Unix SIGPIPE = SIG_DFL — piping into head, tee, or any reader that closes early exits cleanly (status 141), no traceback.

CLI ↔ RPC mapping (verified by tests/unit/cli/test_fs_parity.py):

Verification status (PR #4173) — maps to the 8 spec correctness assertions:

Additional coverage:

| Typed gRPC Ping/Read/Write/Delete/BatchRead (real cluster) | ✅ verified | tests/integration/test_typed_grpc_cluster.py::test_typed_grpc_ping_write_read_delete_batch boots nexus-cluster --no-tls, connects via NexusVFSServiceStub, asserts byte-identity + content_id stability + Delete success + BatchRead per-item shape |

Out of #4133 scope (covered by sibling suites):

Benchmark guidance (dev-laptop medians on Apple Silicon, in-process kernel; from tests/benchmarks/bench_read_write_overhead.py, --benchmark-min-rounds=20). Numbers are reference points, not CI gates: