proximo makes any running Docker container reachable at
https://<name>.test — with automatic local DNS and a trusted HTTPS
certificate — on macOS and Linux. No per-container published ports, no
/etc/hosts edits, no long-running host daemon.
This folder is the full guide, and this page is the canonical section-level
map of it — every ## section of every guide is linked below.
Editors: GitHub anchors are generated from headings, so renaming a heading breaks links — and when you add a
##section to a guide, add it to this map. Both directions are a test, not a habit:internal/skill/docsindex_test.gofails when a section is missing from this map or this map links a heading that is gone. CI link-checks every anchor too.
| Guide | Type | What it covers |
|---|---|---|
| Installation | how-to | Requirements, install on macOS/Linux, exactly what is changed on your host, and how to fully reverse it. |
| CLI reference | reference | Every proximo command, what it does, and example sessions. |
| Updating | how-to | Keeping the stack in lockstep with the CLI: the published stack image, proximo update, skew detection, and how updates apply. |
| Architecture | explanation | How it works under the hood: the embedded stack, the DNS server, the local CA and trust, the watcher. |
| Routing | reference | How to expose a container: the proximo.* labels, port auto-detection, multiple hosts, and native Traefik compatibility. |
| Dev-time observability | how-to | The opt-in up --observability logs (Dozzle) + metrics (Beszel) dashboards — credential-less and no-secret. |
| The agent skill | how-to | The Skill proximo ships to coding agents: installing it, the Managed copy that keeps it level with the binary, and what it knows. |
| Troubleshooting | how-to | Common issues, one anchored section per failure mode. |
| Development | how-to | Contributing: build/test from source, local stack builds (PROXIMO_SRC), versioning, embedded assets, releases and the stack image pipeline. |
The project's glossary: the terms proximo uses and the ones it deliberately avoids. Normative — a term with no implementation is marked as a declared debt, not described as if it worked. Read it before naming anything new.
Why a design is the way it is, and what was rejected on the way.
0001 — Client reports are captured by a proximo hop that rewrites the response
0002 — The stack's Go services ship as one published image, pinned to the CLI version
0003 — Every route answers on a qualified host
0004 — Checks are a first-class concept, with a report and a remedy
0005 — The agent skill ships in the CLI, and the CLI keeps it current
0006 — The Transcript is quoted, never stored
0007 — proximo remembers what the runtime declares, never what the project wrote
0008 — proximo measures, the project concludes
0009 — The stack declares its own address space
Requirements ·
Step 1 — install the binary ·
Step 2 — one-time host setup ·
What install changes on your host ·
State home (~/.proximo) ·
Uninstall ·
Next
proximo install ·
proximo up ·
proximo down ·
proximo update ·
proximo trust ·
proximo status ·
proximo doctor ·
proximo errors ·
proximo errors transcript ·
proximo config tld ·
proximo config ca-path ·
proximo skill install ·
proximo skill uninstall ·
proximo uninstall ·
proximo version ·
Typical sessions
Mental model ·
proximo update ·
Running a different image ·
When does an update apply? ·
Linux
The big picture · The CLI is a one-shot orchestrator · The stack: four services · DNS · TLS and trust · The watcher · Source map
The proximo labels ·
The two hosts every route gets ·
proximo.hosts — opt in and pick the host(s) ·
proximo.port — usually you can omit it ·
proximo.enable — temporary opt-out ·
proximo.redirect — opt in to the HTTP→HTTPS redirect ·
proximo.health — wait for the container to be healthy ·
proximo.path — split one host across containers ·
proximo middlewares — auth, CORS, custom headers ·
proximo.inspect — see what the browser saw ·
proximo.tcp.port — route TCP services by name (SNI) ·
Round-robin across replicas ·
What happens behind the scenes ·
Native Traefik labels (backward compatible) ·
Multiple networks ·
Quick reference
Start it · How it is wired · Credential-less access (local only) · No hardcoded secret · Tear it down · Logs, metrics & retention · Transcripts — what the container said · Incidents — what the runtime declared · Readings — what the runtime says right now · Inspection — what the browser saw · Notes & limits
Install it · Managed and unmanaged copies · What the Skill knows · Without the binary
The Docker daemon is not reachable · proximo is not installed on this host · DNS name does not resolve · DNS port already in use · Port 443 or 80 already in use · macOS UDP forwarding · Certificate warnings in Firefox or Chrome · Traefik logs failed to find any PEM data · macOS Gatekeeper blocks the binary · Where to read watcher warnings · Container not routed · A host collision is reported · 502/503 right after a container restarts · An error I typed in the browser console never shows up · proximo errors shows nothing at all · proximo errors reports no Incident · A transcript is empty or says the container is gone · proximo errors shows nothing for an inspected route · An inspected route 404s on part of my app · VPN or corporate DNS overrides the resolver · Degraded stack · The stack runs an overridden image · The stack image cannot be pulled · The agent skill is out of date
Build and test ·
Lifecycle targets ·
Local source builds (PROXIMO_SRC) ·
Version and image ref ·
Embedded stack assets ·
The published skill (skills/) ·
The docs section map ·
The injected agent ·
Releases
The install-label-open walkthrough lives in the README quick start; the mental model (one-shot CLI, no daemon, DNS + TLS produced natively in Go, opt-in routing) is in Architecture — The CLI is a one-shot orchestrator and The big picture.