Production Quickstart

From a fresh install to a production-hardened LatchGate instance. The primary workflow uses the operator TUI — a single interactive terminal where you configure principals, policy, secrets, webhooks, and run diagnostics. CLI equivalents are shown alongside for scripting and CI.

Prerequisites

• LatchGate installed (brew install latchgate-ai/tap/latchgate or binary install)
• Linux host with UDS support
• sops and age on $PATH (for secrets — brew install sops age)

For HA replay protection, add:

• Redis instance (managed or self-hosted, with appendonly yes)

For external policy evaluation, add:

• OPA instance with the LatchGate policy bundle loaded

For defense-in-depth egress control, add:

• Squid forward proxy (strongly recommended when using actions with egress.profile = proxy_allowlist)

Without Redis and OPA, the gate uses SQLite state and the embedded regorus policy engine — production-grade for single-instance deployments.

1. Scaffold the project

mkdir /opt/latchgate && cd /opt/latchgate
latchgate init --preset lockdown

This generates latchgate.toml, action manifests, operator credentials, and an audit ledger directory. Save the api_key displayed at the end — it is shown once and never logged.

2. Launch the TUI

latchgate tui

The TUI connects to the gate’s admin socket. From here, switch to the Setup screen (6) — it is the control center for the next several steps.

CLI alternative

Every TUI operation has a CLI equivalent. Steps below show both. Use whichever fits — the TUI for interactive sessions, the CLI for scripts and CI.

3. Configure infrastructure

From the Setup screen’s Overview sub-tab (6 → 1), press s to set config values:

• public_base_url → https://gate.internal.example.com

If using external backends (recommended for HA):

• redis_url → redis://redis.internal:6379
• opa_url → http://opa.internal:8181
• egress_proxy_url → http://squid.internal:3128

Without redis_url, the gate uses SQLite state and in-memory replay (single-instance). Without opa_url, the gate uses the embedded regorus policy engine. Without egress_proxy_url, actions with proxy_allowlist use kernel-only enforcement with a startup warning.

Override UDS paths if the defaults don’t fit your environment (listen_uds_path, listen_admin_uds_path).

CLI equivalent

latchgate config set public_base_url "https://gate.internal.example.com"
# Optional — for HA / defense-in-depth:
latchgate config set redis_url "redis://redis.internal:6379"
latchgate config set opa_url "http://opa.internal:8181"
latchgate config set egress_proxy_url "http://squid.internal:3128"

4. Add principals (identity)

Switch to Setup > Principals sub-tab (6 → 3). Press a to add each principal — the form prompts for UID, name, scopes, and owner.

Map Unix UIDs to named principals. Each principal gets specific scopes that control what they can do.

CLI equivalent

latchgate config add-principal --uid 1001 --name agent-support \
  --scopes tools:call --owner alice@company.com
latchgate config add-principal --uid 1002 --name agent-ops \
  --scopes tools:call --owner bob@company.com

5. Grant actions (policy)

Switch to the Setup screen, Principals sub-tab (6 → 3). Select a principal, press g to grant actions. Action IDs are validated against manifests — typos are caught immediately.

Sinks are auto-derived from action manifests’ declared_side_effects — you never set them manually.

CLI equivalent

latchgate policy grant agent-support http_fetch,github_read,slack_post
latchgate policy grant agent-ops http_fetch,github_read,http_post,http_delete

6. Review manifests

Switch to the Actions screen (4). Browse the full action catalog, press e to inspect or edit any manifest. Remove actions you don’t need — a smaller attack surface is better.

7. Set up secrets

If your actions need API keys (GitHub, Slack, etc.), switch to Setup > Secrets sub-tab (6 → 5). Press i to initialize the encrypted secrets store, then s to set each secret.

secrets init generates an age keypair, creates an empty encrypted file, and configures sops_secrets_file + sops_key_file in latchgate.toml. Each secrets set decrypts, updates, and re-encrypts atomically.

CLI equivalent

latchgate secrets init
latchgate secrets set GITHUB_TOKEN ghp_xxxx
latchgate secrets set SLACK_BOT_TOKEN xoxb-xxxx

See Secrets Management for rotation and alternative backends.

8. Configure the egress proxy

If any of your selected actions use egress.profile = proxy_allowlist (most HTTP actions do), you need a Squid forward proxy:

# Start Squid (Docker example)
docker run -d \
  --name latchgate-squid \
  -p 3128:3128 \
  -v $(pwd)/deploy/squid/squid.conf:/etc/squid/squid.conf:ro \
  -v $(pwd)/deploy/squid/allowed_domains:/etc/squid/allowed_domains:ro \
  ubuntu/squid:latest

The egress_proxy_url was already set in step 3. See Egress Proxy for allowlist generation and live-reload configuration. This is defense-in-depth — the kernel already validates sinks, but the proxy is an independent backstop.

9. Add notifications (strongly recommended)

Switch to Setup > Webhooks sub-tab (6 → 4). Press a to add a webhook endpoint. Without notifications, approvals time out before operators notice.

CLI equivalent

latchgate config add-webhook --name slack-alerts \
  --url https://hooks.slack.com/services/T.../B.../xxx \
  --secret whsec_xxx \
  --events approval.pending,approval.expired

See Webhooks for all event types and delivery guarantees.

10. Add more operators (optional)

Switch to Setup > Operators sub-tab (6 → 2). Press a to generate a new keypair and credential entry.

The default operator was created by latchgate init. Distribute each operator’s api_key and .latchgate/<name>.pem securely.

CLI equivalent

latchgate config add-operator --name alice
latchgate config add-operator --name bob

11. Validate

Back on Setup > Overview (6 → 1), press d to run the doctor checks. All checks should pass green.

CLI equivalent

latchgate doctor

Fix any errors before proceeding. Warnings are acceptable but should be addressed before going live.

12. Start

latchgate serve

Signing keys are auto-generated on first start at the paths configured in latchgate.toml (.latchgate/operators/keys/receipt.key and .latchgate/operators/keys/grant.key). Back these up immediately.

Verify:

curl --unix-socket /run/latchgate/gate.sock http://localhost/healthz
curl --unix-socket /run/latchgate/gate-admin.sock http://localhost/v1/admin/status

13. Back up signing keys and schedule ledger backups

# Keys (do this once after first start)
cp .latchgate/operators/keys/receipt.key /secure-backup/
cp .latchgate/operators/keys/grant.key /secure-backup/

# Ledger (schedule this — e.g. daily via cron)
# Back up the evidence ledger (SQLite online backup)
sqlite3 "$(latchgate config get ledger_db_path)" ".backup /backups/audit-$(date +%Y%m%d).db"

14. Set up monitoring

Configure your monitoring to scrape /metrics (admin socket, operator auth). Alert on:

• latchgate_unresolved_intents > 0 — evidence gaps requiring investigation (see Troubleshooting)
• latchgate_webhook_outbox_pending growing over time — webhook delivery issues
• latchgate_audit_write_errors_total increment — critical incident
• latchgate_readyz_degraded_total — dependency degradation
• latchgate_oldest_pending_approval_seconds — operator response latency

What you now have

• UDS-only transport — no TCP exposure
• peercred identity — kernel-enforced caller authentication
• Named operator credentials with DPoP proof-of-possession
• Persistent Ed25519 signing keys for receipts and grants
• SOPS-encrypted secrets with JIT injection
• OPA ACL with per-principal action grants and auto-derived sinks
• Strict sandbox mode with fuel, memory, epoch deadline, I/O budget
• Response schema enforcement set to deny
• Evidence ledger with hash-chain integrity and pre-dispatch intents
• Defense-in-depth egress proxy for proxy_allowlist actions
• Real-time webhook notifications for approvals and security events

Complete command summary

# Setup
latchgate init --preset lockdown
latchgate tui                         # manage everything from the TUI, or use CLI below

# CLI equivalents for TUI operations
latchgate config set public_base_url "https://gate.internal.example.com"
latchgate config set redis_url "redis://redis.internal:6379"
latchgate config set opa_url "http://opa.internal:8181"
latchgate config set egress_proxy_url "http://squid.internal:3128"
latchgate config add-principal --uid 1001 --name agent-support --scopes tools:call
latchgate config add-principal --uid 1002 --name agent-ops --scopes tools:call
latchgate policy grant agent-support http_fetch,github_read,slack_post
latchgate policy grant agent-ops http_fetch,github_read,http_post,http_delete
latchgate secrets init
latchgate secrets set GITHUB_TOKEN ghp_xxxx
latchgate secrets set SLACK_BOT_TOKEN xoxb-xxxx
latchgate config add-webhook --name slack-alerts --url https://hooks.slack.com/... --secret whsec_xxx --events approval.pending

# Validate & start
latchgate doctor
latchgate serve

Next steps

• Operator TUI — full TUI reference with all screens and keybindings
• Policy & Approvals — customize OPA rules for your team’s workflow
• Webhooks — push approval notifications to Slack, Teams, or PagerDuty
• Egress Proxy — defense-in-depth egress control with Squid
• Deployment — full hardening, monitoring, graceful shutdown
• Upgrading — version migration procedures
• SDKs — integrate your agents via the Python or TypeScript SDK