Offline & Air-Gapped Mode

AtlasAI Tenant Plane can run in fully air-gapped environments where no internet connection is available. This page explains what “offline mode” means, how to configure it, and how each feature behaves when the Control Plane is unreachable.

What is offline mode?

By default, the Tenant Plane connects to the AtlasAI Control Plane for:

Plan entitlements (which modules and limits apply to your subscription)
AI model routing (which LLM to use for each request)
Usage metering (reporting how many AI credits, events, etc. were consumed)
License renewal (phone-home every 24h to refresh the license JWT)
Authentication proxy (validating user credentials against a central identity store)

In offline mode, all of these connections are disabled. Instead:

Entitlements are read directly from your local license JWT
AI calls go directly to your own AI provider (you supply the API key)
Usage is tracked locally but not reported to AtlasAI
The license is validated locally and does not auto-renew
Authentication uses the local user database only

Everything else — incident management, runbooks, observability, ITSM, automation — works identically whether you are online or offline.

When to use offline mode

Scenario	Use offline mode?
Air-gapped government or defense network	Yes
Financial institution with strict outbound controls	Yes
Healthcare network with no external connectivity	Yes
BYOC deployment with some internet access	No — use BYOC mode instead
Development environment without CP	Yes — simpler to test with

Enabling offline mode

Add this to your environment:


ATLASAI_OFFLINE_MODE=1

This single flag disables all outbound calls to the Control Plane.

Minimum required environment variables for offline mode:


# ─── Core identity ──────────────────────────────────────────────────────────
TENANT_ID=acme-corp
JWT_SECRET=<generate: openssl rand -hex 32>
ENCRYPTION_KEY=<generate: openssl rand -hex 32>
 
# ─── Database ───────────────────────────────────────────────────────────────
TENANT_PLANE_DATABASE_URL=postgresql://user:pass@localhost:5432/atlas
# (SQLite default works for single-instance; not suitable for HA)
 
# ─── Offline mode ───────────────────────────────────────────────────────────
ATLASAI_OFFLINE_MODE=1
 
# ─── License ────────────────────────────────────────────────────────────────
ATLASAI_LICENSE_KEY=eyJhbGciOiJSUzI1NiJ9...  # Your signed license JWT
CP_LICENSE_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----
 
# ─── AI provider (required for AI features) ──────────────────────────────────
BYOC_PROVIDER=openai         # or: bedrock, azure, anthropic, custom
BYOC_API_KEY=sk-...          # Your AI provider API key
BYOC_MODEL=gpt-4o-mini       # The model to use
 
# ─── Embeddings (for AI search / RAG features) ───────────────────────────────
OPENAI_API_KEY=sk-...        # Or use BYOC_API_KEY if same provider
EMBEDDING_PROVIDER=openai    # or: bedrock, fallback

Behavior of each feature in offline mode

Plan entitlements

In offline mode, the Tenant Plane reads your plan entitlements directly from the license JWT. The JWT contains your plan name, enabled modules, and limits:


{
  "plan_id": "operations",
  "plan_name": "Operations",
  "active_addons": ["automation_pro"],
  "limits": {
    "users": 100,
    "ai_credits": 2000,
    "data_volume_gb": 250,
    "data_retention_days": 30,
    "runbooks": -1
  }
}

These limits are enforced the same way as in online mode. If you need different limits, contact AtlasAI to issue a new license with updated values.

AI features

AI features (RCA, runbook generation, copilot, NL search) use your configured AI provider. You control:

Which model is used
Where the data is sent (it stays in your network if you run a local model)
Cost (your AI provider bill, not AtlasAI AI credits)

See Bring Your Own AI (BYOC) for provider-specific configuration.

Usage metering

Usage is tracked locally (event counts, AI calls, data volume) but not sent to AtlasAI. In offline mode, AI credits from your license are tracked locally. If you exhaust your credit allowance, AI features may be throttled until the next billing cycle. Contact AtlasAI support to adjust your license limits if needed.

Authentication

Users log in using the local user database (managed in Settings → Users). The Control Plane authentication proxy is bypassed completely. Users created in the UI are stored in your local PostgreSQL database.

Note: If you previously used SSO (SAML, OIDC) through AtlasAI’s identity service, SSO will not work in offline mode. Configure SSO directly on the Tenant Plane using your own identity provider instead.

License renewal

In offline mode, phone-home renewal is skipped. You must manually renew your license before it expires:

Contact support@atlasai.com 30 days before expiry
Upload the new license using the Settings UI or environment variable

The current expiry date is always visible in Settings → License.

Step-by-step: First-time offline setup

Step 1: Obtain your license

Before going offline, obtain your license from AtlasAI:

Contact support@atlasai.com with your tenant ID and required plan
AtlasAI sends you:
- Your license JWT (ATLASAI_LICENSE_KEY)
- The RSA public key (CP_LICENSE_PUBLIC_KEY)

Keep both safe. The public key does not expire and can be shared with your team. The license JWT is valid for 1 year by default.

Step 2: Choose your AI provider

You need at least one AI provider for AI-powered features. Options:

Option	Notes
OpenAI API	Requires internet access to `api.openai.com`. Not suitable for fully air-gapped.
Azure OpenAI	Can be in your Azure private network. Works air-gapped if configured on your private endpoint.
AWS Bedrock	Works with VPC endpoints so no public internet needed.
Ollama (self-hosted)	Fully local, no external network needed. Suitable for truly air-gapped environments.
vLLM / TGI (self-hosted)	Same as Ollama — any OpenAI-compatible HTTP server on your local network.

See Bring Your Own AI (BYOC) for setup instructions.

Step 3: Configure your `.env`


# Minimum offline configuration
TENANT_ID=acme-corp
JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
TENANT_PLANE_DATABASE_URL=postgresql://atlasusr:securepassword@postgres:5432/atlas
 
ATLASAI_OFFLINE_MODE=1
ATLASAI_LICENSE_KEY=eyJhbGciOiJSUzI1NiJ9...
CP_LICENSE_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\nMIIBIj...\n-----END PUBLIC KEY-----
 
# If using Ollama on the same server
BYOC_PROVIDER=openai
BYOC_API_KEY=ollama          # Ollama doesn't require a real key
BYOC_ENDPOINT_URL=http://ollama:11434/v1
BYOC_MODEL=llama3.2
 
# If using AWS Bedrock via VPC endpoint
# BYOC_PROVIDER=bedrock
# BYOC_REGION=us-east-1
# TP_BEDROCK_USE_TASK_ROLE=1   # Use IAM task/instance role
# TP_BEDROCK_MODEL_ID=anthropic.claude-3-haiku-20240307-v1:0

Step 4: Start the Tenant Plane


docker compose up -d

Step 5: Verify offline mode

Check the license status:


curl http://localhost:3000/api/admin/license \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Look for "offline_mode": true and "status": "active" in the response.

Check that AI is working:


curl -X POST http://localhost:3000/api/ai/test \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: acme-corp" \
  -d '{"test": true}'

Offline upgrades

In air-gapped environments, you cannot pull Docker images from the internet. Use the offline upgrade path:

Export the new image on a connected machine
Transfer the image tarball to your air-gapped server
Run the upgrade script with the OFFLINE_BUNDLE variable

See Upgrade Guide → Air-Gapped Upgrade for step-by-step instructions.

Offline edge agent upgrades

Edge agents running on monitored hosts can also be upgraded without internet access. The Tenant Plane serves upgrade bundles to agents directly:

Download the new edge agent bundle on a connected machine:


docker pull atlasai/edge-agent:1.3.0
docker save atlasai/edge-agent:1.3.0 | gzip > atlas-edge-agent-1.3.0.tar.gz

Or download the npm tarball:


npm pack @atlasai/edge-agent@1.3.0
# Creates: atlasai-edge-agent-1.3.0.tgz

Upload the bundle to the Tenant Plane server:
```
scp atlas-edge-agent-1.3.0.tar.gz admin@your-server:/app/edge-bundles/
```
The bundle directory is set by ATLAS_EDGE_BUNDLE_DIR (default: /app/edge-bundles).

Set the desired edge agent version in the Tenant Plane admin:


curl -X POST https://your-tenant-plane/api/admin/edge-upgrade \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"desired_version": "1.3.0"}'

On the next heartbeat (within 30 seconds), each edge agent downloads the bundle from the Tenant Plane and updates itself automatically.

See Edge Agent → Air-Gapped Upgrades for more detail.

Troubleshooting offline mode

License shows “invalid” status

Cause: CP_LICENSE_PUBLIC_KEY does not match the key used to sign the license.

Fix: Contact AtlasAI support to verify you have the correct public key for your license.

AI features return “unavailable”

Cause: BYOC_API_KEY is not set, or the AI provider endpoint is unreachable.

Fix: Check your AI provider configuration and that the endpoint URL is accessible from the Tenant Plane server.

Users cannot log in after switching to offline mode

Cause: In online mode, login credentials may have been validated against the AtlasAI Control Plane. In offline mode, only users in the local database are valid.

Fix: Create local user accounts in Settings → Users before switching to offline mode. Or reset passwords for existing users via POST /api/admin/users/{id}/reset-password.

Settings page shows “Control Plane not configured”

This is expected in offline mode. The connection status indicator shows offline because CONTROL_PLANE_BASE_URL is not set. This does not affect functionality.