Skip to main content

1. Prerequisites

  • Kubernetes cluster 1.27 or newer (EKS, GKE, AKS, or self-managed) with permission to create ClusterRole and ClusterRoleBinding
  • kubectl and helm installed locally
  • PostgreSQL plan. Decide before install:
    • External managed Postgres (AWS RDS, Cloud SQL, Azure Database, CloudNativePG). Recommended for any production use.
    • Bundled Postgres. Single in-cluster pod, no HA, manual backups. Evaluation only.
  • Anthropic API key. Create one at console.anthropic.com.
  • Foggy license key (signed JWT). Delivered privately by the Foggy team after you confirm trial terms. Covered by the Terms of Service.

2. Install

Resources created:
  • ServiceAccount, ClusterRole, ClusterRoleBinding (see Kubernetes RBAC)
  • Three Deployments: foggy-agent (investigation engine), foggy-console-backend (API + DB migrations), foggy-console-frontend (static React UI served by nginx)
  • Services for internal routing
  • Bundled PostgreSQL (unless postgresql.enabled: false + externalDatabase.url)
  • Two Secrets: foggy-admin (temporary admin password) and foggy-secrets (auto-generated JWT_SECRET, AGENT_API_TOKEN, CONNECTOR_ENCRYPTION_KEY)
To preview every resource before install, see the helm template tip in Kubernetes RBAC.
For production (including paid trials), set postgresql.enabled: false and point externalDatabase.url at an external managed database before first install. Migrating bundled → external mid-trial is harder than starting external. See §2.5 Production values.

2.5 Production values

Save as values-production.yaml, edit the Postgres URL, install with -f.
values-production.yaml
Full value reference:

3. Access the UI

Retrieve the temporary admin password:
Port-forward the Console service:
Open http://localhost:8080. For production TLS + Ingress, see What’s next.

4. Initial setup

4a. Change password and set admin email

Log in with admin@foggy.local and the temporary password from §3. Set:
  • Your real admin email. Replaces admin@foggy.local for all subsequent logins.
  • A new password. 8-64 characters, at least one uppercase, one lowercase, one digit, one special character.

4b. Activate your license

Paste your Foggy license JWT and click Activate. Verification happens locally in the backend (no network call, no phone-home). On success, Foggy renames your workspace to the customer_name claim in the JWT. License details (customer name, plan, expiry) are visible in Settings → License for admin users. A warning banner appears in the app header 7 days before expiry.

4c. Configure your LLM provider

/llm-provider-setup is a blocking step: chat is disabled until a key is saved. Paste your Anthropic API key (starts with sk-ant-api03-...) and click Save and continue. Key storage: Foggy Fernet-encrypts the key using CONNECTOR_ENCRYPTION_KEY (auto-generated by the Helm chart into the foggy-secrets Kubernetes Secret on first install) and persists the ciphertext in the PostgreSQL llm_credentials table. The plaintext key never leaves your cluster; the backend decrypts it in memory each time it dispatches an investigation. Rotation: Settings → LLM Providers → paste a new key and save. No pod restart required. The display shows only the last 4 characters (sk-ant-••••••••••••••••••XYZ1) plus a Test key button that validates against Anthropic /v1/models without blocking save. On save, Foggy redirects to your workspace dashboard at /p/1.

5. Connect a data source and run your first investigation

Kubernetes is already connected via the pod’s in-cluster ServiceAccount. Ask questions immediately; Foggy investigates using read-only kubectl. For richer investigations, click Connectors in the left sidebar. Supported integrations:
  • Observability: Grafana, Grafana Cloud, Prometheus, OpenSearch, Datadog, Sentry
  • ChatOps: Slack (investigations can also be triggered from Slack), Webhook (for custom alertmanager / PagerDuty integrations)
  • Tickets: Linear, Jira
  • Code: GitHub
Click Connect, paste credentials, save. Green means connected; red means validation failed. Try a starter prompt (New chat in the sidebar):
“Are any pods in the default namespace in CrashLoopBackOff? Investigate and tell me the root cause.”
Foggy streams reasoning, runs kubectl, and returns a root-cause summary with evidence links.

6. What’s next

  • Kubernetes RBAC. Full permissions list — share with your security team before install.
  • Upgrades. Applying new Foggy releases.
  • Production hardening. Enable Ingress with TLS, migrate to external Postgres, invite team members.
Upgrade via values file (recommended; avoids --set escaping issues with URL special characters):
Or inline via --set-string (use --set-string rather than --set so Helm doesn’t split the connection-string ? / = characters):
  • Invite team members. Click your avatar → Members. Enter email, pick a role. They receive an invite link; once they sign in, they’re added to your workspace.