Quick Start

Prerequisites

Node.js ≥ 18 (see installation options below)
A terminal / command prompt
An API key for at least one LLM provider (DeepSeek, OpenAI, Anthropic, etc.)
A writable home directory (or explicit config paths) — annodex and Codex persist data under $HOME by default. On Linux servers with tight home quotas, set ANNODEX_CONFIG_DIR and optionally CODEX_HOME before starting (see Configuration).

Recommended: Windows Install via Miniforge

Step 1: Download and install Miniforge

Download the Windows installer:

Miniforge3-Windows-x86_64.exe

Run the installer and finish the setup.

Step 2: Open Miniforge Prompt as administrator

On Windows:

Click the Start menu or the Windows search box.
Search for Miniforge.
Find Miniforge Prompt.
Right-click it and choose Run as administrator.

Step 3: Update conda and install Node.js

Run these commands in Miniforge Prompt:

conda update -n base -c conda-forge conda
conda install -c conda-forge nodejs

Verify Node.js and npm:

node --version
npm --version

Step 4: Install Codex and Annodex

npm install -g @openai/codex
npm install -g @seqyuan/annodex

Step 5: Initialize Codex

Run:

codex

If it asks you to log in, do not log in. Press Ctrl+C to exit.

Step 6: Start Annodex

annodex

Press Enter through the prompts.

When it asks for a password, you can:

press Enter to skip setting a password, or
type a simple password and press Enter.

Annodex will open in your browser. If it does not open automatically, visit:

http://localhost:30121

Step 7: Add your DeepSeek API key

In the Annodex web app:

Click Settings in the lower-left corner.
Open Models.
Add or edit the DeepSeek provider.
Paste the API key you received after topping up your DeepSeek account.
Save the settings.

Linux / macOS Install via Miniforge

Step 1: Install Miniforge

Download and install Miniforge from github.com/conda-forge/miniforge.

Step 2: Open Terminal and install Node.js

conda update -n base -c conda-forge conda
conda install -c conda-forge nodejs

Step 3: Install Codex and Annodex

npm install -g @openai/codex
npm install -g @seqyuan/annodex

Step 4: Initialize Codex

codex

If it asks you to log in, press Ctrl+C to exit.

Step 5: Launch

On macOS or a local Linux computer:

annodex

Open http://localhost:30121.

On a Linux server:

# Optional but recommended when $HOME is small or read-only:
export ANNODEX_CONFIG_DIR=/scratch/$USER/annodex-config
export CODEX_HOME=/scratch/$USER/codex-home
mkdir -p "$ANNODEX_CONFIG_DIR" "$CODEX_HOME"

annodex --hostname 0.0.0.0

Open this address from another device on the same network:

http://<server-ip>:30121

If the server firewall is enabled, allow the port:

sudo ufw allow 30121/tcp

Verify the config directory is writable:

touch "$ANNODEX_CONFIG_DIR/.write-test" && rm "$ANNODEX_CONFIG_DIR/.write-test"

Alternative: Direct Node.js Install

If you already have Node.js ≥ 18:

# Install Codex (one-time)
npm install -g @openai/codex
codex  # Ctrl+C at login prompt

# Install Annodex
npm install -g @seqyuan/annodex

Launch on Windows or macOS:

annodex

Launch on a Linux server:

export ANNODEX_CONFIG_DIR="${ANNODEX_CONFIG_DIR:-$HOME/.config/annodex}"
mkdir -p "$ANNODEX_CONFIG_DIR"
annodex --hostname 0.0.0.0

First Launch

On first launch, you'll see the annodex workspace with:

Left sidebar — project switcher (unpinned projects), pinned Projects folders with chat history, Add project…
Center panel — chat with model, thinking, tools, and sandbox controls
Right panel — Files and Tools tabs

See Usage Guide for screenshots of model setup, file preview, runtime status, and mobile usage.

Configure a Model

Before your first chat, configure at least one provider.

For DeepSeek:

Recharge your DeepSeek account on the DeepSeek website.
Copy your DeepSeek API key.
In Annodex, click Settings in the lower-left corner.
Open Models.
Add or edit the DeepSeek provider.
Paste the API key and save.
Select deepseek-chat or your configured DeepSeek model in the model selector.

See Models for more model configuration options.

CLI helpers

After installation you can use:

annodex doctor    # check Codex path, config dir, transport
annodex stop      # stop server; cleans orphaned codex app-server (IM gateway keeps running)
annodex restart   # stop then start
annodex logs      # tail server log
annodex im-gateway   # WeCom IM sidecar (while annodex is up)

See Configuration — CLI commands for details.