Skip to content
Projects
Groups
Snippets
Help
This project
Loading...
Sign in / Register
Toggle navigation
D
devname
Overview
Overview
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Charts
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
PLN
devname
Commits
6a7c7ed4
Commit
6a7c7ed4
authored
Nov 12, 2026
by
PLN (Algolia)
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
README: document Linux, Arch and Ubuntu setup, the LAN face and the new commands
parent
c57e079d
Hide whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
74 additions
and
14 deletions
+74
-14
README.md
README.md
+74
-14
No files found.
README.md
View file @
6a7c7ed4
...
...
@@ -23,13 +23,23 @@ setup — no `/etc/hosts`, no resolver config, no mDNS (`.local` collides with
Bonjour). Names are local-program-only
**by construction**
: the generated
Caddyfile aborts every connection whose source is not loopback, so nothing
leaks onto the LAN even though the proxy binds the wildcard (the only way an
unprivileged process can bind a low port on macOS).
unprivileged process can bind a low port on macOS; on Linux the
unprivileged-port sysctl opens low ports to every local process, so the guard
matters there too).
## Install
Requirements: macOS or Linux,
[
Caddy
](
https://caddyserver.com
)
, Python 3.
For https:
[
mkcert
](
https://github.com/FiloSottile/mkcert
)
with a trusted root
(
`mkcert -install`
).
Requirements: macOS, Linux (Ubuntu, Debian, Arch, Fedora, others), or any Unix
that can run a foreground process;
[
Caddy
](
https://caddyserver.com
)
; Python
3.
9+ with the standard library only. For https:
[
mkcert
](
https://github.com/FiloSottile/mkcert
)
with a trusted root
(
`TRUST_STORES=system,nss mkcert -install`
: skipping the Java store avoids an
exit 1 when no JDK keystore exists).
All OS specifics live in one platform layer.
`devname doctor`
names the
platform it detected and, for every failing check, prints the exact command
to fix it (brew, apt, pacman, dnf, sysctl, setcap, systemctl). It never runs
them.
```
bash
git clone https://git.nech.pl/pln/devname.git
&&
cd
devname
...
...
@@ -46,26 +56,45 @@ runs `devname serve`: Caddy as a supervised child plus the index server.
macOS lets an unprivileged process bind a low port only on the wildcard
address, which is exactly what devname does — no privileges needed.
### Linux
—
systemd (user unit)
### Linux
:
systemd (user unit)
`devname agent install`
writes
`~/.config/systemd/user/devname.service`
and
starts it
— no root for the daemon itself
:
starts it
. The daemon itself needs no root
:
```
bash
devname agent install
--print
# preview the unit; writes and starts nothing
devname agent install
# unit + daemon-reload + enable --now
devname agent status
# is-active
devname agent status
# active / not active
devname agent restart
# also: uninstall
loginctl enable-linger
$USER
# optional: run at boot without a login session
journalctl
--user
-u
devname.service
```
The unit runs the system
`python3`
with
`Restart=on-failure`
,
`RestartSec=5`
and a 5-starts-in-120-s limit, so a broken setup stops instead of looping
forever. Install refuses (unless
`--force`
) when the unit would crash-loop:
caddy missing, low ports closed, or a system caddy holding :80.
Binding
`:80`
/
`:443`
as an unprivileged user needs one of (pick one, once):
```
bash
sudo
sysctl net.ipv4.ip_unprivileged_port_start
=
80
# or 0
sudo
setcap
cap_net_bind_service
=
+ep
"
$(
command
-v
caddy
)
"
# survives caddy upgrades; opens ports 80-1023 to every local user
echo
'net.ipv4.ip_unprivileged_port_start=80'
|
sudo
tee /etc/sysctl.d/60-devname-low-ports.conf
sudo
sysctl
-p
/etc/sysctl.d/60-devname-low-ports.conf
# or: only caddy, but a package upgrade of caddy drops it
sudo
setcap
cap_net_bind_service
=
+ep
"
$(
readlink
-f
"
$(
command
-v
caddy
)
"
)
"
```
`*.localhost`
resolves to loopback through systemd-resolved (most distros);
without it, add the names to
`/etc/hosts`
yourself.
Debian and Ubuntu:
`apt install caddy`
(distro archive or the Caddy apt repo)
also enables and starts a
**system**
`caddy.service`
on :80, which collides.
Turn it off:
`sudo systemctl disable --now caddy`
. For https add
`libnss3-tools`
next to
`mkcert`
(Firefox/Chrome trust). Arch:
`pacman -S caddy
mkcert nss`
.
`*.localhost`
must resolve to loopback for curl, Python and agents (browsers
hard-wire it and prove nothing).
`doctor`
checks it with
`getaddrinfo`
.
systemd-resolved answers it on most distros; otherwise add
`myhostname`
to the
`hosts:`
line of
`/etc/nsswitch.conf`
, or list the names in
`/etc/hosts`
.
### Other inits
...
...
@@ -76,19 +105,46 @@ Caddyfile, starts Caddy, serves the index page, and cleans up on SIGTERM.
## Commands
```
devname ensure [project] [--service S
] [--branch B|auto] [--port N
] [--keep-host] [--format url|port|json]
devname ensure [project] [--service S
|'*'] [--branch B|auto] [--port N] [--alias
] [--keep-host] [--format url|port|json]
devname ls [--json] devname rm <host> devname check <host>
devname gc [--idle-hours N] [--yes] (stale names; dry-run by default)
devname render devname serve devname doctor
devname agent install|
status
devname agent install|
uninstall|status|restart [--print] [--force]
```
-
`<project>.localhost`
— the project's main site
-
`<service>.<project>.localhost`
— a sub-service (
`tests.leboard.localhost`
)
-
`<name>--<branch>[.<project>].localhost`
— a branch variant; a worktree never
collides with the main checkout
-
`*.<project>.localhost`
(
`--service '*' --port N`
): one server routing any
single-label subdomain by Host;
`--alias --port N`
puts another name on an
already-registered port
The agent also serves the
**index page**
(
`devname.localhost`
): every
registered name with live up/down status, probed per request, plus
`/json`
.
registered name with live up/down status, plus
`/json`
. A poller probes every
name once a minute through the proxy and keeps 14 days of history, so the page
shows 24 h availability, 5xx count, p50/p95 latency and a 24 h / 14 d strip.
## LAN face (optional)
While an ssh handshake with a trusted host succeeds (
`ssh <gate> true`
with
BatchMode, so the gate's pinned host key is the proof), every name also
answers as
`<name>.<lan host>.local`
over https for phones on the home wifi,
with a private-range guard instead of the loopback one. If the gate fails or
there is no mDNS announcer, nothing is announced, Caddy gets no LAN blocks,
and loopback is untouched.
`http://<lan host>.local/CA`
serves the mkcert root
over plain http so a phone that trusts nothing yet can fetch it.
-
Announcer:
`dns-sd -P`
on macOS,
`avahi-publish -a -R`
on Linux (needs
avahi-daemon and avahi-utils).
-
`<lan host>`
:
`$DEVNAME_LAN_HOST`
, else
`lan_host`
in
`$DEVNAME_HOME/config.json`
, else
`mac`
on macOS and the short hostname
elsewhere (avahi already announces that one, so devname never re-announces
it).
-
Gate host:
`lan_gate_ssh`
in the same file (default
`domovoy-admin`
).
-
The LAN address is the kernel's route source toward the mDNS group, RFC 1918
only: a VPN address is never advertised.
-
Firewalls:
`doctor`
prints the socketfilterfw, ufw or firewalld commands.
## For agents
...
...
@@ -110,6 +166,10 @@ The registry is a flat `names.json` (`$DEVNAME_HOME`, default
python3
-m
unittest discover tests
```
Every platform branch (launchd, systemd, other Unix, avahi, dns-sd, the
low-port and system-caddy checks) is covered with mocks, so the suite runs on
any OS without root, caddy or network.
## License
GPL-3.0-only — see
[
LICENSE
](
LICENSE
)
.
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment