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. |
| Sharing a route with colleagues | explanation | proximo.share: who can reach a shared route, what the team's mesh must provide, taking part, and the team root and intermediates. |
| Setting up sharing for a team | how-to | The steps, in order: roles, the team root, the mesh, enrolling a colleague and a sharing machine, sharing a page, checking it, stopping. |
| 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
0010 — Peer certificates come from a name-constrained team root
0011 — A shared route answers on two peer names, derived from its local hosts
0012 — A peer host is answered without rewriting Host
0013 — proximo's DNS server answers the peer subtree
0014 — The stack listens on the loopback
Requirements ·
Step 1 — install the binary ·
Step 2 — one-time host setup ·
What install changes on your host ·
State home (~/.proximo) ·
Uninstall ·
Next
Running under sudo ·
proximo install ·
proximo up ·
proximo down ·
proximo update ·
proximo trust ·
proximo status ·
proximo doctor ·
proximo errors ·
proximo errors transcript ·
proximo config tld ·
proximo config subnet ·
proximo config ca-path ·
proximo config inventory-dir ·
proximo config machine ·
proximo config peer-suffix ·
proximo config address ·
proximo config team-root ·
proximo config csr ·
proximo config intermediate ·
proximo config mesh-remedy ·
proximo config unset ·
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 · Peer sharing · 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.share — share a route with colleagues ·
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
Scope and assumptions · Constraints · Who can reach a shared route · What the mesh must provide · Taking part · The team root and the intermediates · Limits for whoever runs the team · Appendix — one transport that satisfies the requirements
Who does what · Once per team: the team root · Once per team: the mesh · Enrolling a colleague · Enrolling a sharing machine · Sharing a page · Checking it end to end · Stopping
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 ·
proximo was run under sudo ·
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 ·
A container cannot reach an address your host can ·
Degraded stack ·
The stack runs an overridden image ·
The stack image cannot be pulled ·
The agent skill is out of date ·
A shared link does not resolve or times out ·
A shared link lands on a .test address that does not resolve ·
Login on a shared link does not stick ·
A shared link answers 404 ·
A colleague sees a certificate error on a shared link ·
A shared link is slow ·
A shared route is not served on its peer names ·
proximo does not answer on the mesh address ·
This machine's peer names do not resolve ·
A publishing machine is not a resolving peer ·
The machine's intermediate is about to expire
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.