Apex Upgrade Guide¶

What Survives Upgrades (no action needed)¶

These are stored outside the codebase and are never touched by git pull:

Data	Location	Notes
Database (chats, messages, profiles)	`state/apex.db`	Gitignored. Schema auto-migrates on startup.
Custom personas	`state/apex.db` (agent_profiles table)	Seeded with `INSERT OR IGNORE` — existing profiles are never overwritten.
Alert categories	`state/config.json` → `alert_categories`	Merged on top of code defaults at startup.
Alert category titles	`state/config.json` → `alert_category_titles`	Same merge behavior.
Server config	`state/config.json`	All runtime config. Gitignored.
SSL certificates	`state/ssl/`	Generated by `setup.py`. Gitignored.
API keys / secrets	`~/.apex/.env` (or `APEX_ENV_FILE`)	Never in the repo.
Personal launcher	`server/launch_apex.sh`	Main launcher. Loads `.env` automatically.

What Changes on Upgrade¶

Component	Behavior
Default personas	New defaults may be added (via `INSERT OR IGNORE`). Existing ones untouched.
Code-level alert categories	The built-in map may change, but your `config.json` overrides always win.
API endpoints	May be added/changed. Check release notes.
Dashboard UI	Embedded in code — updates with each pull.
Setup wizard	May gain new steps. Re-run `setup.py` if prompted.

Upgrade Procedure¶

# 1. Stop the server
pkill -f apex.py

# 2. Pull latest code
cd /path/to/apex
git checkout main
git pull origin main

# 3. Check for new dependencies
pip install -r requirements.txt

# 4. Restart
bash server/launch.sh
# (recommended: bash server/launch_apex.sh for mTLS support)

The server auto-migrates the database schema on startup. No manual SQL needed.

Personal Overrides Reference¶

Custom Alert Categories¶

Add to state/config.json:

{
  "alert_categories": {
    "my_source": "my_category",
    "another_source": "my_category"
  },
  "alert_category_titles": {
    "my_category": "My Custom Alerts"
  }
}

These merge with (and override) the built-in defaults on every startup.

Custom Personas¶

Create via the dashboard (/admin → Workspace → Profiles) or the API:

curl -X POST https://localhost:8300/api/profiles \
  -H "Content-Type: application/json" \
  -d '{"name": "MyAgent", "slug": "myagent", "system_prompt": "You are...", "model": "claude-opus-4-6"}'

Custom profiles persist in the database and are never overwritten by upgrades.

Environment Overrides¶

Set APEX_ENV_FILE in your personal launcher to point to your .env:

export APEX_ENV_FILE="$HOME/.my-custom-path/.env"

The generic launch.sh searches these locations in order: 1. $APEX_ENV_FILE (if set) 2. ~/.apex/.env 3. ~/.config/apex/.env