> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelieo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# NSP Security Model: Auth, Rate Limits, and Action Safety
> A complete guide to NSP's layered security model — localhost binding, API key auth, rate limiting, and action reversibility safety contracts.
NSP is designed from the ground up as a local-first runtime substrate: the daemon binds exclusively to `127.0.0.1:7842` by default, so only processes running on the same machine can reach it. Within that boundary, NSP enforces three additional security layers — API key authentication, per-key rate limiting, and a tiered action safety gate — giving you fine-grained control over what agent code can read or change.
## The Three Security Layers
The daemon binds to `127.0.0.1` by default. No remote process can reach port 7842. CORS controls restrict which web origins may call the API.
Every request must carry a valid `X-Substrate-Key` header. Keys are stored as BLAKE3 hashes — the plaintext never touches disk.
Every action passes through a reversibility gate. `irreversible_write` actions require a `verify_expression`. Heuristically dangerous action names are blocked when no schema is available.
## Threat Model
NSP is designed for local agent use — the daemon and your agent code run on the same host. The table below maps each threat to the control that mitigates it.
| Threat | Mitigation |
| ------------------------------------------------- | --------------------------------------------------------- |
| Another local process calling the API | API key auth (`X-Substrate-Key` header) |
| Agent accidentally triggering destructive actions | Action safety gate + required `verify_expression` |
| Agent flooding the API with requests | Rate limiting — 100 state reads/s, 10 actions/s |
| Oversized request bodies hanging the daemon | 10 MB body limit enforced by the HTTP layer |
| Requests hanging indefinitely | 30 s standard timeout, 120 s for action calls |
| A web page calling the API via CORS | CORS policy — only explicitly allowed origins may connect |
| A leaked API key file | Keys stored as BLAKE3 hashes; plaintext is unrecoverable |
## What NSP Does Not Protect Against
NSP's security model assumes you control the machine the daemon runs on. The following scenarios are out of scope and require your own mitigations.
* **Root or admin processes** — a process with elevated privileges on the same host could read the API key from memory. Run the daemon as a low-privilege service account.
* **Remote network exposure** — never bind the daemon to `0.0.0.0` or expose port 7842 via a firewall rule or reverse proxy without additional authentication in front of it.
* **Supply chain attacks** — only install `axon-daemon` from the signed Nelieo platform binaries. Verify the SHA-256 checksum published in the release notes.
## Production Hardening Checklist
Open `axon.toml` and confirm authentication is required, then generate your first key.
```toml theme={null}
[auth]
require_key = true
keys_file = "C:\\ProgramData\\Nelieo\\axon_keys.json"
```
```bash theme={null}
axon-daemon.exe keygen --label "prod-agent-v1"
```
Check that `host` is set to the loopback address. Change it only if you are deploying behind a hardened reverse proxy.
```toml theme={null}
[server]
host = "127.0.0.1"
port = 7842
```
Disable the wildcard CORS setting and list only the origins your dashboard or dev tooling requires.
```toml theme={null}
[cors]
allow_all_origins = false
allowed_origins = ["http://localhost:3000"]
```
Tune action throughput to what your agent actually needs. Lower limits reduce blast radius if agent code misbehaves.
```toml theme={null}
[rate_limit]
enabled = true
state_per_second = 100
action_per_second = 5
```
Storing the registry on disk avoids a cold re-discovery on every daemon restart and gives you an audit trail of registered action schemas.
```toml theme={null}
[registry]
in_memory = false
db_path = "C:\\ProgramData\\Nelieo\\axon_registry.db"
```
Generate replacement keys before retiring old ones to avoid downtime.
```bash theme={null}
axon-daemon.exe keygen --label "prod-agent-v2"
```
Then disable the old key in `axon_keys.json` by setting `"enabled": false`. The daemon picks up the change within 5 seconds — no restart needed.
## Key Security Principles at a Glance
The daemon prints a loud warning every 60 seconds when `require_key = false`. Treat that warning as a blocker before any production deployment. Pass the key via the `NSP_API_KEY` environment variable rather than hardcoding it.
Every action schema declares a reversibility tier: `read`, `reversible_write`, or `irreversible_write`. Treat this classification as a binding safety contract. Read-only actions carry no confidence gate; irreversible actions require both a high confidence score (≥ 0.95) and a `verify_expression`.
A `verify_expression` is your post-action assertion. Specific expressions — for example `"inbox.sent_count == 15"` — give you stronger guarantees than vague ones like `"inbox.sent_count > 0"`. Always tailor the expression to the exact state change you expect.
Store keys in environment variables, a secrets manager, or a `.env` file excluded by `.gitignore`. The Python SDK reads `NSP_API_KEY` automatically if you do not pass `api_key` explicitly.
## Explore the Security Subsections
Generate keys with `axon-daemon.exe keygen`, set the `X-Substrate-Key` header, rotate keys, and handle 401 errors.
Default limits by endpoint, the 429 response format, exponential backoff, and axon.toml configuration.
The three reversibility tiers, confidence gating, verify expressions, and SDK enforcement.
Low-level daemon auth configuration, disabling auth for local dev, and environment variable overrides.
## Security Contact
Found a vulnerability? Email **[security@nelieo.com](mailto:security@nelieo.com)** with a detailed description. The team responds within 24 hours and follows responsible disclosure practices.