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.)

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:

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

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:

annodex --hostname 0.0.0.0

First Launch

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

Left sidebar — project list and file explorer
Center panel — chat interface with model/tool controls
Model selector — choose your configured providers

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.