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, a
site in the config file with tunnel: true, or tunnel.routes lists the
hostname. The dashboard and its API are never published. See the
Public Access guide.
Settings that differ between machines go in local.yaml next to
config.yaml, which is read on top of it. A config.yaml shared through
dotfiles can then stay the same everywhere:
# ~/.config/roji/local.yaml (this machine only)
tunnel:
name: auto # roji-<hostname>; or write the tunnel's name
routes: [web] # publish web.{domain} from this machine
Manage with roji config show | path | init | edit | reload.
Settings priority: CLI flags > Environment variables > local.yaml > 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:
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.