Community: install once, run anywhere
The community build is a personal assistant. You install it once, keep your
model endpoint and API key in one place, and work on whichever folder you
choose — in the browser, or by starting Codumentor from that folder. See
Choosing the folder Codumentor works on.
What lives where
Two independent axes:
| Axis | Meaning | Default (community) |
|---|---|---|
| Instance home | Where conversations, logs, and indexes are stored | $CODUMENTOR_HOME (~/.codumentor) |
| Config layers | What the process believes | Bundled flavor default → user overlay → optional project YAML |
Starting codumentor in ~/src/foo does not write codumentor.yaml or
./data into foo. Chats persist under the user home. Indexes for foo are kept
separate from indexes for ~/src/bar.
Your personal settings (model base URL, API key, auth) live in
$CODUMENTOR_HOME/config.yaml, by default ~/.codumentor/config.yaml (on
Windows C:\Users\<you>\.codumentor\config.yaml). That file is the **user
overlay**. It is plain text; edit it with any text editor and restart
Codumentor to apply the change.
To change one extension's settings there (for example to give
Google Workspace
its client ID), add a plugins_overrides: entry naming that extension. Do not
write a plugins: list in this file: it replaces the whole built-in list and
silently switches off every extension you did not name.
First run: pick a model provider
The first time you start Codumentor from a terminal, before the user overlay
exists, it asks three things: which provider, which model (Enter keeps the
suggested one), and the API key.
| Menu entry | Key variable | Embeddings |
|---|---|---|
| OpenRouter | OPENROUTER_API_KEY | yes |
| OpenAI | OPENAI_API_KEY | yes |
| Google Gemini | GEMINI_API_KEY (or GOOGLE_API_KEY) | yes |
| DeepSeek | DEEPSEEK_API_KEY | no |
| Z.ai (GLM) | ZAI_API_KEY | no |
| Moonshot AI (Kimi) | MOONSHOT_API_KEY | no |
| Mistral | MISTRAL_API_KEY | yes |
| Ollama (local) | — | yes (embeddinggemma) |
| LM Studio (local) | — | yes (nomic-embed-text) |
| Other OpenAI-compatible endpoint | you type the URL | assumed on the same URL |
| ChatGPT subscription (Plus/Pro) — sign in from the browser | — (you sign in) | no |
| Skip — set up a model later in the browser | — | — |
- Press Enter at the key prompt to keep the key out of the file. The config then references the provider's variable, e.g.
${OPENROUTER_API_KEY}, and reads it at every start. If one of these variables is already set, that provider is the menu's default. - Paste the key to store it in the file instead. It is not echoed, and the file is made readable only by you.
- Everything the choice implies is written into the file: endpoint, model ids, the embedding model, and the few provider-specific settings a provider needs (temperature, how it is asked to reason, the context window), each with a comment saying why. Nothing is decided at runtime. To switch provider, edit the file, or delete it and start again.
- Providers without embeddings still chat. Personal recall and repository indexing need
models.embedding_*pointed at one that has them. - ChatGPT subscription and Skip are finished in the browser: open Settings > Models and choose Sign in with ChatGPT (or add an API key there). The first ChatGPT sign-in becomes the model new conversations use, unless you already picked one. Both write the file with the bundled models, so you are not asked again.
- Ctrl-D or Ctrl-C at any prompt writes nothing; you are asked again next time. Without a terminal (a service, a pipe) nothing is asked.
Opening it in the browser and logging in
Once Codumentor is running, open
http://127.0.0.1:2638/app in your browser
(2638 is the default port). Keep the Codumentor window open while you work;
closing it stops the assistant.
The login screen asks for a user name and password:
- User name:
admin - Password: generated on the first start and printed once in the Codumentor window, in a yellow box headed Codumentor admin password. It is also saved in the file
admin_passwordin your settings folder (~/.codumentor/admin_password; on WindowsC:\Users\<you>\.codumentor\admin_password), so you can look it up there any time.
To choose your own password instead, set the environment variable
CODUMENTOR_ADMIN_PASSWORD before starting Codumentor.
Project YAML is an overlay, not the instance
If a directory contains a codumentor.yaml (or the flavor filename) that was
discovered — you did not pass --config — community treats it as a **project
overlay** for that folder:
- It can name repos and project plugins.
- It cannot change your model endpoint or auth. Those stay in the user overlay.
- The first time Codumentor sees that file, it asks whether to trust it.
--configis always trusted and never prompts.--trust-project/--no-trust-projectskip the prompt for this run (--no-trust-projectdoes not remember the skip).
Enterprise-edition workspace servers still treat an on-disk YAML as the instance
when that is the product shape. See the admin configuration
guide for the two axes.
Conversations
The sidebar defaults to This folder on a user-home instance: chats tagged
with the current workspace. All shows every conversation, including
untagged ones from before this filter existed.
Flags
| Flag | Effect |
|---|---|
| `--home user\ | workspace\ |
--ephemeral | Shortcut for --home ephemeral |
--config PATH | That YAML is the instance (trusted; usually workspace home) |
--trust-project / --no-trust-project | Accept or skip a discovered overlay without prompting |