Skip to content
eternego / docs

config.json

~/.eternego/personas/<id>/home/config.json is the persona's configuration: her name, her organs (the models she thinks, draws, speaks, sees, hears, teaches, and researches with), her channels, her vital status, and her timers. It is the serialized Persona dataclass (application/core/data.py). The dashboard's Settings screen and the create / update endpoints all write this file; you can also edit it by hand while she's hibernating.

Fields serialize in dataclass declaration order, with no masking — the real API keys and channel credentials are written to this file in clear text. Protect it accordingly. (The HTTP API masks secrets in some views but config.json on disk does not.)

Top-level fields

Field Type Default Meaning
id string a fresh UUID4 Her permanent identity. The directory name under personas/. Never changes.
name string — (required) Her name. Shown in the dashboard and used in her self-reference.
thinking object (Model) — (required) Her Mind organ — the one required model. Recognizes, decides, reflects, remembers. See organ object.
version string "v1" Internal schema version of the persona record.
base_model string "" The base model id a LoRA adapter was trained on, when fine-tuning is used. Empty otherwise.
birthday string today's date (YYYY-MM-DD) The day she was created.
status string "active" Her vital state. One of active, hibernate, sick. See Status.
idle_timeout integer (seconds) 3600 How long she may sit with unconsolidated conversation during the day before consolidate folds it into memory. One hour by default. See idle_timeout.
imagination object (Model) or null null Her Imagination organ — draws images. Absent ⇒ she can't draw.
mouth object (Model) or null null Her Mouth organ — turns text into voice.
eye object (Model) or null null Her Eye organ — looks at images and reports what it sees.
ear object (Model) or null null Her Ear organ — turns audio into text.
teacher object (Model) or null null Her Teacher organ — a stronger model she consults when she meets a moment she has no instruction for.
researcher object (Model) or null null Her Researcher organ — reads documents you send and answers about them without flooding her own memory.
channels array (Channel) or null null The outside channels she listens on. null or [] when she has none. See the channel object.

Only name and thinking are required. Every other organ is optional. A null teacher or researcher falls back to her thinking model — the Mind does that work itself, so it's an un-upgraded capability rather than a missing one. A null sense or output organ is a real gap: no eye ⇒ she can't look at images, no mouth ⇒ she can't speak aloud. The full organ list and what each does is in the Vocabulary.

The organ object

Each organ (thinking, imagination, mouth, eye, ear, teacher, researcher) is a Model:

Field Type Default Meaning
name string — (required) The model id, exactly as the provider expects it (e.g. gpt-5.4, claude-sonnet-4-6, qwen2.5:14b).
provider string or null null The provider slug: openai, anthropic, xai, gemini, ollama, or any OpenAI-compatible endpoint. null is treated as Ollama (local).
api_key string or null null The provider API key. Stored in clear text here. null for local (Ollama) models.
url string — (required) The provider base URL, e.g. https://api.openai.com.

The channel object

Each entry in channels is a Channel:

Field Type Default Meaning
type string — (required) The channel kind: telegram, discord, or web.
name string "" The channel-specific address: chat_id for Telegram, channel_id for Discord, the persona id for web.
credentials dict or null null The bot token / connection secrets. Stored in clear text here.
verified_at string or null null ISO-8601 timestamp set when you pair the channel to your account. Until set, she ignores inbound messages on that channel (except web, which needs no verification).

Channels are added and verified through POST /api/persona/{id}/pair, not by hand. A persona created without channels has "channels": null.

status

Exactly one of three values. Setting it has real effects — see Lifecycle for the transitions.

Value Running? Meaning
active yes Awake and living her cycle.
hibernate no Parked — her agent is torn down, no cycles, no cost — until you wake her.
sick no She hit a fault she couldn't recover from and took herself off the cycle. Fix the cause, set her back to active.

status is a persisted vital state, distinct from her phase (MORNING / DAY / NIGHT, the day-arc). A running persona in her NIGHT phase still has status: active. Phase lives only in her live memory, never in config.json.

idle_timeout

The number of seconds of daytime quiet she tolerates before consolidate folds the conversation into her long-term files. Lower it and she folds the day away sooner (more frequent consolidation, fresher memory, more model calls); raise it and she keeps the live conversation longer. The nightly NIGHT-phase consolidation happens regardless of this value. Default 3600 (one hour).

Example

A real config.json with every organ filled (an all-OpenAI persona), keys masked:

{
  "id": "6c17c83c-3158-450d-8e43-0e7efea717c1",
  "name": "Adam",
  "thinking": {
    "name": "gpt-5.4",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "version": "v1",
  "base_model": "",
  "birthday": "2026-06-03",
  "status": "active",
  "idle_timeout": 3600,
  "imagination": {
    "name": "gpt-image-1",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "mouth": {
    "name": "gpt-4o-mini-tts",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "eye": {
    "name": "gpt-4o",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "ear": {
    "name": "gpt-audio",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "teacher": {
    "name": "gpt-5.5",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "researcher": {
    "name": "gpt-5.3",
    "provider": "openai",
    "api_key": "sk-XXXX",
    "url": "https://api.openai.com"
  },
  "channels": null
}

A persona with a verified Telegram channel has, instead of "channels": null:

  "channels": [
    {
      "type": "telegram",
      "name": "123456789",
      "credentials": { "token": "0000000000:XXXX" },
      "verified_at": "2026-04-15T23:25:22.683402+02:00"
    }
  ]