Install / macOS

Install on macOS

Native binaries for both Intel and Apple Silicon. Ferrum Edge was benchmarked on Apple Silicon — expect excellent performance.



Apple Silicon recommended: The ARM64 binary is compiled natively for M-series chips. The benchmarks showing ~102K RPS HTTP/1.1 were measured on Apple Silicon.

Download the Binary



macOS ARM64

Apple Silicon (M1/M2/M3/M4)



macOS x86_64

Intel Mac

bash — Apple Silicon

# Apple Silicon (M1/M2/M3/M4)
curl -LO https://github.com/ferrum-edge/ferrum-edge/releases/latest/download/ferrum-edge-macos-aarch64

# Intel Mac
# curl -LO https://github.com/ferrum-edge/ferrum-edge/releases/latest/download/ferrum-edge-macos-x86_64

Remove macOS Gatekeeper Quarantine

macOS quarantines binaries downloaded from the internet. Remove the quarantine flag before running.

bash

xattr -d com.apple.quarantine ferrum-edge-macos-aarch64

Install the Binary

bash

chmod +x ferrum-edge-macos-aarch64
sudo mv ferrum-edge-macos-aarch64 /usr/local/bin/ferrum-edge

# Verify
ferrum-edge --version

Create Config and Start

bash

mkdir -p ~/.ferrum
cat > ~/.ferrum/config.yaml << 'EOF'
mode: file

admin:
  http_port: 9000
  jwt_secret: "dev-secret-change-in-prod"

proxies:
  - name: local-api
    listen_port: 8000
    upstream_url: http://localhost:3000
    plugins:
      - name: cors
        config:
          origins: ["http://localhost:3001", "http://localhost:5173"]
          methods: [GET, POST, PUT, DELETE, OPTIONS]
          headers: [Content-Type, Authorization]
      - name: stdout_logging
        config: {}
EOF

ferrum-edge --config ~/.ferrum/config.yaml

Run as a Background Service (launchd)

On macOS, use launchd to run Ferrum Edge as a user-level background service that starts automatically on login.

xml — ~/Library/LaunchAgents/com.ferrumedge.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.ferrumedge</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/ferrum-edge</string>
    <string>--config</string>
    <string>/Users/YOUR_USER/.ferrum/config.yaml</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/ferrum-edge.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/ferrum-edge-error.log</string>
</dict>
</plist>

bash

launchctl load ~/Library/LaunchAgents/com.ferrumedge.plist
launchctl start com.ferrumedge

Build from Source

bash

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

# Install protoc via Homebrew
brew install protobuf

# Clone and build
git clone https://github.com/ferrum-edge/ferrum-edge.git
cd ferrum-edge
cargo build --release

# Install
sudo cp target/release/ferrum-edge /usr/local/bin/

Admin API Reference → Docker Install Browse Plugins