MandateOS writes host-scoped files such as `.codex/config.toml`, `.codex/hooks.json`, Cursor hooks, and Claude workspace settings.
MandateOS / runtime guardrails for AI agents
Install approvals, guardrails, and receipts into agent workflows.
MandateOS gives teams using Codex, Cursor, Claude Code, OpenClaw, and MCP-based workflows a concrete operating loop: define a mandate, intercept risky actions, escalate when needed, and keep signed evidence behind what ran.
When an agent wants to run a shell command, push code, or call an external tool, MandateOS evaluates the request before it runs, shows operators what was requested, and records the outcome as approval events, receipts, and evidence.
For platform, security, and engineering teams running agents inside real repositories, shells, and operator-reviewed workflows.
Export your connection values, run the host installer, and MandateOS writes local host config plus a status path into that workspace. No repo clone required.
Public proof
Open repo and install path3 published npm packages4 hosts available today
Signed receipts, execution grants, and audit-chain verification are inspectable from the first guarded action. See verification details
- No-clone install into an existing repo
- Open-source trust layer at the edge
- Managed approvals, workspaces, and audit retention
- Codex, Cursor, Claude Code, OpenClaw, and MCP workflows
Before risky actions continue, the runtime evaluates scope, budget, risk zone, and whether an operator decision is required.
Teams can review signed receipts, execution grants, approval events, and retained audit history after the action completes.
The trust layer is open source, so teams can inspect the host integration path instead of relying on a black box.
Where it fits
Use one approval and evidence model across the host tools your team already runs.
MandateOS sits between the agent and the actions that matter: shell execution, code changes, approvals, and higher-risk tool use.
Available today: Codex, Cursor, Claude Code, OpenClaw, and managed MCP flowsSame mandate, approval, and receipt model across local hostsPlanned: GitHub-side enforcement
Codex
Available TodayUse project-scoped Codex MCP and hook config to bring Bash-side actions under the same approval and receipt model.
- Writes `.codex/config.toml` with the MandateOS MCP entry
- Adds Bash PreToolUse guardrails in `.codex/hooks.json`
- Blocks conservatively when approval is still required
Cursor
Available TodayBring Cursor sessions under the same approval, tool-scope, and receipt model as the rest of your agent operations.
- Configures local MCP entries for the repo
- Writes guarded shell and MCP hooks for the workspace
- Keeps the runtime path aligned with the rest of the trust layer
Claude Code
Available TodayUse the same operating model in Claude Code so teams do not have to reinvent policy for each shell.
- Adds the local `mandateos` MCP entry
- Creates workspace-scoped settings for the selected repo
- Preserves a consistent approval and receipt path
OpenClaw
Available TodayDesigned for OpenClaw’s flexible host surface so teams can keep explicit tool boundaries, approvals, and receipts around local agent power.
- Installs the OpenClaw bridge and plugin bundle
- Creates a guarded local profile for the selected workspace
- Uses the same mandate, approval, and evidence model as the other hosts
GitHub Enforcement
PlannedRepository-side actions are a natural next extension of the same policy and approval model.
- Designed to reuse the same mandate logic
- Lets teams extend review and evidence past local shell actions
- Explicitly not presented as fully available today
How it looks in practice
Inspectable proof beats abstract claims.
MandateOS is easiest to trust when you can see the local files it writes, the approval event it creates, and the evidence operators keep after the run.
Product preview
Approval review, receipts, and verification in one operating loop
This is the part first-time visitors need to picture quickly: a risky request reaches the runtime before it executes, an operator sees the exact request and mandate context, and the resulting receipt stays attached to the action for later review.
Click the preview to inspect it at a larger size.
- The request includes the host, workspace, mandate id, and risk context before the tool continues.
- Approval review keeps the operator decision, reasons, and escalation state in one place instead of scattered across chat and logs.
- Receipt verification keeps the signed evidence, approval event, and audit chain attached to the action itself.
Representative product preview based on the live MandateOS approval and evidence flow.
Writes host-scoped files into the workspace you already use
The installer configures the host locally instead of asking teams to copy files around by hand.
.codex/config.tomlRegisters the `mandateos` MCP server and runtime env vars.
.codex/hooks.jsonAdds PreToolUse guardrails for Bash-side execution.
.git/info/excludeKeeps generated host config out of normal commits.
Shows the exact action, mandate, and escalation path
When an agent asks for something higher risk, operators get a concrete event to review instead of a vague chat summary.
Requested action`run migration against production`
Mandate checkTool scope allowed, but risk zone requires approval.
Operator outcomeApproval requested before the command can continue.
Receipts and audit events stay attached to the action itself
After execution, teams can review the signed record instead of reconstructing what happened from logs and screenshots.
ReceiptSigned result with mandate id, decision, and timestamps.
Approval eventOperator review and any execution grant stay in the chain.
Audit verificationHash chain and signature status can be checked later.
Example flow
One realistic end-to-end flow
A platform team installs MandateOS into a repo, defines a mandate for allowed tools and escalation thresholds, lets the agent request a production-sensitive action, stops that action for approval, then reviews the receipt and audit chain afterward.
Install into the repo
Run the host installer for Codex, Cursor, Claude Code, or OpenClaw against an existing workspace path.
Result: local MCP and hook files are written for that host.Define the mandate
Set allowed tools, budgets, risk zones, approval thresholds, and receipt requirements.
Result: the runtime has a concrete policy boundary to evaluate.Agent requests action
The agent proposes a risky command before touching the shell or other sensitive tools.
Example: `run migration against production` reaches the runtime first.Approve or escalate
Routine work continues. Higher-risk work stops for explicit approval or a grant.
Result: an approval event is created for operator review.Keep the evidence
The action record stays attached to receipts, approval events, and audit verification.
Result: operators can review what was requested, approved, and executed later.Why teams adopt this
Practical operator benefits matter more than abstract governance.
MandateOS is useful when teams need runtime guardrails, shared approvals, and evidence they can review after the agent run finishes.
Stop sensitive work for explicit operator review
Teams do not have to rely on prompt instructions or chat etiquette when an action needs approval before it continues.
See what the agent asked to do before and after execution
Operators can review the requested action, the runtime decision, the approval event, and the final receipt in one place.
Keep retained evidence instead of reconstructing history later
Receipts, grants, and audit events stay attached to the action so review does not depend on scattered logs or screenshots.
Best first use cases
Start where runtime guardrails are immediately valuable.
MandateOS works best when teams begin with narrow, high-consequence workflows rather than trying to govern every agent action on day one.
Production-sensitive shell commands
Require approval before commands that touch production data, migrations, or higher-risk environments.
Outcome: risky commands stop for operator review instead of slipping through normal agent flow.Repository write controls
Gate specific repo-changing workflows so teams can separate routine edits from higher-risk changes.
Outcome: one operating model across Codex, Cursor, Claude Code, and future GitHub-side enforcement.External tool escalation
Use receipts and approval thresholds when agents move beyond local edits into external systems and managed tools.
Outcome: the runtime boundary stays explicit as integrations grow.Early multi-team rollouts
Start with the open packages locally, then add the managed control plane when teams need shared approvals and retained evidence.
Outcome: adoption can begin small without hiding the trust layer.Trust boundary
The open-source trust layer and the managed control plane do different jobs.
MandateOS is easier to evaluate when the boundary is explicit. The public packages handle local host integration and runtime enforcement. The managed control plane handles shared operator workflows, approvals, workspace administration, and retained evidence.
What runs close to the host
- Installer CLIs and package entrypoints
- Local MCP registration and host hook wiring
- Runtime request path into MandateOS
- Inspectability through the public repo and packages
What operators use centrally
- Workspaces and operator access
- Approval inbox and escalation review
- Retained audit history and evidence export
- Shared operations across teams and repos
What teams can verify afterward
- Signed receipts and execution grants
- Approval events attached to the request path
- Audit chain verification and retained history
- Public package surface plus operator-visible outcomes
How the boundary works
Agent host (Codex, Cursor, Claude Code, OpenClaw)
MandateOS runtime checks
Operator review, receipts, and audit evidence
Install without cloning
The shortest path is: export two values, run one installer, open your shell.
MandateOS is already packaged for Codex, Cursor, Claude Code, and OpenClaw. You do not need to clone this repository to try it.
You only need the basics that connect the local host to the runtime and a repo path where you want the guardrails installed.
- A `MANDATE_OS_BASE_URL`
- A `MANDATE_OS_AGENT_TOKEN`
- A repo path for the workspace you want to guard
- One host: Codex, Cursor, Claude Code, or OpenClaw
- Optional: `MANDATE_OS_MCP_DEFAULT_MANDATE_ID`
Choose one host, export the base URL and agent token, run the matching `npx` installer, then run the host status command before doing sensitive work.
- Export the connection values once in the shell you plan to use.
- Run the matching installer against your repo path.
- Open the guarded workspace and confirm the host sees MandateOS.
MandateOS becomes concrete immediately because the host now has local config, a status command, and a runtime path for risky actions.
- Local MCP and hook files written for that host
- A status command to confirm the setup
- A host-scoped runtime path for approvals and receipts
The packages and installers are open source. Teams usually connect them to the managed control plane when they want shared approvals, workspace administration, and retained audit history.
- Open source: SDK, MCP server, installers, starter bundles, and docs
- Managed: workspaces, approvals, retained evidence, and operator review
Export your MandateOS connection values
Set your base URL and agent token in the shell where you plan to run an installer. Add a default mandate id only when you want one project mandate preselected.
Run the host installer
Use the package entrypoint or download the shell script for Codex, Cursor, Claude Code, or OpenClaw. Each installer writes the local files that host needs.
Open the shell and verify the host
Start the guarded workspace, approve the MandateOS MCP if the host asks, and confirm the status command before you move into sensitive work.
Shell environment
Copy the runtime URL and agent token from your MandateOS control plane. `MANDATE_OS_MCP_DEFAULT_MANDATE_ID` is optional and only needed when you want the host to start with a project mandate already selected.
# Replace with the runtime URL and agent token from your MandateOS control plane.
export MANDATE_OS_BASE_URL="https://your-mandateos-runtime-url"
export MANDATE_OS_AGENT_TOKEN="key_id.secret"
# Optional: preselect one mandate for this repo.
export MANDATE_OS_MCP_DEFAULT_MANDATE_ID="mdt_123"Packages
These open-source packages are the install and trust layer. Teams pair them with the managed control plane when they want hosted approvals and operator workflows.
@mandate-os/sdk
Use the SDK when you want to call MandateOS from your own services, hooks, or custom host integrations.
npm install @mandate-os/sdk@latest- Typed client for mandates, receipts, and execution grants
- Fits internal tools, host gateways, and policy-aware services
@mandate-os/mcp
Registers the MandateOS MCP server and ships the installer CLIs for Codex, Cursor, and Claude Code.
npm install @mandate-os/mcp@latest- Binaries: mandate-os-mcp, mandate-os-codex-install, mandate-os-cursor-install, mandate-os-claude-install
- Writes MCP entries plus host hooks for guarded execution
@mandate-os/openclaw
Installs the OpenClaw bridge, bundle, and guarded agent setup without copying repo files by hand.
npm install @mandate-os/openclaw@latest- Binaries: mandate-os-openclaw-install, mandate-os-openclaw-bridge
- Adds the MandateOS plugin bundle under the local OpenClaw state directory
Host installers
Run the package CLI directly with `npx`, or download the matching shell script and pass your workspace path as the first argument.
Codex
@mandate-os/mcpWrites project-scoped `.codex/config.toml` and `.codex/hooks.json` so Codex loads the MandateOS MCP server and Bash guardrails inside that repository.
Open Installer Details
Codex
@mandate-os/mcpnpx --yes --package @mandate-os/mcp@latest mandate-os-codex-install install \
--workspace "/absolute/path/to/your/repo"- Reads `MANDATE_OS_BASE_URL`, `MANDATE_OS_AGENT_TOKEN`, and optional `MANDATE_OS_MCP_DEFAULT_MANDATE_ID` from your shell, then forwards the runtime values through Codex `env_vars`.
- Status check: `npx --yes --package @mandate-os/mcp@latest mandate-os-codex-install status --workspace "/absolute/path/to/your/repo"`
Cursor
@mandate-os/mcpConfigures Cursor user and workspace MCP entries, then writes `beforeShellExecution` and `beforeMCPExecution` hooks for the target repository.
Open Installer Details
Cursor
@mandate-os/mcpnpx --yes --package @mandate-os/mcp@latest mandate-os-cursor-install install \
--workspace "/absolute/path/to/your/repo"- Reads `MANDATE_OS_BASE_URL`, `MANDATE_OS_AGENT_TOKEN`, and optional `MANDATE_OS_MCP_DEFAULT_MANDATE_ID` from your shell.
- Status check: `npx --yes --package @mandate-os/mcp@latest mandate-os-cursor-install status --workspace "/absolute/path/to/your/repo"`
Claude Code
@mandate-os/mcpWrites the local-scoped `mandateos` MCP entry into `~/.claude.json` and creates workspace hooks in `.claude/settings.local.json`.
Open Installer Details
Claude Code
@mandate-os/mcpnpx --yes --package @mandate-os/mcp@latest mandate-os-claude-install install \
--workspace "/absolute/path/to/your/repo"- Reads `MANDATE_OS_BASE_URL`, `MANDATE_OS_AGENT_TOKEN`, and optional `MANDATE_OS_MCP_DEFAULT_MANDATE_ID` from your shell.
- Status check: `npx --yes --package @mandate-os/mcp@latest mandate-os-claude-install status --workspace "/absolute/path/to/your/repo"`
OpenClaw
@mandate-os/openclawInstalls the OpenClaw extension bundle, configures the local MCP server, and creates a guarded agent profile for the selected workspace.
Open Installer Details
OpenClaw
@mandate-os/openclawMANDATE_OS_OPENCLAW_WORKSPACE_PATH="/absolute/path/to/your/repo" \
npx --yes --package @mandate-os/openclaw@latest mandate-os-openclaw-install install- Reads `MANDATE_OS_BASE_URL` and optional `MANDATE_OS_MCP_DEFAULT_MANDATE_ID` during installation.
- Status check: `MANDATE_OS_OPENCLAW_WORKSPACE_PATH="/absolute/path/to/your/repo" npx --yes --package @mandate-os/openclaw@latest mandate-os-openclaw-install status`
Trust, security, and evidence
Security claims should end in artifacts operators can review.
MandateOS is stronger when the security story is tied to receipts, approval events, execution grants, and a tamper-evident audit chain rather than broad promises alone.
Verifiable receipts for meaningful actionsApproval events attached to the request pathExecution grants for escalated workAudit chain verification for retained history
Mandates, receipts, and grants are signed when they are created
The runtime signs mandates, receipts, and execution grants so teams can verify integrity and keep older signatures valid through key rotation.
Sensitive tokens are encrypted before storage
At-rest credential storage uses authenticated encryption so the control plane can protect secrets and detect tampering.
API keys are stored as hashes, not raw secrets
Key verification uses timing-safe comparison so the runtime does not have to keep plain-text secrets on disk.
Audit events are chained so later modification is visible
A SHA-256 audit chain makes review stronger because historical edits break verification instead of staying invisible.
Inter-service requests are signed and scoped
Service-to-service calls are authenticated across method, path, body, and expiry. Mutating requests also require idempotency keys.
Evidence is organized for approval and later review
The security model becomes practical when operators can see the request, the escalation decision, and the receipt together.
FAQ
Questions teams ask before they trust agent guardrails.
Direct answers for teams evaluating MandateOS for approvals, runtime visibility, auditability, and inspectable host integration.
1What is MandateOS?
MandateOS is an AI agent guardrails system for teams using Codex, Cursor, Claude Code, OpenClaw, and MCP-based workflows. It evaluates tool scope, budgets, approvals, and receipt requirements before sensitive actions continue.
2What do I see after install?
You see local host config for the selected repo, a status command for the installer, and a concrete runtime path for risky actions. In practice that means files such as `.codex/config.toml`, `.codex/hooks.json`, Cursor hooks, or Claude workspace settings, depending on the host.
3Is MandateOS open source?
The developer-facing trust layer is open source: the SDK, MCP server, installer CLIs, starter policy bundles, docs, and homepage live in the public repo. The managed control plane handles shared approvals, workspace operations, retained audit history, and operator administration.
4Do I need the managed control plane?
No. The public packages and installers can be used on their own when you want local host integration and runtime checks. Teams add the managed control plane when they want shared approvals, workspace administration, retained evidence, and operator review across repos.
5What happens if MandateOS cannot reach the runtime?
MandateOS does not silently waive guardrails. For live guarded actions, the host surfaces a MandateOS failure or blocks the action until the runtime is available again. A few local paths, such as read-only shell commands and MandateOS self-calls, can still short-circuit locally without calling the runtime.
6How is this different from system prompts?
System prompts tell the agent what it should do. MandateOS evaluates what the agent actually requested before the sensitive tool runs, then keeps receipts, approval events, and audit evidence behind the outcome.
7Which integrations are available today?
Today MandateOS provides integrations for Codex, Cursor, Claude Code, OpenClaw, and managed MCP flows. GitHub-side enforcement is planned next, but is not presented as fully available today.
8Where should a team start?
Start with one host and one concrete workflow, usually a risky shell action or repo write path. Install the matching public package locally first, then connect that setup to the managed control plane when you want shared approvals, workspace operations, and retained evidence.
Start with a concrete workflow
Install MandateOS into one repo, then watch the first approval and receipt happen.
The fastest way to evaluate MandateOS is to wire one host into one real repo, define one clear mandate, and inspect the evidence trail yourself.