Docs / Self-hosted

Run the Codira gateway inside your VPC.

For Enterprise customers with data-residency or VPC-only requirements. Your code never leaves your network — the gateway speaks to ai providers from your infrastructure using your own keys.

Overview

The Codira self-hosted gateway is the same Next.js + MongoDB application that powers codira.com, packaged as a single container. It exposes the IDE-facing API (/api/oauth/*, /api/orgs/*, etc.) inside your VPC and brokers requests to whichever ai providers you supply keys for.

The only outbound connection it makes to Codira-owned infrastructure is a periodic HMAC-signed license check (every 24 hours by default). This call carries the license ID and gateway version — no customer code, no usage data, no user identifiers.

Prerequisites

You'll need:

Docker 20+ or a Kubernetes cluster (1.27+ recommended)
A MongoDB 7+ instance reachable from the gateway (Atlas, self-hosted, or DocumentDB)
API keys for the ai providers you intend to use (Anthropic, OpenAI; optionally Google, DeepSeek, xAI)
A Codira Enterprise license — see below
HTTPS termination in front of the gateway (your existing ingress / load balancer)

Get a license

Self-hosted runs against a license key issued by Codira's sales team. To request one, email sales@codira.com with your organization name and expected seat count. Onboarding usually takes 1–2 business days; you'll receive a license key of the form <license-id>.<hmac> along with this guide.

Environment variables

The gateway is configured entirely via environment variables. Secrets should be injected via your secret manager (HashiCorp Vault, AWS Secrets Manager, k8s secrets) — never baked into the image.

Variable	Required	Notes
CODIRA_SELF_HOSTED	required	Set to 'true'. Toggles self-hosted-mode behavior.
CODIRA_LICENSE_KEY	required	The license string issued by Codira sales.
MONGO_URL	required	MongoDB connection string. Atlas SRV format works.
DB_NAME	required	Database name. Default 'codira'.
ANTHROPIC_API_KEY	required	Required for Planner / Reviewer / Security / UX agents.
OPENAI_API_KEY	required	Required for the Implementer agent.
GEMINI_API_KEY	optional	Optional — enables Architect long-context mode (β.6).
DEEPSEEK_API_KEY	optional	Optional — enables reasoning model fallbacks (β.6).
JWT_SECRET	required	Random 32+ byte string. Rotate annually.
RESEND_API_KEY	optional	Optional — enables outbound email (password reset, legal requests).
STRIPE_SECRET_KEY	optional	Optional — only needed if you bill seats yourself via Stripe. Most self-hosted deployments skip Stripe entirely.
CORS_ORIGINS	optional	Comma-separated allowed origins. Defaults to '*' — tighten for prod.
PORT	optional	Default 3000.

Run with Docker

The simplest deployment — a single container behind your existing ingress.

# Pull the latest gateway image
docker pull codira/gateway:0.5.35

# Run it
docker run -d \
  --name codira-gateway \
  -p 3000:3000 \
  -e CODIRA_SELF_HOSTED=true \
  -e CODIRA_LICENSE_KEY="$LICENSE" \
  -e MONGO_URL="mongodb+srv://..." \
  -e DB_NAME=codira \
  -e JWT_SECRET="$(openssl rand -hex 32)" \
  -e ANTHROPIC_API_KEY="$ANTHROPIC_KEY" \
  -e OPENAI_API_KEY="$OPENAI_KEY" \
  codira/gateway:0.5.35

Confirm the gateway is healthy:

curl http://localhost:3000/api/health
# → { "ok": true, "service": "codira-gateway", "version": "0.5.35",
#     "self_hosted": true, "db": { "ok": true } }

Run on Kubernetes

For HA / multi-replica deployments, a Deployment with 2+ replicas behind a Service + Ingress is typical. The gateway is stateless — all state lives in MongoDB — so horizontal scaling Just Works.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: codira-gateway
spec:
  replicas: 2
  selector:
    matchLabels: { app: codira-gateway }
  template:
    metadata:
      labels: { app: codira-gateway }
    spec:
      containers:
        - name: gateway
          image: codira/gateway:0.5.35
          ports:
            - containerPort: 3000
          envFrom:
            - secretRef: { name: codira-gateway-secrets }
          livenessProbe:
            httpGet: { path: /api/health, port: 3000 }
            initialDelaySeconds: 15
            periodSeconds: 30
          readinessProbe:
            httpGet: { path: /api/health, port: 3000 }
            periodSeconds: 10
          resources:
            requests: { cpu: 200m, memory: 512Mi }
            limits:   { cpu: 1000m, memory: 1Gi }

Point the IDE at your gateway

Each developer's Codira IDE needs to know to talk to your gateway instead of codira.com. In Codira, open Settings → ai → Advanced and set the Custom gateway URL to your gateway's ingress hostname:

https://codira-gateway.your-company.internal

Or distribute a managed config file (~/.codira/config.json) via your MDM:

{
  "gateway_url": "https://codira-gateway.your-company.internal",
  "managed": true
}

Health + monitoring

The gateway exposes two endpoints relevant to monitoring:

GET /api/health — JSON probe with DB connectivity + version. Use for k8s liveness/readiness.
GET /api/orgs/:org/audit-log — admin-authenticated audit feed (matches the hosted product's pattern).

All logs go to stdout in JSON for ingestion by Datadog / Splunk / Loki / etc. No application metrics endpoint yet — on the roadmap for v0.7.x.

Support

Enterprise self-hosted customers get a dedicated Slack Connect channel, an account-manager-routed support address, and 24h SLA on P1 issues. For setup questions: support@codira.com.

For security disclosures use security@codira.com — see /trust for the full reporting policy.