Configuration

Writable home directory (important)

Annodex and Codex both write persistent data under the user home (unless you override the paths below). The web UI, model settings, project registry, extensions, optional password, server logs, and Codex chat history all depend on being able to create and update files there.

What gets written

Linux and server deployments

Many Linux issues come from a non-writable or quota-limited $HOME:

• HPC / lab servers with small home partitions
• NFS home directories that are full or read-only
• Service accounts or containers where $HOME is missing or not writable
• sudo sessions where $HOME still points at root's home

Check before starting:

echo "HOME=$HOME"
test -w "$HOME" && echo "home writable" || echo "home NOT writable"
mkdir -p "$HOME/.config/annodex" && echo "annodex config dir ok"

Recommended fix — point annodex (and optionally Codex) at a writable directory on local or scratch disk:

export ANNODEX_CONFIG_DIR=/scratch/$USER/annodex-config
mkdir -p "$ANNODEX_CONFIG_DIR"

export CODEX_HOME=/scratch/$USER/codex-home
mkdir -p "$CODEX_HOME"

annodex --hostname 0.0.0.0

Add those export lines to your shell profile or systemd unit so they persist across restarts.

Legacy env names ANNOVIBE_CONFIG_DIR / PIDEX_CONFIG_DIR are still accepted.

Configuration directory

Default annodex config root:

~/.config/annodex/

Override with:

ANNODEX_CONFIG_DIR=/path/to/writable/config

Key files

Older installs may still have annovibe-* or pidex-* filenames; annodex reads them for migration and writes new data under annodex-* names.

SOUL.md and HARNESS.md

On first start (annodex or annodex start), if SOUL.md or HARNESS.md is missing under the config directory, annodex copies neutral defaults from the package into that directory. Existing files are never overwritten on upgrade.

• SOUL.md — global tone and working style (persona). Edit $ANNODEX_CONFIG_DIR/SOUL.md or ~/.config/annodex/SOUL.md in your editor (not stored inside the project tree).
• HARNESS.md — visualization and output constraints (e.g. show-widget charts).

Each Linux user who runs annodex gets their own copy under $ANNODEX_CONFIG_DIR or ~/.config/annodex. If user A installs the npm package and user B runs annodex, B seeds into B's config dir on first start—not A's home.

Annodex runtime rules in code still override conflicting persona language in SOUL.md.

Providers and models

See Models for provider setup. Configured through Settings → Models or by editing providers.json.

Project registry and switcher

Projects you open are recorded in annodex-projects.json. In the workspace:

• The project switcher (top of the left sidebar) lists all unpinned projects. Pinned projects do not appear in the dropdown.
• Pin a project to keep it as an expandable Projects folder in the sidebar with chat history; drag pinned folders to reorder.
• The active unpinned project also appears as a temporary sidebar folder while selected.

Add projects from the switcher dropdown (Add project…) using the folder browser dialog.

File API (preview and download)

Project files are served under /api/files/{path}:

The FileViewer Download button uses type=download. See Usage — Preview files.

Project workspace files

Inside each project directory annodex may create:

Ensure the project directory itself is writable if you paste images or save project-scoped extension config.

Project memory files

Annodex loads these from the project root into the system prompt at thread start:

Working memory (agent retain / recall / reflect) is stored under config, not in the repo:

~/.config/annodex/memory/<sha1(project-cwd)>/entries.jsonl

Promote candidates from the Tools → Memory panel into MEMORY.md or CONTEXT.md, or use the promote API. Full design and MCP setup: Project Memory.

Project IM (WeCom)

Optional one WeCom bot per project — configured in Settings → Project → WeCom IM (credentials and pairing in the UI only):

Run the sidecar in the same Linux account as annodex: annodex im-gateway or annodex-im-gateway. Users must send the pairing code first before the agent runs. See Project IM for the full setup flow, group @mention rules, streaming replies, and API details.

Codex integration

Annodex uses your existing Codex CLI installation:

• Config: ~/.codex (or CODEX_HOME)
• History: threads and turns from Codex session storage
• Engine: codex app-server for live chat

No separate migration step — install annodex alongside Codex and configure providers in annodex if needed.

Extensions

Settings → Extensions manages MCP-style extension definitions:

• Global scope → ~/.config/annodex/extensions.json
• Project scope → {cwd}/.codex/extensions.json

The panel shows a simple default view for each extension: name, description, Saved for project, and Enabled in current chat. Open Advanced for ID, transport (stdio/http), command/URL, scope, install notes, and Install/Remove MCP actions.

Quick-add presets: Annodex Memory, Browser Use, and Custom MCP. Use Inspect local Codex to view MCP servers, plugin marketplaces, and installed plugins discovered from the Codex CLI.

Enable annodex-memory both in Extensions settings and from the chat bar Extensions menu before using retain/recall/reflect. See Project Memory.

CLI commands

Runtime behavior

• Default port 30121 (--port, PORT)
• Bind address 127.0.0.1 locally; use annodex --hostname 0.0.0.0 on Linux servers
• Connects to codex app-server (WebSocket on Linux/macOS by default)
• SSE streaming for live chat events; idle in-process sessions expire after ~10 minutes
• Optional web password via annodex passwd. When enabled, non-localhost requests are redirected to a login page. localhost requests to /api/im/*, /api/memory/*, and /api/tunnel/* bypass login so the IM gateway, memory MCP, and tunnel management continue working.
• Package updates can auto-restart the server when sessions are idle (ANNODEX_AUTO_RESTART=0 to disable)

Environment variables (common)

Legacy ANNOVIBE_* and PIDEX_* names are still read for compatibility.