Engram — Deployment Models

Engram offers two deployment models. The product experience is identical — same dashboard, same CLI, same AI pipeline, same guideline management. The difference is where it runs and who operates it.

Quick Comparison

	Engram Cloud (SaaS)	Self-Hosted
Who operates	Engram team	Your infrastructure team
Where data lives	Engram-managed PostgreSQL	Your PostgreSQL instance
Dashboard URL	`https://app.getengram.io`	Your domain (e.g., `https://engram.internal.company.com`)
API endpoint	`https://api.getengram.io`	Your domain (e.g., `https://engram.internal.company.com/api`)
Edge serving	Cloudflare Workers + KV (<5ms globally)	Direct from your API server (<10ms)
LLM provider	Engram-managed keys (default) or BYO	BYO required (your keys, your endpoint)
Upgrades	Automatic, zero-downtime	You pull new images and restart
Backups	Managed by Engram	Your responsibility
SSO/SAML	Available on Enterprise plan	Available (self-configured)
Air-gapped	No (cloud service)	Yes (Ollama/vLLM for LLM, no external calls)
Pricing	Per-seat subscription	License fee (annual)
Setup time	Minutes (sign up and go)	15-30 minutes (docker compose)

What's the Same (Everything That Matters)

Regardless of deployment model, you get the exact same product:

Dashboard — same UI for managing guidelines, domains, sources, routing, and team members
CLI — same engram commands (sync, analyze, generate, validate, deploy, context)
AI pipeline — same gap analysis, document generation, validation, staleness detection
Source connectors — same integrations (GitHub, Notion, Confluence, Google Workspace, websites)
Compilation targets — same outputs for Claude Code, Cursor, Copilot, Windsurf, AGENTS.md
GitHub App — same automated repo deployments via PR
API — same REST endpoints, same OpenAPI spec
Auth — same email/password + OAuth + API keys (SAML on enterprise tier)

The CLI doesn't know or care which deployment model you're using — it just talks to whatever API endpoint is configured.

Engram Cloud (SaaS)

Who It's For

Teams that want to start immediately without infrastructure setup
Companies comfortable with cloud-hosted data (guidelines are company conventions, not customer PII)
Teams without dedicated infrastructure/DevOps resources

Getting Started

Sign up at https://app.getengram.io
Create a workspace — pick a name and slug
Connect sources — GitHub org, Notion, Confluence, etc. (OAuth flows in the dashboard)
Run gap analysis — engram analyze or click "Run Analysis" in the dashboard
Generate and review guidelines — confirm topics, generate docs, domain owners approve
Deploy — connect repos, set compile targets, deploy via GitHub App

That's it. No servers to manage, no databases to back up, no TLS certificates to rotate.

LLM Configuration

Default (Engram-managed): Your workspace uses Engram's API keys for AI operations (gap analysis, document generation, validation). No configuration needed.

BYO (optional): If you prefer your AI calls to use your own API keys — for billing, compliance, or model preference — configure BYO in Settings > LLM Configuration:

Your own Anthropic/OpenAI keys
Azure OpenAI endpoint
AWS Bedrock (your region, your credentials)

BYO on SaaS means the AI calls use your keys, but the data (guidelines, sources) still lives in Engram's database.

Edge Content Serving

Context requests (GET /api/v1/context?workspace=acme&role=backend) are served from Cloudflare's edge network — <5ms globally. Pre-compiled guidelines are cached in Cloudflare KV and invalidated automatically when you publish changes.

Data & Security

All data encrypted at rest (AES-256) and in transit (TLS 1.3)
PostgreSQL hosted on managed infrastructure with automated backups
SOC 2 Type II compliance (planned)
Data region: US by default (EU available on Enterprise plan)
Your source credentials (OAuth tokens) are encrypted at rest
Guidelines contain company conventions and patterns — not customer data, not source code

Limitations

Cannot run fully air-gapped (requires internet connectivity)
Data resides in Engram's infrastructure (even with BYO LLM, guidelines are stored by Engram)
No custom database tuning or extension installation

Self-Hosted

Who It's For

Enterprises with strict data residency requirements
Companies that need full control over where data lives
Air-gapped environments (government, defense, regulated industries)
Organizations with existing infrastructure and ops teams

Getting Started

Full technical guide: Self-Hosted Deployment Guide

Quick version:

Create docker-compose.yml with three services: engram (API + worker), engram-web (dashboard), postgres (database)
Set environment variables — DATABASE_URL, JWT_SECRET, LLM API keys
Start: docker compose up -d
Open dashboard at your configured URL, create your first account and workspace
From here, the workflow is identical to SaaS — connect sources, analyze, generate, deploy

LLM Configuration

Self-hosted requires you to provide LLM credentials. Options:

Option	What You Provide	Data Stays Where
Own cloud API keys	Your Anthropic + OpenAI keys	AI calls go to Anthropic/OpenAI, guidelines stay on your server
Azure OpenAI	Azure endpoint + key	AI calls stay in your Azure tenant
AWS Bedrock	Region + IAM credentials	AI calls stay in your AWS account
Ollama / vLLM	Local endpoint URL	Everything stays on your network — fully air-gapped

Configure per-workspace in the dashboard under Settings > LLM Configuration, or via environment variables for server-wide defaults. See self-hosted.md for detailed config examples.

Infrastructure You Manage

Component	What You Do
PostgreSQL	Provision, back up, monitor. Use the bundled container or your existing instance.
TLS / Reverse proxy	Set up nginx/Caddy/Traefik in front of Engram for HTTPS.
Upgrades	Pull new Docker images, restart. Migrations run automatically.
Backups	Schedule `pg_dump` or use your DB backup solution.
Monitoring	Scrape `/metrics` (Prometheus) and `/health`. Set up alerts.
Redis (optional)	Deploy if you want faster context serving (<10ms → <5ms). Not required.

Network Requirements

Connection	Required?	Purpose
LLM API (Anthropic, OpenAI, etc.)	Yes, unless using Ollama	AI pipeline (gap analysis, generation, validation)
GitHub API	Only if using GitHub App	Automated repo deployments
Notion/Confluence/Google APIs	Only during source sync	Ingesting source content
Outbound internet	No (if using Ollama)	Fully air-gapped operation possible

Air-Gapped Deployment

For environments with no internet access:

Use Ollama or vLLM for LLM — runs on your network
Skip source connectors — create guidelines manually in the dashboard or import via API
Skip GitHub App — use engram compile locally and commit files manually
Load Docker images from a registry mirror or docker load from tarballs

Everything works — you just lose the automated integrations that require external APIs.

Scaling

The default single-process mode (MODE=both) handles most teams comfortably:

A 2-core / 2 GB machine serves teams of 50+ with ~100 guidelines
The Rust binary uses ~50 MB RAM baseline, no GC pauses

For larger deployments, split API and worker:

services:
  engram-api:
    image: engram/server:latest
    environment:
      MODE: api
    ports: ["8080:8080"]

  engram-worker:
    image: engram/server:latest
    environment:
      MODE: worker
      ANTHROPIC_API_KEY: sk-ant-...

See self-hosted.md for details.

CLI Configuration by Deployment Model

The CLI works identically with both models. The only difference is the API endpoint it connects to.

SaaS

# First-time setup
bunx @engram/cli
engram init
# → SSO login → selects workspace → done
# API endpoint: https://api.getengram.io (automatic)

Self-Hosted

# First-time setup
bunx @engram/cli
engram init --api https://engram.internal.company.com
# → Login → selects workspace → done

Or set the environment variable:

export ENGRAM_API_URL=https://engram.internal.company.com
engram init

After init, all commands work the same:

engram analyze              # run gap analysis
engram context --role backend  # get context for backend role
engram sync                 # sync guidelines to local AI tools
engram deploy               # push to repos via GitHub App

Migrating Between Models

SaaS → Self-Hosted

Export your workspace data via the API:

engram export --workspace acme --output engram-backup.json

Deploy self-hosted stack (see self-hosted.md)

Import the backup:

engram import --input engram-backup.json --api https://engram.internal.company.com

Re-authenticate source connections (OAuth tokens are not transferable)
Update CLI config: engram init --api https://engram.internal.company.com
Update GitHub App webhook URL to point to your self-hosted instance

Self-Hosted → SaaS

Same process in reverse — export from self-hosted, import into SaaS workspace. Source connections need re-authentication.

Decision Guide

Choose SaaS if:

You want to start in minutes with zero infrastructure
Your guidelines contain company conventions (not regulated data)
You don't have strict data residency requirements
You prefer managed upgrades and backups

Choose Self-Hosted if:

You need full control over where data lives
You have data residency or compliance requirements (HIPAA, FedRAMP, etc.)
You need air-gapped operation (no external network calls)
You have infrastructure and ops capacity to manage it
You want to use your own LLM infrastructure (Ollama, vLLM, private endpoints)

Both models:

Use the same dashboard, CLI, and API
Support BYO LLM (own API keys or self-hosted models)
Support GitHub App for automated repo deployments
Support all compilation targets (Claude, Cursor, Copilot, Windsurf, AGENTS.md)
Get the same AI pipeline (gap analysis, generation, validation)