Skip to main content

Deploy

:::info Stub This is a starter outline. The full deployment guide is being ported from the layer8-proxy-site repo. The quickstart below is the working shape; the per-step detail will be filled in. :::

Layer8 Proxy deploys as a Docker Compose bundle driven from a per-host site repo that pins a version, holds sealed credentials, and declares per-agent ACLs.

Prerequisites​

  • Docker (or Podman — export COMPOSE="podman compose").
  • A layer8-proxy-site clone for the target host.
  • Provider API keys and the lf-scan internal token.

Quickstart​

# 1. Configure .env (provider keys + LF_SCAN_INTERNAL_TOKEN + backup creds).
cp .env.example .env
nano .env

# 2. Pin the layer8-proxy version.
nano site.cfg                  # set layer8_version=vX.Y.Z

# 3. Bootstrap sealed secrets that locksmith reads at startup.
echo -n "$LF_SCAN_INTERNAL_TOKEN" | ./secrets.bootstrap.sh lf_scan_token --from-stdin
echo -n "your-restic-passphrase" | ./secrets.bootstrap.sh restic_password --from-stdin

# 4. Generate the operator credential.
LOCKSMITH_CREDS_PASSPHRASE="..." ./scripts/bootstrap-operator.py

# 5. Deploy the proxy stack (render + verify + docker compose up).
./deploy.sh

# 6. Smoke test.
curl http://127.0.0.1:9200/livez

# 7. Declare agents and register them.
cp agents.yaml.example agents.yaml
nano agents.yaml
./scripts/register-agents.sh
# Each agent gets a bearer; copy each ONCE to the corresponding agent host.

OAuth providers​

To enable OAuth providers (codex, copilot, anthropic-oauth, gemini-cli, qwen-cli), supply a 32-byte sealing key and bootstrap each session once:

LOCKSMITH_OAUTH_SEALING_KEY="$(openssl rand -base64 32)"
echo -n "$LOCKSMITH_OAUTH_SEALING_KEY" \
    | ./secrets.bootstrap.sh oauth_sealing_key --from-stdin

docker exec layer8-locksmith /usr/local/bin/locksmith oauth bootstrap codex \
    --refresh-token "<refresh-token-from-providers-flow>"

To be documented​

  • Rendering + verification (render_configs.py, verify_configs.py) and drift refusal.
  • Sealed-cred mechanics (systemd-creds on Linux, openssl-AES on macOS dev).
  • Backup automation (restic snapshot of locksmith state + sealed creds).
  • Per-host override files (docker-compose.override.yml).
  • Podman notes.

See also​