[](https://github.com/OlofBlomqvist/odd-box/actions/workflows/BuildAndTest.yml)
## ODD-BOX
A simple, cross-platform reverse proxy server tailored for local development and tinkering. Think of it as a lightweight (and more streamlined) alternative to something like IIS, but with a key difference: configuration is primarily done declaratively through structured files, rather than a graphical user interface.
It allows you to configure a list of processes to run and host them behind their own custom hostnames. Self-signed certificates for HTTPS are automatically generated when accessing a site thru the terminating proxy service the first time (cached in .odd-box-cache dir). As with most reverse-proxy servers, odd-box also supports targetting remote backend servers.
As configuration is done thru basic files (toml format) which are easy to share, it's very easy to reproduce a particular setup.
Pre-built binaries are available in the [release section](https://github.com/OlofBlomqvist/odd-box/releases).
You can also build it yourself, or install it using brew, cargo, nix or devbox; see the installation section for guidance.
## Features (incomplete list)
> See the [docs](https://odd-box.cruma.io) for details and more features.
- Cross-platform support (Windows, Linux, macOS)
- Lets-Encrypt support for automatic certificate generation
- Docker integration
- Simple configuration using TOML files
- Keep specified binaries running automatically
- Host local directories for static sites
- Support for both process-specific and global environment variables
- Proxy to remote backend servers
- Terminating proxy supporting HTTP/1.1 & HTTP2 (level 7)
- TCP tunneling for HTTP/1 and HTTPS via SNI sniffing (level 4)
- Basic round-robin load balancing for remote targets
- Automatic self-signed certificates for all hosted processes
- Built in support for rendering markdown files as html for static sites
- Administration API for programmatic control of the proxy
- Web interface for those that do not enjoy the terminal based UI
### Planned features
- Certificate management UI (web & tui)
- Traffic inspection UI (web & tui)
- Extended routing rules (ie. not just host header & sni sniffing)
- Basic statistics (process uptimes,con+req count,bytes transfered,latency etc.)
### Screenshot(s)
**odd-box v0.1.2:**
**odd-box web-ui v0.1.8:**
## Getting Started
You can generate a basic "odd-box.toml" config file to get started:
```
odd-box --init
```
The resulting file will look something like this:
```toml
#:schema https://raw.githubusercontent.com/OlofBlomqvist/odd-box/main/odd-box-schema-v3.0.json
# Global settings
version = "V3"
ip = "127.0.0.1"
http_port = 8080
tls_port = 4343
# ==========================================================
# This serves the directory where this file is located on the dir.localtest.me domain.
[[dir_server]]
host_name = "dir.localtest.me"
dir = "$cfg_dir"
# This sets up a basic reverse proxy to lobste.rs which you can reach thru the lobsters.localtest.me domain
[[remote_target]]
host_name = "lobsters.localtest.me"
backends = [
{ address = "lobste.rs", port = 443, https = true }
]
# This will spin up a python http server in the root directory of the config file (where this file is) -
# you can reach it thru the py.localtest.me domain.
[[hosted_process]]
host_name = "py.localtest.me"
bin = "python"
auto_start = false
args = ["-m", "http.server", "$port"]
# Example for running a docker container
[[hosted_process]]
host_name = "nginx.localhost"
bin = "podman"
args = [
"run",
"--replace",
"--quiet",
"-p$port:80", # incoming $port is handled by odd-box
"nginx" # <-- image name
]
# oh and you can ofc also host processes that dont actually listen to a port
# but you just want to keep running :)
```
From here, you can either open up the config file in your favorite editor, or just run odd-box and open your browser going to https://localhost:4343 where you can configure odd-box thru its web-interface.
## Documentation
For more in depth guidance on using odd-box, see the [documentation](https://odd-box.cruma.io).
