nomos CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Go 1.25+. Use Makefile targets or go directly.

• Build CLI: go build ./cmd/nomos (or make build)
• Release build with version metadata: make release-build (sets ldflags into internal/version)
• Full test suite: go test ./...
• Race suite (release gate): go test -race ./...
• Static checks: go vet ./... (aliased as make lint)
• Format: gofmt -w . (aliased as make fmt)
• Single package: go test ./internal/policy
• Single test: go test ./internal/policy -run TestName
• Focused MCP compat: go test ./internal/mcp
• Fast iteration set: go test ./cmd/nomos ./internal/policy ./internal/service ./internal/gateway ./internal/mcp

Smoke checks using the built binary (run after make build / go build):

• nomos doctor -c ./examples/quickstart/config.quickstart.json --format json
• nomos policy test --action ./examples/quickstart/actions/allow-readme.json --bundle ./examples/policies/safe.yaml
• nomos policy test --action ./examples/quickstart/actions/deny-env.json --bundle ./examples/policies/safe.yaml
• nomos policy explain ... for deny/approval diagnostics

CLI flag precedence is flag > env > fail. Relevant env vars: NOMOS_CONFIG, NOMOS_POLICY_BUNDLE, NOMOS_LOG_LEVEL. --config/-c and --policy-bundle/-p are resolved to absolute paths at parse time.

Architecture

Nomos is an execution firewall for AI agents: an agent-agnostic control plane that sits at the execution boundary and returns ALLOW / DENY / REQUIRE_APPROVAL on normalized actions. The same pipeline backs both the MCP server and HTTP gateway surfaces — understanding that pipeline is the big picture.

Request pipeline (same shape whether the caller is MCP or HTTP):

1. Boundary (internal/mcp or internal/gateway) accepts the request. Identity is never read from the request body — it is injected from config and verified via bearer/HMAC/OIDC. The MCP path derives action_id/trace_id from the MCP request id (mcp_<id>) to stay deterministic.
2. Normalize (internal/normalize, internal/action) canonicalizes resources (e.g., file://workspace/..., url://host/path), rejects traversal (..), and yields a stable action fingerprint. Agent-supplied principal/environment claims are rejected.
3. Policy evaluation (internal/policy) is deny-wins and rule order is irrelevant. Bundles load from JSON or YAML; YAML is validated strictly (duplicate-key and unknown-field rejection) and policy_bundle_hash is always computed from canonical JSON of the typed bundle so equivalent inputs stay deterministic. Matching supports glob patterns and optional identity/risk filters.
4. Obligations: redaction patterns, output caps (output_max_bytes/output_max_lines), sandbox profile (sandbox_mode), approval scope. Sandbox selection is obligation-driven and fails closed when the configured profile is weaker than required.
5. Approvals (internal/approval) bind to exact action fingerprints by default; class-scoped approvals require explicit approval_scope_class obligation and are limited to action_type_resource.
6. Execute (internal/executor, internal/sandbox) runs only ALLOW decisions. repo.apply_patch is implemented as deterministic path + content replacement, not diff application. net.http_request maps normalized url:// to https://, enforces host allowlists, and denies redirects unless the matched policy sets http_redirects.
7. Credentials (internal/credentials) are brokered as short-lived lease IDs bound to (principal, agent, environment, trace_id). Raw secrets never return to the agent; only lease IDs surface in visibility.
8. Redact + cap (internal/redact) applies before any output leaves Nomos — to the agent, logs, and audit sinks. Per-rule caps are enforced post-redaction so policy caps cannot be bypassed by larger executor defaults.
9. Audit + telemetry (internal/audit, internal/telemetry): action.completed is the canonical replay-level AuditEvent v1 record. Hash chaining runs over canonicalized payloads with prev_event_hash attached for cross-platform-deterministic verification. Telemetry is additive (OTLP/HTTP) — audit remains the authoritative evidence surface.