Getting Started

Installation

Quick Install (Recommended)

curl -fsSL https://railgun.dev/install.sh | bash

This will:

Download the correct binary for your platform
Install it to ~/.local/bin/
Configure Claude Code to use Railgun

From GitHub Releases

Download the latest release for your platform:

darwin-arm64 (macOS Apple Silicon)
darwin-x64 (macOS Intel)
linux-arm64
linux-x64

# Example: macOS Apple Silicon
tar -xzf railgun-darwin-arm64.tar.gz
mv railgun ~/.local/bin/
railgun install

From Source

git clone https://github.com/anthropics/railgun.git
cd railgun
cargo build --release
cp target/release/railgun ~/.local/bin/
railgun install

Quick Start

1. Install the Hook

railgun install

This adds Railgun to ~/.claude/settings.json as a preToolUse hook.

2. Verify Installation

railgun --version

3. Create a Policy (Optional)

Create railgun.toml in your project or home directory:

[policy]
mode = "strict"  # "strict" blocks, "monitor" logs only
 
[policy.secrets]
enabled = true
 
[policy.commands]
enabled = true
 
[policy.protected_paths]
enabled = true
 
[policy.network]
enabled = true
 
# Tool-level permissions
[tools]
allow = []
deny = []
ask = ["mcp__*"]  # Prompt for MCP tools

4. Test Your Policy

# Test a safe command
railgun test Bash '{"command":"ls -la"}'
# Result: ALLOWED
 
# Test a dangerous command
railgun test Bash '{"command":"rm -rf /"}'
# Result: DENIED (Dangerous command pattern)
 
# Test secret detection
railgun test Write '{"content":"AKIA1234567890EXAMPLE"}'
# Result: DENIED (AWS access key detected)

5. Validate Configuration

railgun lint

How It Works

When Claude Code attempts to use a tool:

Claude Code calls railgun hook with JSON on stdin
Railgun parses the tool name and input
Policy engine runs checks: tools → secrets → commands → paths → network
Returns verdict: allow, deny (with reason), or ask (prompt user)
Claude Code proceeds or blocks based on verdict

{"tool_name":"Bash","tool_input":{"command":"ls"}}
                    │
                    ▼
           railgun hook (stdin)
                    │
                    ▼
            rg_policy::inspect()
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
   Tool Check            Parameter Check
        │                       │
   (early deny)    ┌────────────┼────────────┐
        │          ▼            ▼            ▼
        │      Secrets      Commands      Paths
        │          │            │            │
        │          └────────────┼────────────┘
        │                       ▼
        │                   Network
        │                       │
        └───────────┬───────────┘
                    ▼
          Verdict (Allow|Deny|Ask)
                    │
                    ▼
              Exit Code (0 or 2)

Next Steps

Configuration — Full config file reference
Policy Engine — How inspection works
CLI Reference — All command-line options

Getting Started

On this page