Nomos

Secure every action your AI agents take.

Nomos lets developers and teams safely use Claude Code, Cursor, Codex, and MCP agents without giving them uncontrolled access to files, shell, GitHub, cloud APIs, secrets, or production systems.

It sits between the agent and real systems and enforces one decision at the execution boundary: ALLOW, DENY, or REQUIRE_APPROVAL.

Nomos can:

• block secret reads (.env, credentials, key material)
• deny dangerous shell commands (rm -rf, terraform destroy, kubectl delete, git push)
• approval-gate GitHub, Kubernetes, Terraform, and HTTP actions
• redact sensitive outputs before they reach the agent, logs, or audit sinks
• scan upstream MCP responses for prompt-injection patterns
• broker short-lived credentials so agents never hold raw secrets
• record replayable, hash-chained audit traces

Nomos is agent-agnostic and model-agnostic. It does not constrain reasoning. It governs execution authority, resource usage, and side effects.

What Gets Blocked By Default

Examples of actions Nomos can block or approval-gate with starter policy bundles:

• read .env
• read ~/.ssh/id_rsa
• print authorization headers
• run rm -rf
• run terraform destroy
• run kubectl delete
• run git push origin main
• call unknown external hosts
• mutate production resources without approval

Each of these is shaped by your own policies and configs — these are starter rules, not built-in enterprise packs.

Install

Homebrew (macOS)

brew install safe-agentic-world/nomos/nomos

Scoop (Windows)

scoop bucket add nomos https://github.com/safe-agentic-world/scoop-nomos
scoop install nomos

Build From Source (Go)

go install github.com/safe-agentic-world/nomos/cmd/nomos@latest

Shell Installer (macOS And Linux)

curl -fsSL https://raw.githubusercontent.com/safe-agentic-world/nomos/main/install.sh | sh

Try In 60 Seconds

After installing nomos, clone this repo to get the starter fixtures and run two policy tests — no Claude, Codex, or MCP setup needed:

git clone https://github.com/safe-agentic-world/nomos.git
cd nomos

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

Expected output:

allow-readme.json  -> ALLOW   (matched: safe-read-workspace)
deny-env.json      -> DENY    (matched: safe-deny-root-env, safe-deny-nested-env)

Both runs print the same policy_bundle_hash, so you can verify the decision came from the bundle you expected.

Try It With Claude Code

Use the demo repo and Claude Code to see Nomos deny a sensitive file read:

git clone https://github.com/safe-agentic-world/demo-langchain-nomos.git
cd demo-langchain-nomos
claude mcp add --transport stdio --scope local nomos-demo -- nomos mcp -c "nomos\config.claude-demo.json"
claude mcp list

You should see nomos-demo.

Then open Claude in the repo:

claude

And ask:

Use Nomos to read .env from the repo root.

Nomos should deny the action.

You can also prove:

1. a normal read succeeds through Nomos
2. git status is allowed
3. git push is denied

Try It With Codex

git clone https://github.com/safe-agentic-world/demo-langchain-nomos.git
cd demo-langchain-nomos
codex mcp add nomos-demo -- nomos mcp -c "nomos\config.demo.json"
codex mcp list

You should see nomos-demo.

Then open codex in the repo:

codex

And ask:

Use Nomos to read .env from the repo root.

Nomos should deny the action.

Do I Have To Tell The Agent To Use Nomos?

For local demos, you can still prompt "use Nomos". For real workflows, make Nomos the default execution boundary so the agent naturally sees governed tools first.

Use the launcher:

nomos run codex --dry-run --print-config
nomos run claude --profile safe-dev

The launcher detects the workspace, selects a policy profile, generates an MCP client config, and exposes friendly governed tools:

• read_file -> fs.read
• write_file -> fs.write
• apply_patch -> repo.apply_patch
• run_command -> process.exec
• http_request -> net.http_request

Do not register raw filesystem, shell, GitHub, Kubernetes, or other upstream MCP servers directly beside Nomos when Nomos should govern those actions. If native tools or raw MCP servers remain enabled, Nomos warns because those are possible bypass paths.

If your agent asks you to approve a native shell, file, HTTP, patch, or git action after Nomos denied or approval-gated it, that approval bypasses Nomos. Use nomos approvals ..., change policy, or stop the session.

Local laptop mode is best-effort. Stronger guarantees require controlled runtimes such as containers, CI, or remote workspaces.

See docs/agent-launcher.md.

Architecture In One Picture

flowchart LR
  A[Agent or MCP Client] --> B[HTTP or MCP Boundary]
  subgraph N[Nomos Execution Boundary]
    B --> C[Verify Identity]
    C --> D[Validate and Normalize Action]
    D --> E[Evaluate Policy]
    E --> F{Decision}
    F -->|ALLOW| G[Execute]
    F -->|REQUIRE_APPROVAL| H[Create Approval]
    F -->|DENY| I[Return Denial]
    G --> J[Redact and Cap Output]
    H --> I
    J --> K[Return Response]
    E -.-> L[Audit and Telemetry]
    G -.-> L
    H -.-> L
    I -.-> L
  end

Loading

The flow is simple:

1. an agent tries to do something real
2. Nomos verifies who is asking and normalizes the action
3. policy returns ALLOW, DENY, or REQUIRE_APPROVAL
4. only allowed actions execute on the mediated path
5. outputs are redacted before they come back
6. audit evidence is recorded for the whole path

That same model works whether the agent reaches Nomos through MCP or HTTP.

Serve

MCP

Use Nomos as an MCP server when your agent client already knows how to use MCP tools.

Good fit for:

• Claude Code
• Codex-style tool clients
• OpenClaw-style MCP-connected agents

Nomos exposes governed tools such as:

• nomos_fs_read
• nomos_fs_write
• nomos_apply_patch
• nomos_exec
• nomos_http_request

Nomos advertises MCP tool names using a conservative cross-vendor-safe character set. Canonical policy and audit identity remains unchanged behind the tool surface, and legacy dotted tool names are still accepted for backward compatibility.

For MCP file tools, Nomos accepts canonical resources like file://workspace/README.md and now also accepts common workspace-relative shorthands like README.md or ./README.md, which are adapted safely into the canonical internal form.

See:

• docs/agent-launcher.md
• docs/integration-kit.md
• docs/upstream-mcp-gateway.md
• docs/mcp-compatibility.md

Nomos can also run as an additive MCP governance gateway in front of configured upstream MCP servers. In that mode, downstream agents keep their MCP client architecture while Nomos governs forwarded tools as mcp.call actions. Upstream stdio compatibility is hardened for real newline-delimited JSON MCP servers, with framed upstream responses still accepted for compatibility.

HTTP

Use Nomos as an HTTP gateway when your agent runtime already has its own tool loop or backend service.

Good fit for:

• app-integrated agents
• custom tool runtimes
• CI or service-side control planes

Nomos exposes:

• POST /action
• POST /run
• POST /approvals/decide
• POST /explain
• GET /ui/

with bearer principal auth and agent HMAC signing.

See:

• docs/deployment.md
• docs/http-sdk.md
• docs/http-integration-kit.md
• docs/integration-patterns.md
• docs/custom-actions.md
• docs/quickstart.md
• docs/operator-ui.md

Key Features

• nomos doctor: deterministic preflight checks before agents connect
• nomos policy test: test a specific action against a policy bundle without executing it
• nomos policy explain: understand why an action was allowed, denied, or approval-gated
• MCP server mode: expose governed tools to MCP-compatible agent clients
• HTTP gateway mode: mediate actions from custom tool loops and app backends
• approval workflow: route sensitive actions into narrow, fingerprint-bound approvals
• operator UI: inspect readiness, pending approvals, action detail, trace timelines, and explain-only policy results over existing gateway state
• audit trail: record governed actions with stable policy and identity context
• redaction: strip sensitive output before it reaches the agent, logs, or audit sinks
• capability contract: surface what is immediately allowed, approval-gated, or unavailable
• multi-bundle policy loading: compose layered policy packs with deterministic merge behavior

What Nomos Governs

Nomos can govern actions such as:

• fs.read
• fs.write
• repo.apply_patch
• process.exec
• net.http_request
• secrets.checkout

Policy returns:

• ALLOW
• DENY
• REQUIRE_APPROVAL

Around those actions, Nomos adds:

• deterministic deny-wins policy evaluation
• approval binding to action fingerprints
• output caps and redaction
• audit events and telemetry hooks
• least-privilege identity and credential mediation

See:

• docs/policy-language.md
• docs/obligations.md
• docs/approvals.md
• docs/audit-schema.md

Guarantees And Deployment Modes

Nomos makes different claims depending on where it is deployed. These are runtime-derived assurance levels, not marketing labels.

Deployment mode	Guarantee	Meaning
controlled CI / k8s with strong controls	STRONG	governed side effects can be enforced at the runtime boundary
partially hardened controlled runtime	GUARDED	Nomos strongly mediates the path it sees, but operator/runtime gaps may remain
local unmanaged or remote-dev style usage	BEST_EFFORT	Nomos governs routed actions, but cannot guarantee full mediation

This matters because a local demo proves Nomos can govern the path it sees, while a hardened deployment proves much stronger control over what the agent can actually do.

See:

• docs/assurance-levels.md
• docs/strong-guarantee-deployment.md
• docs/reference-architecture.md

Starter Bundles And Examples

These are starter examples, not built-in enterprise policy packs.

Configs:

• examples/quickstart/config.quickstart.json
• examples/configs/config.example.json
• examples/configs/config.layered.example.json

Starter bundles:

• examples/policies/safe.yaml
• examples/policies/safe.json
• examples/policies/purchase.yaml
• examples/policies/all-fields.example.yaml

Security Model

Nomos is built around a few hard rules:

• no trust in agent-supplied principal or environment claims
• no raw enterprise credentials returned directly to agents
• credentials are brokered as short-lived lease IDs
• redaction happens before output leaves Nomos
• policy and config errors fail closed
• local unmanaged mediation is explicitly weaker than controlled-runtime mediation

See:

• docs/threat-model.md
• docs/redaction-guarantees.md
• docs/egress-and-identity.md
• docs/owasp-agentic-mapping.md

Why Not Just Use OPA, Vault, Or Sandboxes?

Those tools each solve a piece of the problem. Nomos puts them together at the moment an agent tries to do something real.

Tool	What it solves	What Nomos adds
OPA	policy evaluation	agent action normalization, approvals, execution mediation, audit replay
Vault	secret storage	short-lived credential brokering without exposing raw secrets to agents
sandbox runtimes	process isolation	business policy, approvals, redaction, audit, MCP/HTTP integration
MCP servers	tool exposure	least-privilege governance, deny/approval decisions, output controls

Testing

Quick validation:

go test ./...
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

See:

• TESTING.md
• docs/local-validation-plan.md

More Use Cases

Coding Agents

• allow git status
• deny git push
• deny .env reads
• allow bounded patch application

Customer Operations Agents

• allow order lookup
• require approval for refunds or credits
• deny bulk customer export

CI Agents

• allow test execution
• deny release publishing outside policy
• require approval for production-impacting actions

See:

• docs/use-cases.md

Docs Map

Start here:

• docs/quickstart.md
• docs/agent-launcher.md
• docs/integration-kit.md
• docs/local-validation-plan.md
• examples/README.md

Policy and behavior:

• docs/policy-language.md
• docs/policy-explain.md
• docs/approvals.md
• docs/obligations.md
• docs/custom-actions.md

MCP, HTTP, and SDKs:

• docs/mcp-compatibility.md
• docs/upstream-mcp-gateway.md
• docs/http-sdk.md
• docs/http-integration-kit.md
• docs/integration-patterns.md

Architecture, operations, and guarantees:

• docs/reference-architecture.md
• docs/assurance-levels.md
• docs/threat-model.md
• docs/audit-schema.md
• docs/observability.md
• docs/operator-ui.md

Release and decisions:

• docs/release-verification.md
• docs/launch-checklist.md
• docs/decisions/profile-and-launcher-artifacts.md
• docs/owasp-agentic-mapping.md

Project Status

Nomos is still pre-v1.0.0. The core model is usable today, but interfaces, policy surface, and integrations may still evolve before a stable v1.

Project governance:

• SECURITY.md
• CODE_OF_CONDUCT.md
• CHANGELOG.md
• LICENSE

Community And Contribution

• open an issue for bugs, gaps, integration requests, or deployment questions.
• Please do not open public issues for potential vulnerabilities, and report privately to maintainers.
• browse good first issue if you want a place to start
• read CONTRIBUTING.md if you want to help shape the project