> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started with ironrun: Sealed Execution in 5 Minutes

> Install ironrun, run setup in your project directory, and execute your first sealed command with secrets injected and redacted from agent output.

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.

<Steps>
  ### Install ironrun

  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.

  <CodeGroup>
    ```bash curl (Linux / macOS) theme={null}
    curl -fsSL https://ironrun.dev/install.sh -o /tmp/ironrun-install.sh
    bash /tmp/ironrun-install.sh
    ```

    ```bash go install theme={null}
    go install github.com/generalized-labs/ironrun/cmd/ironrun@latest
    ```

    ```bash npm / npx theme={null}
    npx @generalized-labs/ironrun@latest
    ```
  </CodeGroup>

  Confirm the binary is on your `PATH`:

  ```bash theme={null}
  ironrun version
  # ironrun v0.4.0
  ```

  ### Run `ironrun setup` in your project directory

  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.

  ```bash theme={null}
  cd your-project
  ironrun setup
  ```

  Setup does five things:

  1. **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.
  2. **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).
  3. **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.
  4. **Writes agent instruction files** — `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` tell each agent to use `run_sealed` instead of running shell commands directly.
  5. **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`.

  After setup your project root will contain:

  ```
  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
  ```

  Here is a representative `ironrun.yml` that setup generates for a Node.js project:

  ```yaml theme={null}
  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
  ```

  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.

  ### Add a secret

  Store your first secret in the encrypted vault. ironrun uses a masked prompt so the value is never echoed to your terminal:

  ```bash theme={null}
  ironrun add OPENAI_API_KEY
  # Secret value (input hidden):
  # Saved OPENAI_API_KEY in dev. Value is never displayed.
  ```

  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:

  ```bash theme={null}
  chmod 600 .env
  ironrun import .env
  ```

  Check what's stored without revealing any values:

  ```bash theme={null}
  ironrun status
  ```

  ### Run a sealed command yourself

  Before handing control to your agent, run a command through ironrun yourself to see the redaction in action:

  ```bash theme={null}
  ironrun run test
  ```

  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.

  <Tip>
    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`.

    ```bash theme={null}
    ironrun doctor
    ```

    ```
      ✓ ironrun.yml valid (v2, 3 command(s))
      ✓ provider passthrough (no external CLI required)
      ✓ redaction self-test passed
      ✓ command "test": "npm" resolves
      ✓ command "build": "npm" resolves
      ✓ command "dev": "npm" resolves
    ```
  </Tip>

  ### Start your agent

  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.

  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:

  ```bash theme={null}
  ironrun trust list    # see pending session requests
  ironrun trust grant req_abc123
  ```

  From that point on, when the agent runs `npm test` through `run_sealed`:

  **What the agent asked for:**

  ```
  run_sealed({ "argv": ["npm", "test"] })
  ```

  **What ironrun ran:**

  ```bash theme={null}
  DATABASE_URL=postgres://app:s3cr3t@db.internal/myapp \
  STRIPE_SECRET_KEY=sk_live_51Nabc123 \
  npm test
  ```

  **What the agent received back:**

  ```
  exit_code: 0
  duration_ms: 4231

  --- stdout ---
  ok  myapp  4.2s

  --- stderr ---
  (empty)
  ```

  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.
</Steps>

## 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](/concepts/policy-file) — TTLs, `no_network`, seccomp filtering, and the audit log
* Set up [revocable agent leases](/guides/agent-setup) for sensitive projects where you want to approve every individual command
* Review the [MCP tools reference](/mcp/overview) to understand exactly what the agent can and cannot do