Configuration

Every setting this server accepts, in one place. There was no such place: the guide explained a dozen of them where they came up and the rest existed only in internal/config/config.go, so the answer to “what can I set” was “read the source”.

A test keeps this honest. TestEveryConfigurationKeyIsDocumented reads the Config struct and every COGITORIUM_* this server looks up, and fails if one of them is missing from this file. A setting added without a line here does not merge.

Where it comes from

Later wins:

1. Defaults — what you get having written nothing.
2. The file — --config <path>, else $COGITORIUM_CONFIG, else <data-dir>/config.yaml if it exists.
3. The environment — COGITORIUM_*.
4. Flags — --listen, --data, --log-level, --config.

A file is YAML and every key below is top-level:

listen: 0.0.0.0:8688
data_dir: /data
sandbox: docker
terminal: false

Booleans read from the environment are strict: only 1 and true (any case) count as on. COGITORIUM_EGRESS=yes is off, and it overrides a config file that said on — a value that looks affirmative and is not would be the worst way to find out what is enabled.

Where it listens, and what it owns

Credentials

Nothing here belongs in a config file that ends up in a repository. The three that have no YAML key at all are env-only for exactly that reason.

Models

Seeded, never enforced. A provider is created only when this install has no provider by that name; nothing is updated or removed afterwards, so an address changed on the Models screen stays changed. See the starter.

providers:
  - name: local
    kind: openai-compatible        # or: anthropic
    base_url: http://ollama:11434/v1
    key_env: SOME_ENV_VAR          # the variable holding the key, never the key
    models:
      - name: qwen2.5:7b           # what the provider calls it
        label: local               # what you read on a screen
orchestrator_model: local/qwen2.5:7b

Doors a prepared workspace arrived with

A workspace bundle can carry its inlets — the address, and behind it every task with its schema, its instruction and what success is — so two installs restored from one document are the same install. It never carries the key, which is why a restored door is inert: it exists, its shape is right, and it refuses every delivery.

That is the right rule and it left one manual step in a deployment that is otherwise one command. inlet_keys closes it without weakening the rule, because the key does not come from the document — it comes from the environment, where this deployment already keeps its secrets and where the caller’s own copy comes from too:

inlet_keys:
  - address: echopage          # the `echopage` in POST /i/echopage/extract
    key_env: ECHOPAGE_INLET_KEY

A door named here that this install does not have yet is ordinary — on a first start the workspace has not been imported — and the next start finds it. An empty variable leaves the door shut and says so loudly, because the failure it would otherwise cause is a 401 at somebody else’s integration hours later.

The same thing through the API, for a deployment that would rather script it: POST /api/v1/inlets/{id}/key with {"key": "…"} adopts a key you already hold instead of generating one. A supplied key must be at least 32 characters; the response never echoes it back.

Running agent-authored code

On Kubernetes

Only the claim has to be supplied: it names the volume the data directory is on, and a gear Job mounts that same claim at its own subPath.

The terminal

It is on, and it is a shell on the machine this server runs on, as the account it runs as — the same reach you already have by sitting at that machine, and the terminal an editor would have given you. The exception is a workspace terminal on an install with more than one account: a member is not the operator, so there they get the sandbox instead, and where there is no sandbox to put them in they are refused rather than handed the machine.

terminal: false refuses it entirely, and on a shared install it should. The setting distinguishes “written false” from “not written”, so writing it once holds across restarts and across changes to the default.

Work

Plugins

plugins:
  release-radar:
    repository: orkcom-tech/cogitorium

Read-only from a plugin’s side. What a plugin wants to remember goes in its own storage — a plugin writing its own configuration would be a plugin granting itself something.

Also

COGITORIUM_CONFIG names the config file itself, and is the second place --config looks.