roji

A simple reverse proxy for local development environments. Automatically discovers Docker Compose services and provides HTTPS access via *.dev.localhost.

"Use the highway (Traefik) for production, take the back alley (roji) for development"

Features

• Auto-discovery: Automatically detects and routes containers on the shared network
• Auto HTTPS: Generates and installs TLS certificates with zero configuration
• Live Dashboard: Real-time route updates, request logging, and project management
• Docker Compose Operations: Start/stop/restart projects from dashboard or API
• Label-based Configuration: Customize hostnames, ports, and paths via container labels
• WebSocket & gRPC: Full bidirectional WebSocket and HTTP/2 gRPC proxying
• Request Mocking: Define mock responses via labels for frontend development
• Basic Authentication: Protect routes with username/password via labels or config
• Static File Hosting: Serve static files with directory listing
• Dev Servers on the Host: Give vite dev, wrangler dev and the like a hostname and HTTPS, next to your containers. roji run app -- npx vite --port {port} picks a free port for you
• Public Access: Publish selected routes through a Cloudflare Tunnel, opt-in per route
• Service Management: Run as system service (systemd/launchd/Windows Service)
• Environment Diagnostics: roji doctor checks and fixes common issues

Quick Start

Install roji:

# macOS
brew install kan/roji/roji

# Linux / macOS (one-liner)
curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/kan/roji/main/install.sh | bash

Add your app to the roji network:

# your-app/docker-compose.yml
services:
  myapp:
    image: your-app
    expose:
      - "3000"
    networks:
      - roji

networks:
  roji:
    external: true

Start your app and open https://myapp.dev.localhost — that's it!

For a step-by-step walkthrough, see the Getting Started guide.

Installation

Homebrew (macOS)

brew install kan/roji/roji

One-liner Install (Recommended)

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/kan/roji/main/install.sh | bash

This will:

• Download the roji binary for your platform (Linux/macOS, x86_64/arm64)
• Verify it against the release's checksums.txt, and its build provenance with gh attestation verify when the GitHub CLI is installed and logged in
• Install to ~/.local/bin by default (interactive prompt for location)
• Run roji doctor --fix to set up the environment
• Install CA certificate to system trust store
• Register and start roji as a system service

Options:

curl -fsSL ... | bash -s -- --global       # Install to /usr/local/bin
curl -fsSL ... | bash -s -- --local        # Install to ~/.local/bin (default)
curl -fsSL ... | bash -s -- --no-service   # Skip service registration
curl -fsSL ... | bash -s -- --upgrade      # Skip upgrade prompts
curl -fsSL ... | bash -s -- --version 1.2.0  # Install a specific version (or: | ROJI_VERSION=1.2.0 bash)

Upgrading

Re-run the install script. It detects existing installations and upgrades automatically:

curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/kan/roji/main/install.sh | bash

Manual Installation

Download from GitHub Releases or build from source:

git clone https://github.com/kan/roji.git && cd roji && make build
sudo ./bin/roji doctor --fix    # Set up environment
sudo ./bin/roji ca install      # Install CA certificate
sudo ./bin/roji service install && sudo ./bin/roji service start

A downloaded archive can be checked against its build provenance with the GitHub CLI, the way the installer does. Put the version you downloaded in --source-ref:

gh attestation verify roji_Linux_x86_64.tar.gz --repo kan/roji \
  --signer-workflow kan/roji/.github/workflows/release-build.yml \
  --source-ref refs/tags/vX.Y.Z

For v1.3.0, the signer workflow is kan/roji/.github/workflows/release.yml. Earlier releases carry no attestation.

Configuration

Configuration file: ~/.config/roji/config.yaml

network: roji                          # Docker network(s) to watch (comma-separated)
domain: dev.localhost                  # Base domain
bind: 127.0.0.1,::1                    # Listen address(es); empty for all interfaces
http_port: 80                          # HTTP port (redirect to HTTPS)
https_port: 443                        # HTTPS port
certs_dir: ~/.local/share/roji/certs   # Certificate directory
data_dir: ~/.local/share/roji          # Data directory
dashboard: roji.dev.localhost          # Dashboard hostname
log_level: info                        # Log level (debug, info, warn, error)
auto_cert: true                        # Auto-generate certificates

static_sites:                          # Static file hosting
  - host: docs
    root: ~/projects/docs/build

proxy_sites:                           # Dev servers running on the host
  - host: app
    target: http://localhost:5173

tunnel:                                # Public access via Cloudflare Tunnel
  domain: example.com                  # Zone on your Cloudflare account
  name: roji                           # Named tunnel to run

Routes stay private until a container opts in with roji.tunnel=true, or a site in the config file with tunnel: true. The dashboard and its API are never published. See the Public Access guide.

Manage with roji config show | path | init | edit.

Settings priority: CLI flags > Environment variables > Config file > Defaults

For full details on environment variables, Docker labels, static sites, and authentication, see the Configuration guide.

Dashboard

Access at https://roji.dev.localhost — a live dashboard with real-time route updates, request logging, Docker Compose controls, and project management. See the Dashboard documentation for details.

CLI Reference

Command	Description
roji	Start the reverse proxy server
roji doctor	Check environment and fix issues (--fix, --json)
roji config	Manage configuration (show, path, init, edit)
roji ca	Manage CA certificate (status, install, uninstall, export)
roji service	Manage system service (install, uninstall, start, stop, restart, status)
roji log	View server logs (-n, --no-follow)
roji routes	List registered routes
roji version	Show version info
roji credits	Show licenses of roji and its dependencies
roji health	Check server health

For full command reference with all flags, see the CLI Reference.

API Reference

All API endpoints are served on the dashboard host. See the API Reference for the complete list.

Troubleshooting

Start with diagnostics:

roji doctor            # Check for issues
sudo roji doctor --fix # Auto-fix where possible

This checks Docker, networking, certificates, ports, and DNS — and can fix most common problems automatically.

For platform-specific issues (WSL, macOS, Linux) and detailed solutions, see the Troubleshooting guide.

Documentation

Full documentation is available at roji-proxy.dev:

• Getting Started — Installation and first service
• Configuration Guide — Config file, labels, static sites, auth
• Public Access — Reaching selected routes from the internet
• CLI Reference — All commands and flags
• API Reference — Dashboard API endpoints
• Troubleshooting — Common issues and platform guides

Name Origin

roji means "back alley" or "narrow lane" in Japanese. The concept is to use the highway (Traefik) for production and casually take the back alley (roji) for local development.

License

MIT

Licenses of the bundled dependencies are in CREDITS (Go modules) and THIRD_PARTY_NOTICES (everything else). Both ship in the release archives and the Docker image, and roji credits prints them from the binary itself.