Getting Started

Requirements

Requirement	Minimum	Recommended
Linux kernel	5.10	6.1+
`curl` and `sudo`	latest	latest
`sha256sum`	available	from coreutils
Redis (optional)	6.0	7.x — only needed for cluster-wide rate limiting

Kernel 6.1+ is recommended for multishot accept and SQPOLL stability. Check your version:

uname -r

Step 1 — Install Arc (recommended)

curl -fsSL https://raw.githubusercontent.com/shuakami/Arc/master/install.sh | sh
arc-gateway --help

The installer script downloads the latest GitHub Release, verifies SHA256, and installs arc-gateway to /usr/local/bin/arc-gateway. It currently supports Linux x86_64 and Linux arm64.

Step 2 — Write a minimal config

Arc accepts JSON, TOML, or YAML, detected by file extension. Create arc.yaml:

node:
  workers: 0          # 0 = auto-detect CPU count from available_parallelism()
  read_timeout: 30s
  write_timeout: 30s
  idle_timeout: 60s

listeners:
  - name: http
    kind: http
    bind: "0.0.0.0:8080"

observability:
  metrics_bind: "127.0.0.1:9090"

upstreams:
  - name: app
    discovery:
      type: static
      endpoints:
        - address: "127.0.0.1:3000"
    pool:
      max_idle: 128
      idle_ttl: 30s

routes:
  - name: root
    match:
      path: "/{*rest}"
    action:
      upstream: app

Step 3 — Start a test backend

Any HTTP server on port 3000 works. Python’s built-in server is enough for testing:

python3 -m http.server 3000 &

Step 4 — Run Arc

arc-gateway --config arc.yaml

Step 5 — Verify

# Proxied response from the backend
curl -i http://localhost:8080/

# Health check
curl http://localhost:9090/healthz
# Expected: ok

# Prometheus metrics
curl http://localhost:9090/metrics
# Look for: arc_requests_total, arc_active_current

Add rate limiting

Rate limits use GCRA (Generic Cell Rate Algorithm). Add a rate_limit block to any route:

routes:
  - name: api
    match:
      path: /api/{*rest}
    action:
      upstream: app
    rate_limit:
      qps: 100
      burst: 200
      key:
        by: client_ip

Save the file. Arc watches for config changes and applies them within ~500 ms without dropping connections.

Add TLS

Generate or obtain a certificate, then add a TLS listener:

listeners:
  - name: https
    kind: https
    bind: "0.0.0.0:8443"
    tls:
      certificates:
        - sni: example.com
          cert_pem: ./certs/example.com.crt
          key_pem: ./certs/example.com.key

Certificate files are read at startup and re-read on hot reload. For automatic certificate issuance, see TLS & Certificates.

Add ACME (Let’s Encrypt)

listeners:
  - name: https
    kind: https
    bind: "0.0.0.0:8443"
    tls:
      acme:
        email: you@example.com
        domains: [example.com]
        account_key:
          algorithm: ed25519
          encrypted_key_path: ./acme-key.enc
          passphrase:
            type: env
            name: ACME_KEY_PASSPHRASE
        challenge:
          type: tls_alpn_01
          listener: https

Hot reload

Arc monitors config file modification times. After any change:

# via systemd
systemctl reload arc-gateway

# directly
kill -HUP $(pidof arc-gateway)

Changes to listener addresses, worker count, io_uring ring sizing, or control plane binding require a process restart. All other changes (routes, upstreams, rate limits, TLS certs, plugins) apply live.

Troubleshooting

Arc starts but `curl http://localhost:8080/` returns a connection refused

Check that the listener bind address and port match what you are curling. If you bound to 127.0.0.1:8080 you cannot reach it from another machine.

io_uring: Operation not permitted

io_uring requires Linux 5.10+. On kernels between 5.10 and 5.19, some SQPOLL operations may require elevated privileges. Set RLIMIT_MEMLOCK or run with CAP_SYS_ADMIN. In containers, ensure seccomp does not block io_uring syscalls.

/healthz returns 401 Unauthorized

The control plane auth_token is set but the request does not include it. Add the header: curl -H "Authorization: Bearer <token>" http://localhost:22100/healthz.

Config change is not taking effect

Confirm the mtime of the file changed (some editors write to a temp file and rename). Send SIGHUP manually: kill -HUP $(pidof arc-gateway). Check arc_config_reload_total in /metrics to confirm a reload fired.

TLS: certificate not served for a domain

Ensure the sni field in certificates exactly matches the hostname (or uses a wildcard like *.example.com). The first certificate in the array is the default fallback when no SNI matches.

ACME: challenge validation fails

TLS-ALPN-01 requires port 443 to be reachable. HTTP-01 requires port 80. Check firewall rules and that the listener bind address is publicly routable. ACME errors are written to the access log with kind: "system".

Next steps

Configuration

Every config field explained.

Security

XDP, rate limiting, L7 protection.

Deployment

Systemd and Kubernetes guides.

Observability

Metrics, logs, tracing.

Getting started

Operations

Reference

Getting Started

Requirements

Step 1 — Install Arc (recommended)

Step 2 — Write a minimal config

Step 3 — Start a test backend

Step 4 — Run Arc

Step 5 — Verify

Add rate limiting

Add TLS

Add ACME (Let’s Encrypt)

Hot reload

Troubleshooting

Next steps

Configuration

Security

Deployment

Observability

​Requirements

​Step 1 — Install Arc (recommended)

​Step 2 — Write a minimal config

​Step 3 — Start a test backend

​Step 4 — Run Arc

​Step 5 — Verify

​Add rate limiting

​Add TLS

​Add ACME (Let’s Encrypt)

​Hot reload

​Troubleshooting

​Next steps

Configuration

Security

Deployment

Observability

Requirements

Step 1 — Install Arc (recommended)

Step 2 — Write a minimal config

Step 3 — Start a test backend

Step 4 — Run Arc

Step 5 — Verify

Add rate limiting

Add TLS

Add ACME (Let’s Encrypt)

Hot reload

Troubleshooting

Next steps