Team Daemon Production Deployment
This runbook is a conservative Linux/systemd/Caddy baseline for one Team daemon
and one topology. Adapt paths and hardening to organizational policy. Team is
proprietary software and requires an active license. Never use --open in
production.
1. Verify The Release#
Obtain the platform archive and SHA256SUMS through the licensed distribution
channel. Verify the archive before extraction; do not proceed if no trusted
checksum is available. For example, on Linux x86_64:
grep ' reticle-daemon-linux-x64.tar.gz$' SHA256SUMS | sha256sum -c -
tar xzf reticle-daemon-linux-x64.tar.gzOn macOS administrative workstations, use shasum -a 256 FILE. Compare the full
archive digest out of band with the value in SHA256SUMS.
2. Create A Dedicated Identity And Paths#
The archive includes an installer that creates a non-login identity, installs the binary and unit, and initializes protected configuration paths. Run it from the extracted archive directory:
sudo ./install.shPlace the topology at /var/lib/reticle/topology.yaml, owned by reticle:reticle
and mode 0640. Treat write access as privileged because enabled custom commands
written directly to YAML can execute while daemon policy permits them.
3. Create And Protect Tokens#
Generate distinct high-entropy view and edit tokens and store them only in the service environment file and approved secret system.
openssl rand -hex 32
openssl rand -hex 32
sudo install -o root -g reticle -m 0640 /dev/null /etc/reticle/reticle.envSet these lines in /etc/reticle/reticle.env without shell quotes:
RETICLE_VIEW_TOKEN=<independent-view-token>
RETICLE_EDIT_TOKEN=<independent-edit-token>Do not put tokens in the unit command line. Browser query-token links can enter proxy logs; prefer header-bearing API/MCP clients and redact query strings.
4. Install The systemd Unit#
The packaged unit omits --allow-custom-commands. Add it to ExecStart only
when the reviewed topology needs custom checks or named actions. --check-config
validates command definitions without executing them; it does not need that
startup flag. Local commands require Unix and Bash.
[Unit]
Description=Reticle Team Daemon
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=60
StartLimitBurst=5
[Service]
Type=simple
User=reticle
Group=reticle
EnvironmentFile=/etc/reticle/reticle.env
Environment=HOME=/var/lib/reticle
StateDirectory=reticle
LogsDirectory=reticle
ConfigurationDirectory=reticle
ExecStartPre=/usr/local/bin/reticle-daemon --config /var/lib/reticle/topology.yaml --check-config
ExecStart=/usr/local/bin/reticle-daemon --bind 127.0.0.1 --port 8790 --config /var/lib/reticle/topology.yaml --audit-log /var/log/reticle/audit.jsonl
Restart=on-failure
RestartSec=5s
TimeoutStopSec=20
KillMode=control-group
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
ReadWritePaths=/var/lib/reticle /var/log/reticle
UMask=0027
[Install]
WantedBy=multi-user.targetThe installer saves this as /etc/systemd/system/reticle-daemon.service. After
setting tokens and reviewing the topology, run:
sudo systemctl daemon-reload
sudo systemctl enable --now reticle-daemon.service
sudo systemctl status reticle-daemon.serviceFurther sandboxing is encouraged but must be tested against required SSH config, known-hosts, binaries, network destinations, and local command wrappers.
5. Terminate TLS With Caddy#
Keep the daemon loopback-only. Caddy handles WebSocket proxying automatically.
map.example.com {
reverse_proxy 127.0.0.1:8790
}Validate and reload Caddy using the package's normal service procedure. Restrict network access further with firewall, VPN, or identity-aware proxy controls as required. This minimal site does not enable Caddy access logging. If access logs are required, configure and test query-string redaction before allowing browser query-token links. Reticle's shared bearer tokens do not provide transport encryption.
6. Validate Access And Boundaries#
curl --fail --header "Authorization: Bearer $RETICLE_VIEW_TOKEN" \
https://map.example.com/api/graphConfirm viewer and editor links separately. Verify that viewers cannot save,
refresh, chat, manage definitions, or invoke actions. Verify stale saves and stale
action revisions are refused. Confirm Team presents no browser terminal or ad-hoc
command path. Test each custom command under the reticle identity and restricted
SSH principal before production use.
7. Rotate Tokens#
There is no live token-reload operation. Rotation requires replacing the secret and restarting the daemon, which interrupts active connections.
- Generate a new token and distribute it through the approved secret channel.
- Replace only the corresponding value in
/etc/reticle/reticle.env. - Run
sudo systemctl restart reticle-daemon.service. - Verify the new token and verify that the old token is denied.
- Revoke browser sessions and integrations using the old token as applicable.
Rotate immediately after suspected disclosure or personnel/access changes.
8. Rotate And Review Audit JSONL#
Audit logging is opt-in and the daemon keeps the file open. After logrotate moves the file, send SIGHUP so the daemon reopens the configured path without restarting.
/var/log/reticle/audit.jsonl {
daily
rotate 30
compress
delaycompress
missingok
notifempty
create 0600 reticle reticle
su reticle reticle
postrotate
/bin/systemctl kill -s HUP reticle-daemon.service >/dev/null 2>&1 || true
endscript
}Audit records can include peer addresses, stable IDs, revisions, role and policy decisions, provider/model names, and action errors. Protect them as operational data. Reticle does not ship retention enforcement, forwarding, or alerting; test forwarding to the organization's logging system separately.
9. Backup And Restore#
Back up:
/var/lib/reticle/topology.yamland any approved adjacent configuration;/etc/reticle/reticle.envthrough the secret backup system, separately from general filesystem backups;- the systemd unit and Caddy configuration;
- retained audit JSONL according to policy;
- the installed binary and trusted checksum needed for rollback.
Do not back up the in-memory observation ring; it is transient.
Restore into protected paths with the ownership and modes above. Restore tokens through the secret system, verify the binary checksum, start the daemon, and test viewer/editor boundaries before reopening network access. A restore does not recreate transient observations.
10. Upgrade#
- Read release notes and migration guidance.
- Back up topology, unit/proxy configuration, tokens, audit records, old binary, and checksum.
- Verify the new binary checksum.
- Preserve the prior binary under a versioned backup filename.
- Stop the service, install the new binary at
/usr/local/bin/reticle-daemon, and start the service. - Verify version, graph collection, roles, stale-revision behavior, actions, and audit writes.
- Keep the prior binary until the rollback window closes.
11. Roll Back#
Stop the service, restore the prior topology if the new version changed its
format, reinstall the checksum-verified prior binary at
/usr/local/bin/reticle-daemon, and start the service. Verify access and
collection. In-memory observations are lost across the restart. Record the
rollback and preserve relevant audit/system logs.
12. Uninstall#
- Export any required topology and audit records.
- Run
sudo systemctl disable --now reticle-daemon.service. - Remove
/etc/systemd/system/reticle-daemon.serviceand runsudo systemctl daemon-reload. - Remove the Caddy site and reload Caddy.
- Remove
/usr/local/bin/reticle-daemonafter preserving licensed artifacts required by policy. - Remove
/etc/reticle,/var/lib/reticle, and/var/log/reticleonly after backup/retention approval. - Revoke tokens, remove firewall/DNS entries, and delete the
reticleuser when no owned files or processes remain.
Uninstallation does not remove copies held in backups, logs, browser session storage, or downstream systems; expire those under their own policies.