Skip to main content
By the end of this guide you will have ironrun installed, a policy file wired to your project, at least one secret stored in an encrypted local vault, and a working run_sealed tool that your AI agent can call to run commands without ever reading a credential value.
1
Install ironrun
2
Choose the method that suits your platform. The curl installer is the fastest path on Linux and macOS — it is an inspectable script with mandatory checksum verification before anything is written to disk.
3
curl (Linux / macOS)
go install
npm / npx
4
Confirm the binary is on your PATH:
5
ironrun version
# ironrun v0.4.0
6
Run ironrun setup in your project directory
7
Navigate to your project root and run setup. ironrun inspects your project, previews every file it is about to write, and asks for confirmation before touching anything.
8
cd your-project
ironrun setup
9
Setup does five things:
10
  • Detects your stack — it finds your task runner (npm/pnpm/yarn/bun, Go, Rust, Python) and any .env file, and pre-fills command definitions with the env var names it discovers.
  • Creates an encrypted dev environment — secret values are stored outside your repository under ~/.ironrun/vaults/, wrapped by a project root key in your OS credential manager (Keychain on macOS, libsecret on Linux).
  • Registers the MCP server — writes or merges .mcp.json at the project root so Claude Code picks up the run_sealed tool automatically. If the Codex or Cursor CLIs are present, ironrun also merges into their global MCP configs (~/.codex/config.toml and ~/.cursor/mcp.json) so those agents work too.
  • Writes agent instruction files — CLAUDE.md, AGENTS.md, and .cursorrules tell each agent to use run_sealed instead of running shell commands directly.
  • Optionally installs a background service — ironrun offers to install a value-blind per-user daemon (launchd on macOS, systemd on Linux) that coordinates project and inbox state. You can skip this and install it later with ironrun daemon install.
    • 11
    After setup your project root will contain:
    12
    your-project/
├── ironrun.yml       ← your policy file
├── .mcp.json         ← MCP server config for Claude Code
├── CLAUDE.md         ← instructs Claude Code to use run_sealed
├── AGENTS.md         ← instructs Codex to use run_sealed
└── .cursorrules      ← instructs Cursor to use run_sealed
    13
    Here is a representative ironrun.yml that setup generates for a Node.js project:
    14
    version: "2"
environment_set: active
require_agent_leases: true
allow_proposals: true

commands:
  - id: dev
    argv: [npm, run, dev]
    ttl: 0
    secrets: [DATABASE_URL, STRIPE_SECRET_KEY]

  - id: test
    argv: [npm, test]
    ttl: 120s
    secrets: [DATABASE_URL, STRIPE_SECRET_KEY]

  - id: build
    argv: [npm, run, build]
    ttl: 120s
    15
    Each id is the name the agent uses when it calls run_sealed. The argv is a literal list — no shell, no pipes, no glob expansion, so an injected value can never be re-expanded or piped somewhere unexpected.
    16
    Add a secret
    17
    Store your first secret in the encrypted vault. ironrun uses a masked prompt so the value is never echoed to your terminal:
    18
    ironrun add OPENAI_API_KEY
# Secret value (input hidden):
# Saved OPENAI_API_KEY in dev. Value is never displayed.
    19
    To import an entire existing .env file at once, ironrun will preview the key names (never the values), ask for confirmation, encrypt and verify the copy, and warn you that the plaintext source file remains on disk:
    20
    chmod 600 .env
ironrun import .env
    21
    Check what’s stored without revealing any values:
    22
    ironrun status
    23
    Run a sealed command yourself
    24
    Before handing control to your agent, run a command through ironrun yourself to see the redaction in action:
    25
    ironrun run test
    26
    ironrun resolves the secrets bound to the test command, injects them into the child process, streams the output through the redactor, and prints the cleaned result to your terminal. If any test logs a connection string, you will see [REDACTED] instead of the value.
    27
    Run ironrun doctor at any point to verify your full setup in one shot — it validates the policy file, checks that your provider CLI is installed and authenticated, runs a redaction self-test, and confirms that every command’s binary resolves on PATH.
    28
    Start your agent
    29
    Launch your agent as you normally would — for example, claude for Claude Code. Because .mcp.json is already in your project root, Claude Code picks up the run_sealed tool automatically without any additional configuration.
    30
    The agent will see run_sealed in its tool list and, when it needs to run a command, call it instead of using a bare shell. On its first call it will request a trusted workspace session; ironrun surfaces that request in the global Inbox. Approve it once and the same session can run commands for two hours without further prompts:
    31
    ironrun trust list    # see pending session requests
ironrun trust grant req_abc123
    32
    From that point on, when the agent runs npm test through run_sealed:
    33
    What the agent asked for:
    34
    run_sealed({ "argv": ["npm", "test"] })
    35
    What ironrun ran:
    36
    DATABASE_URL=postgres://app:s3cr3t@db.internal/myapp \
STRIPE_SECRET_KEY=sk_live_51Nabc123 \
npm test
    37
    What the agent received back:
    38
    exit_code: 0
duration_ms: 4231

--- stdout ---
ok  myapp  4.2s

--- stderr ---
(empty)
    39
    The agent never held DATABASE_URL or STRIPE_SECRET_KEY. Those values never entered the conversation, and they will never appear in the Claude Code JSONL logs.

    ​
    What to do next

    • Explore additional environments with ironrun new staging and switch between them with ironrun use staging
    • Learn about the full policy file reference — TTLs, no_network, seccomp filtering, and the audit log
    • Set up revocable agent leases for sensitive projects where you want to approve every individual command
    • Review the MCP tools reference to understand exactly what the agent can and cannot do