Daemon Commands
Inspect and operate the Gordon daemon: status, process logs, reload, configuration, TLS, traffic, and networks.
These commands target the local daemon through its owner-only socket, or the daemon selected with --remote, GORDON_REMOTE, or the active remote. See CLI Overview.
gordon daemon
| Subcommand |
Description |
status |
Show daemon status and the app fleet summary |
logs |
Show daemon process logs |
reload |
Reload installation configuration |
config show |
Show installation configuration |
config validate |
Statically validate a local configuration file |
tls |
Show public TLS certificate status |
traffic |
Show traffic entrypoint, router, and counter status |
networks |
List Gordon-managed networks |
gordon daemon status
Display installation identity plus one status line per app (from desired/active state, no container inspection). Per-service detail lives under gordon apps show APP and gordon apps status APP.
gordon daemon status
gordon daemon status --remote prod
gordon daemon status works in local mode and remote mode.
- Local mode reads status from in-process services.
- Remote mode reads status from the target admin API.
Output
Gordon Status
Gordon Domain: gordon.example.com
Registry Port: 5000
Server Port: 8088
Apps: 3
Network Isolation: false
Container Status:
blog: active
shop: deploying
old-site: stopped
| Field |
Description |
| Gordon Domain |
Public Gordon domain from configuration |
| Registry Port |
Docker registry port |
| Server Port |
Gordon admin port |
| Apps |
Total apps in desired/active state |
| Network Isolation |
Whether installation network policy is enabled |
| Container Status |
Fleet status per app (see states below) |
App States
| State |
Description |
| active |
App deployed and converged on desired state |
| deploying |
Desired state diverges from effective state |
| pending |
App applied but never deployed |
| stopped |
Durable stopped intent (stays stopped across reboot) |
Flags
Uses the global remote flags:
| Flag |
Description |
--remote, -r |
Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
--token-file |
Read the remote token from a mode 0600 file |
Environment Variables
Examples
Check Local or Remote Status
# Local
gordon daemon status
# Using a saved remote
gordon daemon status --remote prod
# Using environment variables
export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=your-token
gordon daemon status
Quick Fleet Check
# Check for non-converged apps
gordon daemon status --remote prod | grep -E "(deploying|pending|stopped)"
Required Permissions (Remote Only)
Remote status calls require admin:status:read scope in the authentication token.
# Generate token with required scope
gordon auth token generate --subject admin --scopes admin:status:read
gordon daemon logs
Display Gordon daemon process logs. Application workload output is read with
gordon apps logs APP --service SVC, which resolves the app's active container
through the daemon.
Synopsis
gordon daemon logs [options]
Options
| Option |
Short |
Default |
Description |
--config |
-c |
Auto |
Path to config file |
--follow |
-f |
false |
Follow log output (like tail -f) |
--lines |
-n |
50 |
Number of lines to show |
--remote, -r |
|
|
Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
--token-file |
|
|
Read the remote token from a mode 0600 file |
Remote targeting uses client config or an active remote by default. Use
--remote and --token-file to override. See CLI Overview.
Remote log access requires an admin token with admin:logs:read (or admin:*:*). admin:status:read is not sufficient for logs.
Examples
# Gordon process logs
gordon daemon logs # Last 50 lines
gordon daemon logs -f # Follow logs
gordon daemon logs -n 100 # Last 100 lines
gordon daemon logs -f -n 200 # Follow, starting from last 200 lines
# App service logs
gordon apps logs blog --service web
gordon apps logs blog --service web --follow --remote prod
# Remote process logs (override)
gordon daemon logs --remote prod
Log Locations
# Using gordon daemon logs
gordon daemon logs -f
# Direct file access
tail -f ~/.gordon/logs/gordon.log
# With systemd
journalctl --user -u gordon -f
# App service logs through Gordon
gordon apps logs blog --service web --tail 50
gordon apps logs blog --service web --follow
gordon daemon reload
Reload installation configuration.
Synopsis
gordon daemon reload
Description
Sends SIGUSR1 to the running Gordon process, triggering:
- Installation settings reload (live keys apply, restart-required keys are reported)
- Traffic/proxy state refresh from ACTIVE app projection
Reload never activates pending desired app state, re-resolves images, or flips intent. Obsolete application keys (routes, attachments, services, auto, previews, …) are rejected with a config-retired diagnostic before any mutation.
Example
# After editing gordon.toml, apply changes without restart
vim ~/.config/gordon/gordon.toml
gordon daemon reload
gordon daemon config show
Display the Gordon installation configuration including server settings,
network isolation, volumes, and external route domains. App routes live
under gordon apps show, never here. Sensitive filesystem paths and upstream external route targets are redacted by default.
gordon daemon config show
gordon daemon config show --json
gordon daemon config show --remote prod
Flags
| Flag |
Description |
--json |
Output as JSON |
JSON Output
{
"server": {
"port": 1111,
"registry_port": 5000,
"registry_domain": "reg.example.com"
},
"network_isolation": {
"enabled": true,
"prefix": "gordon"
},
"volumes": {
"auto_create": true,
"prefix": "gordon",
"preserve": true
},
"external_routes": [
{"domain": "reg.example.com"}
]
}
External route targets and server.data_dir are intentionally omitted from the default admin config response because they reveal internal network and filesystem layout.
gordon daemon config validate
Statically validates a candidate configuration file before it is installed.
This command is local-only: --remote is rejected. Validation is static —
runtime, ACTIVE-state, secret, pull, and listener checks are not performed.
A file that fails validation exits non-zero; --json is still written first.
gordon daemon config validate --file ./gordon.toml
gordon daemon config validate --file ./gordon.toml --json
Flags
| Flag |
Description |
--file |
Local candidate configuration file (required) |
--json |
Output as JSON |
JSON Output
On success:
{
"valid": true,
"diagnostics": [],
"scope": "static"
}
On failure, valid is false and diagnostics carries the failure:
{
"valid": false,
"diagnostics": [
{"code": "config-invalid", "key": "", "message": "configuration failed static validation"}
],
"scope": "static"
}
gordon daemon tls
Inspect public TLS/ACME certificate status.
Gordon serves normal HTTPS fallback on TLS-capable entrypoints such as entrypoints.edge with protocol = "smart_tcp". Certificate priority is static certificates first, then public ACME certificates, then Gordon's internal CA.
ACME challenge notes:
- DNS-01 (
cloudflare-dns-01) does not require a special external port 80 edge.
- HTTP-01 requires an HTTP-capable smart TCP entrypoint reachable on external port 80 for every hostname being validated.
- TLS-ALPN-01 is not supported.
Display the current public TLS/ACME certificate status, including ACME mode,
certificate details, route coverage, and any errors.
gordon daemon tls
gordon daemon tls --json
gordon daemon tls --remote prod
Flags
| Flag |
Description |
--json |
Output as JSON |
Human Output
Public TLS / ACME Status
ACME: enabled
Configured Mode: auto
Effective Mode: http-01
Reason: configured
Token Source: env
Certificates
ID: cert-abc123
Names: example.com, www.example.com
Status: valid
Not After: 2026-05-29 12:00:00
Route Coverage
example.com covered=yes covered_by=cert-abc123
internal.local covered=no error=self-signed cert
Errors
route internal.local has no ACME cert
JSON Output
{
"acme_enabled": true,
"configured_mode": "auto",
"effective_mode": "http-01",
"selection_reason": "configured",
"token_source": "env",
"certificates": [
{
"id": "cert-abc123",
"names": ["example.com", "www.example.com"],
"challenge": "http-01",
"status": "valid",
"not_after": "2026-05-29T12:00:00Z",
"renewal_pending": false
}
],
"routes": [
{
"domain": "example.com",
"covered": true,
"covered_by": "cert-abc123",
"required_acme": true
},
{
"domain": "internal.local",
"covered": false,
"required_acme": false,
"error": "self-signed cert"
}
],
"errors": ["route internal.local has no ACME cert"]
}
Token Source
The token_source field indicates where the ACME token was sourced from
(e.g., env, file, config). The token value is never displayed.
gordon daemon traffic
gordon daemon traffic --remote prod
gordon daemon traffic --remote https://gordon.example.com --json
Remote mode queries the running Gordon admin API. Local mode does not synthesize runtime traffic state from a fresh config load; use a configured remote target for authoritative counters and reload status.
Flags
| Flag |
Description |
--json |
Output machine-readable JSON |
--remote, -r |
Remote Gordon instance or saved remote name |
JSON Output
{
"last_reload_status": "ok",
"entrypoints": [
{
"name": "postgres",
"address": "0.0.0.0:5432",
"protocol": "tcp",
"active": true,
"active_tcp_connections": 1,
"active_udp_sessions": 0,
"total_accepted": 12,
"total_refused": 0,
"total_errors": 0,
"bytes_in": 4096,
"bytes_out": 8192,
"smart_tcp": {
"http_accepted": 0,
"h2c_accepted": 0,
"https_fallback_accepted": 0,
"tls_passthrough_accepted": 0,
"raw_fallback_accepted": 0,
"entrypoint_cidr_refused": 0,
"raw_fallback_cidr_refused": 0,
"proxy_refused": 0,
"unknown_no_fallback_refused": 0,
"malformed_rejected": 0,
"sniff_timeout": 0,
"client_hello_too_large": 0
}
}
],
"routers": [],
"services": [],
"counters": {
"active_tcp_connections": 1,
"active_udp_sessions": 0,
"total_accepted": 12,
"total_refused": 0,
"total_errors": 0,
"bytes_in": 4096,
"bytes_out": 8192,
"smart_tcp": {
"http_accepted": 0,
"h2c_accepted": 0,
"https_fallback_accepted": 0,
"tls_passthrough_accepted": 0,
"raw_fallback_accepted": 0,
"entrypoint_cidr_refused": 0,
"raw_fallback_cidr_refused": 0,
"proxy_refused": 0,
"unknown_no_fallback_refused": 0,
"malformed_rejected": 0,
"sniff_timeout": 0,
"client_hello_too_large": 0
}
}
}
gordon daemon networks
Display Docker networks managed by Gordon, including which containers
are connected to each network.
gordon daemon networks
gordon daemon networks --json
gordon daemon networks --remote prod
Flags
| Flag |
Description |
--json |
Output as JSON |
JSON Output
[
{
"name": "gordon_myapp",
"driver": "bridge",
"containers": ["container1", "container2"]
}
]
source
1# Daemon Commands
2
3Inspect and operate the Gordon daemon: status, process logs, reload, configuration, TLS, traffic, and networks.
4
5These commands target the local daemon through its owner-only socket, or the daemon selected with `--remote`, `GORDON_REMOTE`, or the active remote. See [CLI Overview](./index.md).
6
7## gordon daemon
8
9| Subcommand | Description |
10|------------|-------------|
11| `status` | Show daemon status and the app fleet summary |
12| `logs` | Show daemon process logs |
13| `reload` | Reload installation configuration |
14| `config show` | Show installation configuration |
15| `config validate` | Statically validate a local configuration file |
16| `tls` | Show public TLS certificate status |
17| `traffic` | Show traffic entrypoint, router, and counter status |
18| `networks` | List Gordon-managed networks |
19
20---
21
22## gordon daemon status
23
24Display installation identity plus one status line per app (from desired/active state, no container inspection). Per-service detail lives under `gordon apps show APP` and `gordon apps status APP`.
25
26```bash
27gordon daemon status
28gordon daemon status --remote prod
29```
30
31`gordon daemon status` works in local mode and remote mode.
32
33- Local mode reads status from in-process services.
34- Remote mode reads status from the target admin API.
35
36### Output
37
38```
39Gordon Status
40
41Gordon Domain: gordon.example.com
42Registry Port: 5000
43Server Port: 8088
44Apps: 3
45Network Isolation: false
46
47Container Status:
48 blog: active
49 shop: deploying
50 old-site: stopped
51```
52
53### Information Displayed
54
55| Field | Description |
56|-------|-------------|
57| Gordon Domain | Public Gordon domain from configuration |
58| Registry Port | Docker registry port |
59| Server Port | Gordon admin port |
60| Apps | Total apps in desired/active state |
61| Network Isolation | Whether installation network policy is enabled |
62| Container Status | Fleet status per app (see states below) |
63
64### App States
65
66| State | Description |
67|-------|-------------|
68| active | App deployed and converged on desired state |
69| deploying | Desired state diverges from effective state |
70| pending | App applied but never deployed |
71| stopped | Durable stopped intent (stays stopped across reboot) |
72
73### Flags
74
75Uses the global remote flags:
76
77| Flag | Description |
78|------|-------------|
79| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
80| `--token-file` | Read the remote token from a mode 0600 file |
81
82### Environment Variables
83
84| Variable | Description |
85|----------|-------------|
86| `GORDON_REMOTE` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
87| `GORDON_TOKEN` | Authentication token |
88
89### Examples
90
91### Check Local or Remote Status
92
93```bash
94# Local
95gordon daemon status
96
97# Using a saved remote
98gordon daemon status --remote prod
99
100# Using environment variables
101export GORDON_REMOTE=https://gordon.mydomain.com
102export GORDON_TOKEN=your-token
103gordon daemon status
104```
105
106### Quick Fleet Check
107
108```bash
109# Check for non-converged apps
110gordon daemon status --remote prod | grep -E "(deploying|pending|stopped)"
111```
112
113### Required Permissions (Remote Only)
114
115Remote status calls require `admin:status:read` scope in the authentication token.
116
117```bash
118# Generate token with required scope
119gordon auth token generate --subject admin --scopes admin:status:read
120```
121
122---
123
124## gordon daemon logs
125
126Display Gordon daemon process logs. Application workload output is read with
127`gordon apps logs APP --service SVC`, which resolves the app's active container
128through the daemon.
129
130### Synopsis
131
132```bash
133gordon daemon logs [options]
134```
135
136### Options
137
138| Option | Short | Default | Description |
139|--------|-------|---------|-------------|
140| `--config` | `-c` | Auto | Path to config file |
141| `--follow` | `-f` | false | Follow log output (like `tail -f`) |
142| `--lines` | `-n` | 50 | Number of lines to show |
143| `--remote, -r` | | | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
144| `--token-file` | | | Read the remote token from a mode 0600 file |
145
146Remote targeting uses client config or an active remote by default. Use
147`--remote` and `--token-file` to override. See [CLI Overview](./index.md).
148
149Remote log access requires an admin token with `admin:logs:read` (or `admin:*:*`). `admin:status:read` is not sufficient for logs.
150
151### Examples
152
153```bash
154# Gordon process logs
155gordon daemon logs # Last 50 lines
156gordon daemon logs -f # Follow logs
157gordon daemon logs -n 100 # Last 100 lines
158gordon daemon logs -f -n 200 # Follow, starting from last 200 lines
159
160# App service logs
161gordon apps logs blog --service web
162gordon apps logs blog --service web --follow --remote prod
163
164# Remote process logs (override)
165gordon daemon logs --remote prod
166```
167
168### Log Locations
169
170```bash
171# Using gordon daemon logs
172gordon daemon logs -f
173
174# Direct file access
175tail -f ~/.gordon/logs/gordon.log
176
177# With systemd
178journalctl --user -u gordon -f
179
180# App service logs through Gordon
181gordon apps logs blog --service web --tail 50
182gordon apps logs blog --service web --follow
183```
184
185---
186
187## gordon daemon reload
188
189Reload installation configuration.
190
191### Synopsis
192
193```bash
194gordon daemon reload
195```
196
197### Description
198
199Sends `SIGUSR1` to the running Gordon process, triggering:
200
201- Installation settings reload (live keys apply, restart-required keys are reported)
202- Traffic/proxy state refresh from ACTIVE app projection
203
204Reload never activates pending desired app state, re-resolves images, or flips intent. Obsolete application keys (`routes`, `attachments`, `services`, `auto`, previews, …) are rejected with a `config-retired` diagnostic before any mutation.
205
206### Example
207
208```bash
209# After editing gordon.toml, apply changes without restart
210vim ~/.config/gordon/gordon.toml
211gordon daemon reload
212```
213
214---
215
216## gordon daemon config show
217
218Display the Gordon installation configuration including server settings,
219network isolation, volumes, and external route domains. App routes live
220under `gordon apps show`, never here. Sensitive filesystem paths and upstream external route targets are redacted by default.
221
222```bash
223gordon daemon config show
224gordon daemon config show --json
225gordon daemon config show --remote prod
226```
227
228### Flags
229
230| Flag | Description |
231|------|-------------|
232| `--json` | Output as JSON |
233
234### JSON Output
235
236```json
237{
238 "server": {
239 "port": 1111,
240 "registry_port": 5000,
241 "registry_domain": "reg.example.com"
242 },
243 "network_isolation": {
244 "enabled": true,
245 "prefix": "gordon"
246 },
247 "volumes": {
248 "auto_create": true,
249 "prefix": "gordon",
250 "preserve": true
251 },
252 "external_routes": [
253 {"domain": "reg.example.com"}
254 ]
255}
256```
257
258External route targets and `server.data_dir` are intentionally omitted from the default admin config response because they reveal internal network and filesystem layout.
259
260---
261
262## gordon daemon config validate
263
264Statically validates a candidate configuration file before it is installed.
265This command is local-only: `--remote` is rejected. Validation is static —
266runtime, ACTIVE-state, secret, pull, and listener checks are not performed.
267A file that fails validation exits non-zero; `--json` is still written first.
268
269```bash
270gordon daemon config validate --file ./gordon.toml
271gordon daemon config validate --file ./gordon.toml --json
272```
273
274### Flags
275
276| Flag | Description |
277|------|-------------|
278| `--file` | Local candidate configuration file (required) |
279| `--json` | Output as JSON |
280
281### JSON Output
282
283On success:
284
285```json
286{
287 "valid": true,
288 "diagnostics": [],
289 "scope": "static"
290}
291```
292
293On failure, `valid` is `false` and `diagnostics` carries the failure:
294
295```json
296{
297 "valid": false,
298 "diagnostics": [
299 {"code": "config-invalid", "key": "", "message": "configuration failed static validation"}
300 ],
301 "scope": "static"
302}
303```
304
305---
306
307## gordon daemon tls
308
309Inspect public TLS/ACME certificate status.
310
311Gordon serves normal HTTPS fallback on TLS-capable entrypoints such as `entrypoints.edge` with `protocol = "smart_tcp"`. Certificate priority is static certificates first, then public ACME certificates, then Gordon's internal CA.
312
313ACME challenge notes:
314
315- DNS-01 (`cloudflare-dns-01`) does not require a special external port 80 edge.
316- HTTP-01 requires an HTTP-capable smart TCP entrypoint reachable on external port 80 for every hostname being validated.
317- TLS-ALPN-01 is not supported.
318
319Display the current public TLS/ACME certificate status, including ACME mode,
320certificate details, route coverage, and any errors.
321
322```bash
323gordon daemon tls
324gordon daemon tls --json
325gordon daemon tls --remote prod
326```
327
328### Flags
329
330| Flag | Description |
331|------|-------------|
332| `--json` | Output as JSON |
333
334### Human Output
335
336```text
337Public TLS / ACME Status
338
339ACME: enabled
340Configured Mode: auto
341Effective Mode: http-01
342Reason: configured
343Token Source: env
344
345Certificates
346 ID: cert-abc123
347 Names: example.com, www.example.com
348 Status: valid
349 Not After: 2026-05-29 12:00:00
350
351Route Coverage
352 example.com covered=yes covered_by=cert-abc123
353 internal.local covered=no error=self-signed cert
354
355Errors
356 route internal.local has no ACME cert
357```
358
359### JSON Output
360
361```json
362{
363 "acme_enabled": true,
364 "configured_mode": "auto",
365 "effective_mode": "http-01",
366 "selection_reason": "configured",
367 "token_source": "env",
368 "certificates": [
369 {
370 "id": "cert-abc123",
371 "names": ["example.com", "www.example.com"],
372 "challenge": "http-01",
373 "status": "valid",
374 "not_after": "2026-05-29T12:00:00Z",
375 "renewal_pending": false
376 }
377 ],
378 "routes": [
379 {
380 "domain": "example.com",
381 "covered": true,
382 "covered_by": "cert-abc123",
383 "required_acme": true
384 },
385 {
386 "domain": "internal.local",
387 "covered": false,
388 "required_acme": false,
389 "error": "self-signed cert"
390 }
391 ],
392 "errors": ["route internal.local has no ACME cert"]
393}
394```
395
396### Token Source
397
398The `token_source` field indicates where the ACME token was sourced from
399(e.g., `env`, `file`, `config`). The token value is never displayed.
400
401---
402
403## gordon daemon traffic
404
405```bash
406gordon daemon traffic --remote prod
407gordon daemon traffic --remote https://gordon.example.com --json
408```
409
410Remote mode queries the running Gordon admin API. Local mode does not synthesize runtime traffic state from a fresh config load; use a configured remote target for authoritative counters and reload status.
411
412### Flags
413
414| Flag | Description |
415|------|-------------|
416| `--json` | Output machine-readable JSON |
417| `--remote`, `-r` | Remote Gordon instance or saved remote name |
418
419### JSON Output
420
421```json
422{
423 "last_reload_status": "ok",
424 "entrypoints": [
425 {
426 "name": "postgres",
427 "address": "0.0.0.0:5432",
428 "protocol": "tcp",
429 "active": true,
430 "active_tcp_connections": 1,
431 "active_udp_sessions": 0,
432 "total_accepted": 12,
433 "total_refused": 0,
434 "total_errors": 0,
435 "bytes_in": 4096,
436 "bytes_out": 8192,
437 "smart_tcp": {
438 "http_accepted": 0,
439 "h2c_accepted": 0,
440 "https_fallback_accepted": 0,
441 "tls_passthrough_accepted": 0,
442 "raw_fallback_accepted": 0,
443 "entrypoint_cidr_refused": 0,
444 "raw_fallback_cidr_refused": 0,
445 "proxy_refused": 0,
446 "unknown_no_fallback_refused": 0,
447 "malformed_rejected": 0,
448 "sniff_timeout": 0,
449 "client_hello_too_large": 0
450 }
451 }
452 ],
453 "routers": [],
454 "services": [],
455 "counters": {
456 "active_tcp_connections": 1,
457 "active_udp_sessions": 0,
458 "total_accepted": 12,
459 "total_refused": 0,
460 "total_errors": 0,
461 "bytes_in": 4096,
462 "bytes_out": 8192,
463 "smart_tcp": {
464 "http_accepted": 0,
465 "h2c_accepted": 0,
466 "https_fallback_accepted": 0,
467 "tls_passthrough_accepted": 0,
468 "raw_fallback_accepted": 0,
469 "entrypoint_cidr_refused": 0,
470 "raw_fallback_cidr_refused": 0,
471 "proxy_refused": 0,
472 "unknown_no_fallback_refused": 0,
473 "malformed_rejected": 0,
474 "sniff_timeout": 0,
475 "client_hello_too_large": 0
476 }
477 }
478}
479```
480
481---
482
483## gordon daemon networks
484
485Display Docker networks managed by Gordon, including which containers
486are connected to each network.
487
488```bash
489gordon daemon networks
490gordon daemon networks --json
491gordon daemon networks --remote prod
492```
493
494### Flags
495
496| Flag | Description |
497|------|-------------|
498| `--json` | Output as JSON |
499
500### JSON Output
501
502```json
503[
504 {
505 "name": "gordon_myapp",
506 "driver": "bridge",
507 "containers": ["container1", "container2"]
508 }
509]
510```
511
512## Related
513
514- [CLI Overview](./index.md)
515- [Apps Commands](./apps.md)
516- [Serve Command](./serve.md)
517- [Traffic configuration](../config/traffic.md)
518- [Remote CLI Management](/wiki/guides/remote-cli.md)