<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->
# Nomos
**Stop agents from doing more than they should.** Nomos reviews each action an
agent proposes against that agent's own context: who it is and what it may
touch, the task it is working on, why it says it needs this step, what it
expects the step to change, and signed receipts of what it has already observed.
An action that is unwanted, overeager or unsupported by evidence is denied, with
guidance the agent can act on. An approved action receives a signed, single-use
**Writ of Execution**, and the executor that holds your tools' credentials runs
exactly what the Writ says and signs a receipt of what happened.
Keep your agent, its framework and its model. Nomos sits between the agent and
the tools it should not use unchecked.
**[Get started](docs/getting-started.md)** ·
**[Integrate your agent](docs/integrate-your-agent.md)** ·
**[How it works](docs/architecture.md)** ·
**[All documentation](docs/index.md)**
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/diagrams/request-lifecycle-dark.svg">
<img alt="One request through Nomos. The agent proposes an action with council_authorize, along with its task context. Nomos authenticates it, verifies attached receipts, checks permissions and OPA policy, has the chairman assess risk and set the threshold, and has the council judge whether the action fits the agent's task; a failure at any of these returns a denial with guidance. On approval Nomos signs a Writ, which the agent hands to the executor. The executor verifies the Writ, claims its nonce, applies local checks, runs the exact command against the protected tools, and signs a receipt that the agent can attach to its next request." src="docs/assets/diagrams/request-lifecycle.svg">
</picture>
## Why Nomos
Autonomy is what makes agents useful. It is also what lets them overreach. Many
unwanted agent actions are not attacks but an agent being too helpful: cleaning
up more than it was asked to, force-pushing to clear a conflict, restarting a
production service to make an error go away. The command alone often looks
legitimate. What makes it wrong is the context: what the agent was asked to do,
and what it actually knows.
- **It judges the action against the agent's context.** Reviewers deny a command
that does more than the stated task calls for, reaches outside the stated
target, understates its blast radius, or follows from pressure rather than
from the task.
- **It weighs what the agent has observed, not what it asserts.** Signed receipts
of earlier actions arrive as certified evidence. A state-changing action that
rests on an unchecked claim ("the table is empty", "nothing routes here") is
denied until the agent checks, and evidence that contradicts the request is a
denial.
- **Rules first, judgment for the rest.** Per-agent permission scopes and OPA
rules decide what you can write down: blocked paths, required justification,
absolute executable paths. The council decides what depends on context.
- **It runs exactly what was approved.** The Writ signs the command, working
directory, packaged files and target agent. The executor verifies it, enforces
its own local policy as a second layer, and accepts each Writ once.
- **It leaves evidence.** Executor results are signed, rejections included, and
decisions are recorded in a hash-linked ledger.
### The context Nomos reviews
| Context | Where it comes from | What reviewers ask |
|---|---|---|
| Identity, role, councils | The agent's account | May this agent ask at all, and does its role grant the scopes the action needs? |
| `description`, `context` | The agent: its task and what it has done so far | Does the command serve that task, and nothing more? |
| `target_resource`, `working_directory` | The agent | Does the command stay inside the stated target? |
| `justification`, `blast_radius` | The agent | Is the stated effect honest? Does a production change have a rollback? |
| `evidence` | The agent, as plain text | Treated as a claim, not an observation |
| `certified_evidence` | Signed executor receipts from the agent's earlier actions | Treated as observed fact; a contradiction is a denial |
Typical uses: keeping coding agents in Cursor, Windsurf or Copilot from
overreaching their task in the shell, gating agent-driven deployments,
migrations and infrastructure changes, letting autonomous agents request
privileged operations with proof of authorization, and testing how LLM reviewers
handle jailbreaks and obfuscated commands.
Nomos protects the actions routed through it. Your integration decides which
actions go through the adapter, and your deployment decides what the executor
can reach.
## How a request flows
1. **Decide (steps 1–7).** The agent calls `council_authorize` with the exact
command, the task it serves and why it needs it. Nomos checks identity, any attached receipts,
permissions and OPA policy; the chairman assesses risk and sets the approval
threshold; the voting members decide. A denial comes back with guidance the
agent can act on.
2. **Hand off.** On approval the response carries the signed Writ. Nomos never
runs anything itself: the agent takes the Writ to an executor.
3. **Execute (steps 8–12).** The executor checks the signature, expiry and target
agent, claims the Writ's nonce, applies its local rules, runs the command and
signs the result.
The [architecture guide](docs/architecture.md#how-a-request-flows) walks through
each step and what a failure returns.
**Watch: how Nomos works (9 min).** One request from intent to executed Writ,
then a delete that is denied until the agent gathers certified evidence, and a
prompt-injected agent stopped by policy, the council and the executor.
https://github.com/user-attachments/assets/5bac7e1e-04f5-4d12-81c8-f0c1de58b085
## What you can swap
Nomos is a set of contracts with replaceable parts around them. Each part below
changes through configuration or a service you supply, not a fork.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/diagrams/modularity-dark.svg">
<img alt="What you can swap without forking. Your side: the agent and framework, the MCP or gRPC transport, accounts and roles, and which council to call. Nomos council: voting members, models per role, chairman and threshold, self-hosted models, OPA policy rules, code review of files, durable storage, signing keys. Execution: the bundled executor service or your own, its local policy, and the runtime backend. Fixed contracts between them: the Intent, the signed Writ, and the signed receipt." src="docs/assets/diagrams/modularity.svg">
</picture>
| Part | Shipped default | Change it with |
|---|---|---|
| Your agent | Any MCP or gRPC client | [Integrate your own agent](docs/integrate-your-agent.md) |
| Voting members | Command integrity, environment isolation, blast containment | `members[]` in `configs/council.yaml`: add, remove, reprioritize, reweight |
| Models | One NVIDIA API Catalog model for every role | `llm_backends` per role (`nim`, `openai`, `anthropic`, `nv_inference`); [self-hosted models](docs/self-hosted-models.md) |
| Chairman and threshold | Chairman on, unanimous approval | `chairman.enabled`, `chairman.allow_quorum` |
| Policy | OPA `strict-shell` profile, fails closed | `opa.policy_id`, `policies/*.rego`, or an external OPA at `opa.url` |
| Councils | One council, `council-prod` | `configs/local_council_catalog.yaml` and `council_id` per request |
| Executor | OpenShell adapter on port `9907` | `deploy/executor-*.yaml` profiles, or [your own service](docs/integrate-your-agent.md#other-integration-shapes) |
| Storage and signing | Compose: Redis and local keys. Kind: PostgreSQL and Vault transit | `storage.mode`, `signing.provider` |
Details: [configuration reference](docs/reference/configuration.md).
**Watch: building a trusted executor (5 min).** What an executor must verify,
enforce and sign, and where to run it: beside the agent, one per host, or on a
central management host.
https://github.com/user-attachments/assets/3c029f53-5d49-4ba5-a9bd-e746df3fa856
## Integrate your own agent
Wrap your agent's tool dispatcher in a small adapter. Nothing in your agent's
framework has to change.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/diagrams/agent-adapter-dark.svg">
<img alt="Adapting an agent: 1 intercept the tool call and map it and the agent's task to fields; 2 call council_authorize; 3 decide: if denied, return the guidance to the agent, if approved take the Writ; 4 POST the Writ to the executor with X-Agent-ID and check success; 5 keep the signed ExecutionResult and attach it as certified_evidence to the next request." src="docs/assets/diagrams/agent-adapter.svg">
</picture>
The core of the adapter, given an open MCP session to the council:
```python
async def run_through_nomos(session, action):
reply = await session.call_tool("council_authorize", arguments={
**action, "agent_id": AGENT_ID, "auth_token": AUTH_TOKEN, "council_id": "council-prod",
})
if reply.isError:
raise RuntimeError(reply.content) # a tool error carries plain text, not JSON
decision = json.loads(reply.content[0].text)
if decision["status"] != "approved":
return decision # guidance goes back to the agent; a revision is a new request
async with httpx.AsyncClient(timeout=240) as http:
result = await http.post(f"{EXECUTOR_URL}/v1/writs/execute",
headers={"X-Agent-ID": AGENT_ID},
json={"writ": decision["writ"]})
result.raise_for_status()
return result.json() # keep the full ExecutionResult, including failures
# action = {"command": "/usr/bin/echo hello", "working_directory": "/workspace",
# "description": "...", "context": "the task and the steps so far",
# "target_resource": "/workspace",
# "justification": "...", "blast_radius": "Prints a string; changes nothing"}
```
Inspect `success` and `verification_stage` before reporting an action as completed.
Keep the original result for later evidence even if execution failed.
The [integration guide](docs/integrate-your-agent.md) has the complete adapter,
the values to get from your operator, denial handling, IDE agents, application
tools and custom executors.
Already running NeMo Relay? The [NeMo Relay plugin](integrations/nemo-relay/README.md)
does the adapter's work from configuration, with no change to the agent.
**Watch: Nomos through the NeMo Relay plugin (8 min).** What Relay is, how to
configure the plugin on a system that already runs it, and how its two hooks
carry a tool call to the council and back.
https://github.com/user-attachments/assets/bd5086a3-4f7a-4ec9-92bd-67c0b70efcaa
## Try it locally
Linux with Docker, plus Kind, kubectl and Helm for the default target, and an
[NVIDIA API key](https://build.nvidia.com/):
```bash
git clone https://github.com/NVIDIA/Nomos.git && cd Nomos
NVIDIA_API_KEY=nvapi-... ./scripts/deploy_stack.sh # Kind (default)
NVIDIA_API_KEY=nvapi-... DEPLOY_TARGET=compose ./scripts/deploy_stack.sh # or Docker Compose
curl -s http://127.0.0.1:9901/healthz # monitor and council
curl -s http://127.0.0.1:9907/v1/health # executor
```
The script generates local secrets, creates the first agent account and prints
the service URLs. [Getting started](docs/getting-started.md) continues from here
to a first approved request. The hosted API Catalog models are for evaluation;
for steady latency, run a [self-hosted model](docs/self-hosted-models.md).
## Documentation
| Step | Read | When |
|---|---|---|
| 1 | [Architecture](docs/architecture.md) | You want the request path, the Writ and the components |
| 2 | [Getting started](docs/getting-started.md) | You want a running stack and a first request |
| 3 | [Integrate your own agent](docs/integrate-your-agent.md) | You have an agent to put behind Nomos |
| 4 | [Configuration](docs/reference/configuration.md) · [Self-hosted models](docs/self-hosted-models.md) | You want to change members, models, policy or executors |
| 5 | [Deployment setup](docs/deployment-setup.md) · [Validation](docs/council-mcp-validation.md) | You operate a deployment |
| — | [MCP tools and executor API](docs/reference/mcp-api.md) · [Development](docs/development.md) | Reference and repository internals |
| — | [NeMo Relay plugin](integrations/nemo-relay/README.md) · [OpenShell request-review middleware](integrations/openshell/README.md) | Existing integrations, setup and deployment limits |
The [documentation index](docs/index.md) lists everything, including the
browser-based interactive explainers.
## Contributing, security and license
This project is not currently accepting contributions; see
[MAINTAINERS.md](MAINTAINERS.md) for the maintenance and release process. Report
vulnerabilities as described in [SECURITY.md](SECURITY.md).
Apache License 2.0; see [LICENSE](LICENSE). This project downloads and installs
additional third-party open source software. Review their license terms before
use; see [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY).
Nomos is built for integration with NVIDIA NeMo Agent Toolkit and speaks MCP for
broad agent compatibility. Its kernel follows John Lakos's levelized design.