1# AI Agent Deployment Guide
2
3Use Gordon's declarative app workflow. Do not edit daemon state or infer workload identity from domains.
4
5## Required files
6
7```text
8~/.config/gordon/gordon.toml  # Daemon configuration
9app.toml                      # Declarative app manifest
10```
11
12## Workflow
13
141. Define services, routes, networks, volumes, secrets, readiness, and backups in `app.toml`.
152. Validate and persist the manifest:
16
17   ```bash
18   gordon apps apply --file app.toml
19   ```
20
213. Register required secret values without placing them in the manifest:
22
23   ```bash
24   gordon apps secrets set APP --service SERVICE KEY
25   ```
26
274. Deploy the accepted revision:
28
29   ```bash
30   gordon apps deploy APP
31   ```
32
335. Verify state and workload logs:
34
35   ```bash
36   gordon apps show APP
37   gordon apps logs APP --service SERVICE
38   ```
39
40The local CLI uses the authenticated owner-only Unix socket. To target another Gordon instance, use the configured authenticated HTTP/TLS remote transport.
41
42## Registry authentication
43
44Generate a scoped token on the server, then pass it to the registry client through standard input. Never place tokens in manifests, command history, fixtures, or logs.
45
46## Safety rules
47
48- Use app and service names as workload identity; domains are routing addresses only.
49- Keep secret values outside manifests and app state.
50- Reuse the same idempotency key only to inspect or retry the same mutation request.
51- Do not delete retained volumes or secrets during app removal.