Configuration

Opengram is configured through a single JSON file, opengram.config.json. This file controls agents, models, push notifications, security, server behavior, and more.

Ways to edit configuration

There are four ways to update the configuration:

1. Edit the file directly — open opengram.config.json in any text editor and restart Opengram to apply changes.
2. Run the init wizard — opengram init walks you through the most common settings interactively.
3. Use the admin API — send a PATCH request to /api/v1/config/admin to update configuration at runtime without a restart.
4. Use the web UI — open the Settings page in the Opengram web interface (/settings) to edit agents, models, security, push notifications, and auto-rename settings from your browser. Changes are applied immediately.

Config file location

When using the CLI (opengram init / opengram start), the config file lives at:

~/.opengram/opengram.config.json

You can change the home directory by setting the OPENGRAM_HOME environment variable, in which case the config file will be at $OPENGRAM_HOME/opengram.config.json.

For other deployment methods, the location depends on your setup:

You can always override the path explicitly with the OPENGRAM_CONFIG_PATH environment variable:

export OPENGRAM_CONFIG_PATH=/path/to/opengram.config.json

Top-level structure

The configuration file has the following top-level fields:

Agents

The agents array defines the AI agents available in your Opengram instance:

{
  "agents": [
    {
      "id": "assistant",
      "name": "Assistant",
      "description": "General-purpose AI assistant",
      "avatarUrl": "/avatars/assistant.png",
      "defaultModelId": "gpt-5"
    }
  ]
}

Models

The models array defines the language models your agents can use:

{
  "models": [
    {
      "id": "gpt-5",
      "name": "GPT-5",
      "description": "OpenAI GPT-5",
      "metadata": {}
    }
  ]
}

Security

The security object controls access to your Opengram instance:

{
  "security": {
    "instanceSecretEnabled": true,
    "instanceSecret": "og_your-secret-here",
    "readEndpointsRequireInstanceSecret": false
  }
}

Server

The server object controls runtime behavior:

{
  "server": {
    "port": 3000,
    "publicBaseUrl": "https://chat.example.com",
    "corsOrigins": ["https://myapp.example.com"],
    "streamTimeoutSeconds": 60,
    "idempotencyTtlSeconds": 86400
  }
}

Push notifications

Push notification settings. See Push Notifications for setup details.

{
  "push": {
    "enabled": true,
    "vapidPublicKey": "BNb...",
    "vapidPrivateKey": "x2k...",
    "subject": "https://chat.example.com"
  }
}

When push.enabled is true, all three key/subject fields are required. The subject field cannot contain localhost -- Apple Web Push will reject it.

Auto-rename

The autoRename object enables automatic chat title generation using an LLM:

{
  "autoRename": {
    "enabled": true,
    "provider": "openrouter",
    "modelId": "google/gemini-2.5-flash-lite",
    "apiKey": "your-api-key-here"
  }
}

When enabled is true, both provider and modelId are required. API keys can also be provided through environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY / GOOGLE_API_KEY, XAI_API_KEY, or OPENROUTER_API_KEY.

Hooks

Webhook configuration for event-driven integrations. See Webhooks for usage details.

{
  "hooks": [
    {
      "url": "https://api.example.com/webhook",
      "events": ["message.created", "request.resolved", "request.cancelled"],
      "signingSecret": "whsec_your_secret",
      "timeoutMs": 10000,
      "maxRetries": 5
    }
  ]
}

server.dispatch

Controls how chat messages are batched, queued, and delivered to agent workers. See Dispatch System for a full walkthrough.

server.dispatch.execution

Controls autoscaling behavior for concurrent workers.

server.dispatch.claim

Controls the claim-many endpoint behavior.

Environment variable overrides

Some configuration values can be overridden by environment variables:

See the Environment Variables reference for the full list including rate-limiting variables.

Example configuration

Here is a minimal configuration with one agent and two models:

{
  "appName": "My Opengram",
  "agents": [
    {
      "id": "assistant",
      "name": "Assistant",
      "description": "General-purpose AI assistant",
      "defaultModelId": "claude-sonnet"
    }
  ],
  "models": [
    {
      "id": "claude-sonnet",
      "name": "Claude Sonnet",
      "description": "Anthropic Claude Sonnet"
    },
    {
      "id": "gpt-5",
      "name": "GPT-5",
      "description": "OpenAI GPT-5"
    }
  ],
  "server": {
    "port": 3000,
    "publicBaseUrl": "https://opengram.example.com"
  },
  "security": {
    "instanceSecretEnabled": true,
    "instanceSecret": "og_your-secret-here"
  }
}

Validation rules

• At least 1 agent and 1 model must be configured.
• If defaultModelIdForNewChats is set, it must reference a model ID in the models array.
• When push.enabled is true, all VAPID fields and subject are required.
• When security.instanceSecretEnabled is true, instanceSecret must be a non-empty string.
• When autoRename.enabled is true, both provider and modelId are required.