Reference

Config File

Agently's global configuration is stored at ~/.agently/config.json. This file controls providers, default models, and global behavior.

File Location

~/.agently/config.json

On Windows, this is at %APPDATA%\Agently\config.json.

Changes to this file take effect the next time Agently is opened, or immediately if you click Reload Config in Settings → Advanced.

Full Schema

{
  // Version of the config schema
  "version": 1,

  // AI Providers
  "providers": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "sk-ant-...",   // stored in keychain, not in file
      "models": [
        {
          "id": "claude-opus-4-6",
          "name": "Claude Opus 4.6",
          "contextWindow": 200000,
          "maxOutputTokens": 8192
        }
      ]
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-...",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "contextWindow": 128000,
          "maxOutputTokens": 4096
        }
      ]
    },
    {
      // Local provider (Ollama, LM Studio, etc.)
      "id": "local-ollama",
      "name": "Ollama (local)",
      "baseUrl": "http://localhost:11434/v1",
      "apiKey": null,
      "models": [
        {
          "id": "llama3.2:latest",
          "name": "Llama 3.2"
        }
      ]
    }
  ],

  // Default provider and model for new conversations
  "defaultProvider": "anthropic",
  "defaultModel": "claude-opus-4-6",

  // Default permission for new conversations
  // "explore" | "ask-to-edit" | "auto"
  "defaultPermission": "ask-to-edit",

  // Active workspace ID
  "activeWorkspace": "default",

  // Telemetry (anonymous usage data)
  "telemetry": false,

  // Auto-update channel
  // "stable" | "beta" | "alpha"
  "updateChannel": "stable"
}

Field Reference

versionnumberrequired

Config schema version. Currently always 1. Do not change.

providersProvider[]

List of AI provider configurations. API keys are stored in the system keychain — the key in the JSON is a reference name only.

defaultProviderstring

ID of the default provider for new conversations. Must match one of the provider IDs in the providers array.

defaultModelstring

Model ID to use by default. Must be listed under the defaultProvider.

defaultPermission"explore" | "ask-to-edit" | "auto"

Permission level for new conversations. Default is "ask-to-edit".

activeWorkspacestring

ID of the workspace to open on launch. Default is "default".

telemetryboolean

Send anonymous usage statistics to help improve Agently. Default is false.

updateChannel"stable" | "beta" | "alpha"

Which release channel to follow for auto-updates. Default is "stable".

Editing the Config

You can edit config.json directly in any text editor, or use the GUI in Settings. The GUI writes valid JSON automatically.

If the file contains invalid JSON, Agently will show an error on launch and fall back to defaults. The original file is backed up to config.json.bak.