FAQ and Troubleshooting

Common questions and solutions for Codumentor users.

How do I set my API key?

Set the OPENAI_API_KEY environment variable:

export OPENAI_API_KEY="sk-..."

Or specify it in codumentor.yaml:

models:
  api_key: "${OPENAI_API_KEY}"

You can also use separate keys for different model types:

export OPENAI_AGENT_API_KEY="sk-agent-..."
export OPENAI_EMBEDDING_API_KEY="sk-embedding-..."

Which models work?

Codumentor works with any OpenAI-compatible endpoint. This includes:

OpenAI (GPT-4, GPT-4o, text-embedding-ada-002, etc.)
Google Gemini via the OpenAI-compatible gateway
OpenRouter for access to many model providers
Local models served via vLLM, LiteLLM, or any OpenAI-compatible server

Set the agent_base_url and embedding_base_url in your config to point to your provider.

Ingestion is slow

This is normal for large repositories. Ingestion involves cloning repos, reading files, chunking, and generating embeddings via API calls. To speed things up:

Add extra exclude_patterns_overrides to skip directories you do not need (common ones like node_modules, dist, __pycache__, vendor, and minified files are already excluded by default):

exclude_patterns_overrides:
  - "**/legacy/**"
  - "**/generated/**"

Lower ingestion.max_file_size to skip large files earlier (default: 1 MB).
Enable the embedding cache (on by default) so re-ingestion skips unchanged content.
Use include_patterns to narrow ingestion to only specific file types.

Vector DB errors

If you encounter errors related to the vector database, try deleting it and re-ingesting:

rm -rf data/vector_db
python -m codumentor.cli.main ingest

You can also use the --recreate flag to rebuild from scratch:

python -m codumentor.cli.main ingest --recreate

Shell commands not allowed

By default, Codumentor asks for confirmation before running shell commands. To allow all shell commands automatically:

In codumentor.yaml:

tools:
  shell_always_allow: true

In the TUI, shell auto-approval is controlled entirely through the config — there is no CLI flag.

In the Web UI, you can configure tool approval rules from the Settings dialog to allow or deny specific command patterns.

How do I use a local model?

Point agent_base_url and embedding_base_url to your local server:

models:
  agent: "my-local-model"
  agent_base_url: "http://localhost:8000/v1"
  embedding: "my-embedding-model"
  embedding_base_url: "http://localhost:8000/v1"

Any server that implements the OpenAI-compatible API will work. Popular options include vLLM, LiteLLM, and Ollama. See the LLM Server plugin for automated server management.

Web UI won't start

Make sure the UI has been built before starting the API server:

cd ui
npm install
npm run build
cd ..
python -m codumentor.cli.main api

Then open http://127.0.0.1:2638/app in your browser.

If the page is blank or returns a 404, verify the ui/dist/ directory exists and contains files.

How do I update?

Pull the latest source and reinstall dependencies:

git pull
pip install -r requirements.txt

If the Web UI has changed, rebuild it:

cd ui && npm install && npm run build && cd ..

If you are using the portable executable, download the latest version from the releases page.