Railguard

Railguard is invoked via the rg command. It supports multiple subcommands for different operation modes.

Synopsis

rg [OPTIONS] <COMMAND>
 
Commands:
  run    Run a command through the Railguard proxy
  proxy  Start the proxy without running a command
  login  Login to Railguard Cloud
 
Options:
  -c, --config <FILE>  Path to config file [default: railguard.toml]
  -p, --port <PORT>    Override the listen port
  -h, --help           Print help
  -V, --version        Print version

Commands

`rg run`

Run a child command through the Railguard proxy. The proxy starts, runs your command, and shuts down when the command exits.

rg run [OPTIONS] -- <COMMAND>...

Arguments:

<COMMAND>... — The command to run (everything after --)

Examples:

# Run a Foundry script
rg run -- forge script script/Deploy.s.sol --broadcast
 
# Run a custom script
rg run -- node ./bot.js
 
# With port override
rg run --port 8546 -- forge script Deploy.s.sol

Environment Injection:

Railguard automatically sets these environment variables for your child process:

RPC_URL=http://127.0.0.1:<port>
ETH_RPC_URL=http://127.0.0.1:<port>

`rg proxy`

Start the proxy server without running a child command. Useful for:

Background operation
Multiple scripts using the same proxy
Integration with external process managers

rg proxy [OPTIONS]

Examples:

# Start in foreground
rg proxy
 
# Start in background
rg proxy &
 
# With custom config
rg -c production.toml proxy

Shutdown:

Press Ctrl+C for graceful shutdown
Or send SIGTERM

Authenticate with Railguard Cloud for remote policy sync and log retention.

rg login

This initiates a device code flow:

Opens your browser (or prints a URL)
You authorize on the Railguard website
CLI receives an access token
Token is stored locally for future requests

Global Options

`--config, -c`

Specify the path to your configuration file.

rg -c ./config/railguard.toml run -- forge script Deploy.s.sol
rg --config /etc/railguard/production.toml proxy

Default: railguard.toml in the current directory.

`--port, -p`

Override the server port from the config file.

rg --port 8546 run -- forge script Deploy.s.sol

This is useful for running multiple Railguard instances simultaneously.

Exit Codes

Code	Meaning
0	Success
1	Child process failed (for `rg run`)
1	Configuration error
1	Server bind failure

When using rg run, the exit code matches the child process exit code.

Signals

Signal	Behavior
`SIGINT` (Ctrl+C)	Graceful shutdown within 5 seconds
`SIGTERM`	Graceful shutdown within 5 seconds
`SIGKILL`	Immediate termination (no cleanup)

Environment Variables

Railguard reads these environment variables:

Variable	Purpose
`RUST_LOG`	Log level (e.g., `debug`, `info`, `warn`)
`RAILGUARD_CONFIG`	Alternative to `-c` flag

Variables in your config are expanded using ${VAR_NAME} syntax:

[upstream]
url = "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}"

Usage Patterns

CI/CD Integration

# Run in non-interactive mode
RUST_LOG=info rg run -- forge script Deploy.s.sol --broadcast 2>&1 | tee railguard.log

Multiple Instances

# Mainnet on port 8545
rg -c mainnet.toml --port 8545 proxy &
 
# Testnet on port 8546
rg -c sepolia.toml --port 8546 proxy &

Docker

FROM rust:1.75-slim as builder
WORKDIR /app
COPY . .
RUN cargo build --release
 
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/rg /usr/local/bin/
COPY railguard.toml /etc/railguard/
CMD ["rg", "-c", "/etc/railguard/railguard.toml", "proxy"]

systemd Service

[Unit]
Description=Railguard RPC Proxy
After=network.target
 
[Service]
Type=simple
User=railguard
ExecStart=/usr/local/bin/rg -c /etc/railguard/railguard.toml proxy
Restart=on-failure
RestartSec=5
 
[Install]
WantedBy=multi-user.target

Next Steps

Configuration — Config file reference
TUI — Terminal interface guide
Policy Engine — How inspection works

CLI Reference