proximo

command module
v0.16.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2026 License: MIT Imports: 1 Imported by: 0

README ΒΆ

proximo

Make any running Docker container reachable at https://<name>.test β€” with automatic local DNS and trusted HTTPS β€” on macOS and Linux. No per-container published ports, no /etc/hosts edits.

proximo gives you automatic Host-based routing plus the two things that are usually left to you: local DNS and a trusted certificate. The only mandatory prerequisite is Docker; DNS and certificates are produced natively in Go.

Documentation

πŸ“– Read the full guide β€” the docs below, rendered and searchable.

Full guides live in docs/:

  • Installation β€” requirements, install steps, what it changes on your host, and how to reverse it.
  • CLI reference β€” every command with examples.
  • Updating β€” proximo update, skew detection, and how updates apply to the stack.
  • Architecture β€” the stack, DNS, the local CA, the watcher.
  • Routing β€” the proximo.* labels, the two hosts every route gets, and Traefik compatibility.
  • Dev-time observability β€” opt-in up --observability logs (Dozzle) + metrics (Beszel) dashboards: credential-less and over trusted HTTPS (http:// auto-redirects). Also Inspection: label a container proximo.inspect=true and proximo errors shows what the browser reported alongside the response that caused it. Chrome is the supported browser β€” other engines are likely to work and are not tested.
  • The agent skill β€” proximo skill install puts a Skill in your repository (or your home) that teaches Claude Code and Codex the label contract and how to diagnose a broken route. It ships inside the binary, so the version an agent reads is always the one you have installed.
  • Troubleshooting β€” common issues. Something broken? proximo doctor reports every check on the host and hands back the exact command to run for each failure. Container labeled but unreachable? Start with the container not routed checklist.
  • Development β€” building, testing from source, versioning, releases.

Quick start

Install the binary (macOS via Homebrew; Linux via release binary or go install β€” see Installation):

brew install filippolmt/tap/proximo          # macOS
go install github.com/filippolmt/proximo@latest   # Linux/from source

One-time host setup (CA, resolver, trust, and the stack β€” needs sudo once):

proximo install

Label any container with the host you want, then bring it up:

# docker-compose.yml
services:
  whoami:
    image: traefik/whoami
    labels:
      - "proximo.hosts=whoami.test"   # the port is auto-detected (single EXPOSE)
docker compose up -d
open https://whoami.test   # macOS β€” trusted HTTPS, no warning
proximo status             # see what's routed
open https://traefik.test  # Traefik's own dashboard, always on (traefik.<tld> is reserved)

Every route also answers on a qualified host β€” the Compose project name inserted before the TLD, so whoami.test in project shop is served at whoami.shop.test too. It is never taken by another container, which makes it the name to put in a README or an .env; proximo status prints it beside the short one. See the two hosts every route gets.

A ready-to-run sample is in examples/whoami/. For the label contract (multiple hosts, explicit port, opt-out, native Traefik labels) see the routing label table. If something does not work, the troubleshooting checklist walks through the usual causes.

Development

No local Go toolchain is required β€” every Make target runs Go inside the golang image, so Docker is the only prerequisite:

make build      # build bin/proximo-<os>-<arch> for the host (Go runs in Docker)
make test       # run the test suite

Everything else β€” all Make targets, the lifecycle targets, running the stack from local source (PROXIMO_SRC), versioning, embedded assets, releases β€” is in the development guide.

License

MIT β€” free to use, modify, and distribute.

Documentation ΒΆ

Overview ΒΆ

Command proximo is a local development reverse proxy that makes any running Docker container reachable at https://<name>.<tld> with automatic DNS and trusted HTTPS, on macOS and Linux.

Directories ΒΆ

Path Synopsis
cmd
dnsserver command
Command dnsserver is the wildcard DNS server that runs inside the proximo stack.
Command dnsserver is the wildcard DNS server that runs inside the proximo stack.
inspector command
Command inspector is the proximo hop that serves routes under Inspection.
Command inspector is the proximo hop that serves routes under Inspection.
watcher command
Command watcher runs inside the proximo stack and keeps the Traefik container attached to the Docker networks of routed containers across their lifecycle.
Command watcher runs inside the proximo stack and keeps the Traefik container attached to the Docker networks of routed containers across their lifecycle.
hack
nameconstraints command
Command nameconstraints mints the X.509 name-constraint fixtures that the "Two machines, proved by hand" proof needs, serves them over TLS so a real browser can be pointed at them, and verifies them with Go's own crypto/x509.
Command nameconstraints mints the X.509 name-constraint fixtures that the "Two machines, proved by hand" proof needs, serves them over TLS so a real browser can be pointed at them, and verifies them with Go's own crypto/x509.
internal
checks
Package checks verifies the environment proximo needs, one independently verifiable statement at a time, and collects the outcomes into one Report.
Package checks verifies the environment proximo needs, one independently verifiable statement at a time, and collects the outcomes into one Report.
cli
Package cli implements the proximo command surface.
Package cli implements the proximo command surface.
config
Package config manages proximo's persisted user configuration and the on-disk paths it uses (TLS material, the embedded stack, etc.).
Package config manages proximo's persisted user configuration and the on-disk paths it uses (TLS material, the embedded stack, etc.).
dns
Package dns implements the wildcard DNS server and the host-resolver wiring that route the configured TLD to the local proximo.
Package dns implements the wildcard DNS server and the host-resolver wiring that route the configured TLD to the local proximo.
docker
Package docker materializes and drives the embedded reverse-proxy stack (Traefik + DNS server + network watcher) via `docker compose`, and hosts the network-attach watcher used inside the stack.
Package docker materializes and drives the embedded reverse-proxy stack (Traefik + DNS server + network watcher) via `docker compose`, and hosts the network-attach watcher used inside the stack.
inspect
Package inspect implements the proximo hop that sits in front of routes under Inspection: it proxies to the backend, injects the reporting agent into HTML responses, ingests what the agent sends back, and keeps the resulting Exchanges in memory.
Package inspect implements the proximo hop that sits in front of routes under Inspection: it proxies to the backend, injects the reporting agent into HTML responses, ingests what the agent sends back, and keeps the resulting Exchanges in memory.
observability
Package observability bootstraps the opt-in dev-time observability stack (Dozzle logs + Beszel metrics hub/agent).
Package observability bootstraps the opt-in dev-time observability stack (Dozzle logs + Beszel metrics hub/agent).
platform
Package platform provides OS / package-manager detection and the small set of privileged and unprivileged host operations the CLI relies on.
Package platform provides OS / package-manager detection and the small set of privileged and unprivileged host operations the CLI relies on.
skill
Package skill installs the agent Skill proximo ships, and reports how every installed copy stands against the binary that would write it.
Package skill installs the agent Skill proximo ships, and reports how every installed copy stands against the binary that would write it.
tls
Package tls generates the local CA and wildcard certificate (via crypto/x509) and installs/removes trust in the system and NSS stores.
Package tls generates the local CA and wildcard certificate (via crypto/x509) and installs/removes trust in the system and NSS stores.
transcript
Package transcript reads back what a Project's own container wrote while an Exchange was live.
Package transcript reads back what a Project's own container wrote while an Exchange was live.
version
Package version holds build metadata injected at release time via -ldflags.
Package version holds build metadata injected at release time via -ldflags.
Package skills holds what proximo publishes to coding agents.
Package skills holds what proximo publishes to coding agents.
tools
team-ca command
Command team-ca is the custodian's half of the peer-sharing ceremony (docs/sharing.md#the-team-root-and-the-intermediates).
Command team-ca is the custodian's half of the peer-sharing ceremony (docs/sharing.md#the-team-root-and-the-intermediates).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL