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

# Getting Started with Agent Security

> Set up Rafter — the security toolkit built for AI coding agents. One command, 9 platforms, free forever.

# Getting Started

Rafter is the way to **shift security left** — into your AI coding agent's feedback loop. It runs on your machine with zero setup — no API key, no account, no telemetry. Same tools, same output, same policies for every developer on every platform. Add an API key and your agent can also run the Code Security Engine (deep SAST/SCA) on demand.

## Why Install Rafter

AI coding agents are powerful but they lack security judgment. They will run destructive commands, commit secrets, and install untrusted extensions without hesitation. Rafter sits inside the loop and gives them that judgment — before damage is done, not after.

**Install it because:**

* **Zero cost, zero risk.** Free, MIT-licensed, no telemetry, works offline. Nothing to evaluate — install it and see.
* **One command, 9 platforms.** `rafter agent init --all` covers Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Continue.dev, Aider, and OpenClaw. No per-platform configuration.
* **Complements sandboxing.** Sandboxes contain blast radius after something goes wrong. Rafter prevents the mistake in the first place — secrets never reach git, dangerous commands never execute.
* **More than secret scanning.** Command interception, policy enforcement, extension auditing, custom rules, MCP server, pre-commit hooks, and full audit logging — all in one package.
* **Stable output contract.** UNIX philosophy: scan results to stdout as JSON, status to stderr, exit codes are a versioned API. Deterministic for a given CLI version. Pipe to `jq`, feed to CI gates, hand to any automation that reads JSON.
* **Not just for agents.** Every feature works in human workflows too — pre-commit hooks, CI/CD gates, manual scanning. Agent-first doesn't mean agent-only.

## What Does Rafter Do?

Rafter provides six capabilities in one package:

* 🔍 **Secret scanning** — 21+ built-in patterns, deterministic detection, optional Betterleaks (formerly Gitleaks) for deeper coverage
* 🛡️ **Command interception** — Risk-tiered approval system that blocks destructive commands before agents execute them
* 📋 **Policy enforcement** — Project-level `.rafter.yml` files define custom rules that travel with the repo
* 🔌 **Extension auditing** — Evaluate third-party skills and MCP tools for embedded secrets, malicious URLs, and risky patterns
* 📝 **Audit logging** — Stable JSONL schema recording every security event
* ⚙️ **MCP server** — 4 tools exposed over stdio for native integration with any MCP-compatible client

## Installation

Install the Rafter CLI globally:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @rafter-security/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @rafter-security/cli
  ```

  ```bash yarn theme={null}
  yarn global add @rafter-security/cli
  ```

  ```bash pip theme={null}
  pip install rafter-cli
  ```
</CodeGroup>

<Note>
  **Python 3.10+ required for pip installs.** Verify your version:

  ```bash theme={null}
  python3 --version   # Must be 3.10 or higher
  ```

  On Ubuntu/Debian, Python and pip may not be installed by default:

  ```bash theme={null}
  sudo apt update && sudo apt install -y python3 python3-pip python3-venv
  ```

  On Fedora/RHEL: `sudo dnf install python3 python3-pip`.
  macOS: `brew install python`. Windows: install from [python.org](https://python.org) — pip is included.
</Note>

## Quick Setup

Initialize local security with one command:

```bash theme={null}
rafter agent init
```

This will:

1. Create `~/.rafter/config.json` configuration
2. Initialize directory structure
3. Auto-detect installed agents (Claude Code, Codex CLI, OpenClaw, Gemini CLI, Cursor, Windsurf, Continue.dev, Aider)
4. Set up audit logging

To install integrations, use `--with-*` flags, `--all`, or `--interactive`:

```bash theme={null}
rafter agent init --all                   # install all detected integrations + Betterleaks
rafter agent init --with-claude-code      # install specific integration
rafter agent init --interactive           # guided setup — prompts for each detected platform
```

### Project-Level Setup

To generate instruction files that agents read at session start in a specific project:

```bash theme={null}
rafter agent init-project                 # all platforms
rafter agent init-project --only claude-code,cursor  # specific platforms
rafter agent init-project --list          # preview without writing
```

This creates files like `.claude/CLAUDE.md`, `AGENTS.md`, `.windsurfrules`, etc. Commit them so every contributor's agent sees Rafter context automatically.

### Choose Your Risk Level

During setup, choose from three risk levels:

<AccordionGroup>
  <Accordion title="Minimal (Permissive)">
    * Basic guidance only
    * Most commands allowed
    * Good for local development
  </Accordion>

  <Accordion title="Moderate (Recommended)">
    * Standard protections
    * Approval required for high-risk commands
    * Secrets always blocked
    * **Default setting**
  </Accordion>

  <Accordion title="Aggressive (Maximum Security)">
    * Maximum security
    * Requires approval for most operations
    * Best for sensitive environments
  </Accordion>
</AccordionGroup>

```bash theme={null}
# Set risk level during init
rafter agent init --risk-level moderate

# Install all integrations with aggressive security
rafter agent init --all --risk-level aggressive

# Or change risk level later
rafter agent config set agent.riskLevel aggressive
```

## Verify Installation

Run the built-in health check to confirm everything is set up correctly:

```bash theme={null}
rafter agent verify
```

This checks your config, Betterleaks binary, and all 8 supported agent integrations (Claude Code, Codex, OpenClaw, Gemini CLI, Cursor, Windsurf, Continue.dev, Aider). Pass `--json` for CI-consumable output, `--probe` to confirm Claude Code's `PreToolUse` hook actually fires (not just that the file is on disk). If any check fails, the output includes actionable fix instructions.

You can also test individual components:

```bash theme={null}
# Scan current directory for secrets
rafter secrets .

# View configuration
rafter agent config show

# Check audit logs
rafter agent audit
```

> **Note:** `rafter agent scan` still works but is deprecated — it will be removed in a future major version.

## What's Next?

<CardGroup cols={2}>
  <Card title="Secret Scanning" icon="key" href="/guides/agent-security/secret-scanning">
    Learn how to detect secrets in your code
  </Card>

  <Card title="Command Execution" icon="terminal" href="/guides/agent-security/command-execution">
    Safely execute shell commands with validation
  </Card>

  <Card title="Claude Code" icon="robot" href="/guides/agent-security/claude-code-integration">
    Set up Rafter with Claude Code
  </Card>

  <Card title="Codex CLI" icon="code" href="/guides/agent-security/codex-integration">
    Set up Rafter with OpenAI Codex CLI
  </Card>

  <Card title="OpenClaw" icon="shield-halved" href="/guides/agent-security/openclaw-integration">
    Set up Rafter with OpenClaw agents
  </Card>

  <Card title="MCP Integration" icon="plug" href="/guides/agent-security/mcp-integration">
    Use with Cursor, Windsurf, Claude Desktop, Cline
  </Card>

  <Card title="Command Reference" icon="book" href="/guides/agent-security/reference">
    Complete CLI command reference
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/agent-security/troubleshooting">
    Fix common install and runtime issues
  </Card>
</CardGroup>

## Directory Structure

After initialization, Rafter creates:

```
~/.rafter/
├── config.json      # Configuration file
├── audit.jsonl      # Security event log (JSON lines)
├── bin/betterleaks  # Betterleaks binary (if installed; v0.8.0+)
├── patterns/        # Custom secret patterns (reserved)
└── git-hooks/       # Global pre-commit hook (if --global)
```

## Agent Auto-Detection

`rafter agent init` detects all supported agents and installs the appropriate skills:

| Agent        | Detected via          | Install flag         | Skills installed to        |
| ------------ | --------------------- | -------------------- | -------------------------- |
| Claude Code  | `~/.claude`           | `--with-claude-code` | `~/.claude/skills/rafter/` |
| Codex CLI    | `~/.codex`            | `--with-codex`       | `~/.agents/skills/rafter/` |
| OpenClaw     | `~/.openclaw`         | `--with-openclaw`    | `~/.openclaw/skills/`      |
| Gemini CLI   | `~/.gemini`           | `--with-gemini`      | MCP server config          |
| Cursor       | `.cursor/`            | `--with-cursor`      | MCP server config          |
| Windsurf     | `~/.codeium/windsurf` | `--with-windsurf`    | MCP server config          |
| Continue.dev | `~/.continue`         | `--with-continue`    | MCP server config          |
| Aider        | `~/.aider.conf.yml`   | `--with-aider`       | MCP server config          |

Use `--all` to install all detected integrations at once, or individual `--with-*` flags for specific agents.

Restart your agent after initialization to load the installed skills.

## Support

<Card title="Need Help?" icon="question">
  * Documentation: [docs.rafter.so](https://docs.rafter.so)
  * GitHub Issues: [rafter-cli/issues](https://github.com/raftersecurity/rafter-cli/issues)
  * Support: [rafter.so/help](https://rafter.so/help)
</Card>