Installation & operations

1. Requirements

• Linux (Python 3.10+) or Windows 10/11 (portable bundle includes its runtime).
• Codex CLI installed and available as codex, or configured with an absolute executable path.
• Write access to the queue state directory and to every working directory used by jobs.
• For notifications or remote sync: outbound HTTPS access, DNS and a valid TLS trust store.

SQLite is used by default. Keep the database and attachment directory on reliable local storage; do not place them on an eventually-consistent network share.

2. Linux installation

cd /opt/xnexus-station
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m py_compile xNexusStation/src/worker/nexus_station.py xNexusStation/src/web/nexus_station_web.py
python xNexusStation/src/worker/nexus_station.py stats

Set XNEXUS_STATION_HOME to a dedicated persistent directory when the default ~/.local/state/xnexus-station is not suitable.

export XNEXUS_STATION_HOME=/var/lib/xnexus-station
mkdir -p "$XNEXUS_STATION_HOME"
python xNexusStation/src/worker/nexus_station.py stats

3. Windows installation

Extract xnexus-station-for-windows to a fixed directory without spaces if possible. Run setup.cmd once, then start the worker and web console from that directory.

cd C:\Tools\xnexus-station-for-windows
setup.cmd
start_worker.cmd
start_web.cmd

The portable bundle uses the current Windows user profile for Codex configuration (%USERPROFILE%\.codex). Do not copy credentials into the bundle.

4. Initialize and create a first job

# inspect the queue
python xNexusStation/src/worker/nexus_station.py stats

# enqueue a test job
python xNexusStation/src/worker/nexus_station.py add "ping" --cwd "$PWD" --profile <PROFILE> --model <MODEL>

# run one worker (foreground smoke test)
python xNexusStation/src/worker/nexus_station.py worker --once

Database tables and the default local_project are created lazily on first access. Run a smoke test before registering long-running services.

5. Start the services

Run exactly one worker per queue database. The web console can run separately.

# worker
python xNexusStation/src/worker/nexus_station.py worker --poll 1

# web console (loopback by default)
python xNexusStation/src/web/nexus_station_web.py --host 127.0.0.1 --port 8765

For systemd, use a dedicated unprivileged service account, an absolute WorkingDirectory, restrictive file permissions, automatic restart with a bounded rate, and a separate web service unit. Do not run the worker as root.

6. Initial web configuration

1. Open /config and set a server name/description if needed.
2. Create an API token at /api-tokens; copy the secret immediately.
3. Verify profiles/models on /jobs/new.
4. Configure webhook/Telegram notifications and use their test buttons.
5. Configure Remote jobs sync only after the local queue is healthy; set interval, endpoint, auth and filters.

Secrets are stored in the local SQLite configuration table. Restrict database permissions and never commit or print the database, tokens, bot credentials or custom headers.

7. Network and TLS

Bind the application to loopback and terminate TLS at a trusted reverse proxy. If direct binding is unavoidable, use firewall allowlists and a strong access token.

# example reverse-proxy target
http://127.0.0.1:8765

• Forward only the required host/path.
• Disable proxy buffering for any future streaming endpoints.
• Set request and upstream timeouts; limit request body size.
• Do not expose SQLite files, attachments or logs as static files.

8. Backups, upgrades and recovery

• Stop or quiesce the worker before copying the database; include the attachments and logs directories.
• Keep encrypted, access-controlled backups and periodically test a restore into an isolated directory.
• Before upgrade, record the current version, run syntax checks and take a backup.
• After upgrade, start the web console, verify /api/v1/health, then start one worker and process a smoke-test job.
• If a worker is interrupted, it recovers RUNNING jobs to QUEUED on restart; inspect logs before retrying manually.

9. Troubleshooting