Athena

A chatbot for Northeastern Electric Racing. Ask a question about the team in plain English — the car, the code, the process, the history — and get a direct answer drawn from NER's own documentation, with citations.

NER's institutional knowledge is real, extensive, and hard to reach. It's spread across systems with no common search, organized by conventions nobody tells you about (software carries over year to year, so the reasoning behind a system named on the 25 page usually lives on the 22 or 17 page), and the team turns over annually. Every year a cohort re-derives what the last cohort already knew, and the people who could answer fastest are the leads whose time is scarcest.

Athena is the attempt to fix that.

Its typical user is not a software engineer. A first-semester member asking "what does TSAL mean?" should get a good answer without knowing that a wiki called Confluence exists.

---

What works today

Confluence-backed Q&A, running on one machine.

URL	http://localhost:3003 — the default; change it with ATHENA_PORT
Sources	Confluence, NER space — 1,951 documents indexed
Models	OpenRouter: z-ai/glm-5.3, deepseek/deepseek-v4-pro, qwen/qwen3.8-max, moonshotai/kimi-k3. Switchable in the chat picker.
Embeddings	Local model server (nomic-embed-text) — content never leaves the machine
Auth	Basic, 3 accounts. Registration is open to anyone who can reach the port.
Tools	Internal search, open_url, sandboxed code execution
Branding	NER's — FinishLine's red (#ef4345), NER logo, Lato body type. See docs/OPERATIONS.md.
Not wired up	Web search, image generation, Slack/GitHub/telemetry/FinishLine, SSO

Verified end-to-end in a real browser: login → ask → cited answer from real Confluence pages.

Two things are half-done

1. The default assistant has no system prompt. Athena currently answers as stock Onyx, with no NER navigation knowledge or glossary. The prompt is written and ready at docs/system-prompt.md — it has to be pasted into /admin/configuration/chat-preferences. Prompts for a set of tool-specific agents are drafted in prompts/, also uninstalled, and depend on toolsets that aren't wired up yet.
2. The Confluence connector is paused, and a second orphaned connector with no credential is still sitting in the database.

Where it came from

Athena is a fork of Onyx, an open-source RAG and agent platform. The fork point is commit 3f11d9e, and the upstream repo is wired up as the upstream remote so we can keep pulling its changes in.

What that buys us: a multi-cycle tool-calling agent loop, 50+ connectors, citation rendering, streaming, SSO, and multi-provider LLM routing — none of which we'd have written ourselves, and all of which keeps improving without us.

The whole tree is upstream's, including backend/ee/ and web/src/ee/. NER's changes are deliberately small and additive — branding, design tokens, a landing page, docs, and a test harness — so that git merge upstream/main stays a cheap operation rather than a rewrite. Before changing an upstream file, ask whether the same result can be reached by adding one instead.

One consequence of re-forking: encryption-at-rest for credentials is available again — it lives in backend/ee/onyx/utils/encryption.py, which the earlier gutted tree had removed. It is still off, because ENCRYPTION_KEY_SECRET is unset, so the Confluence token remains plaintext in Postgres. Turning it on is a migration, not a flag: existing rows have to be re-encrypted (backend/scripts/reencrypt_secrets.py).

Running it

You need Docker with ~8 GB available to it.

cd deployment/docker_compose
docker compose up -d

Then open http://localhost:3003.

On a different port, if 3003 is taken:

ATHENA_PORT=3007 docker compose up -d      # or put ATHENA_PORT=3007 in .env

ATHENA_PORT is the only host port the stack publishes — see docs/OPERATIONS.md.

Action	Command
Stop, keep containers	docker compose stop
Status	docker compose ps
Logs	docker compose logs -f api_server
Rebuild after a code change	docker compose up -d --build
Remove containers, keep data	docker compose down
Delete everything including data	docker compose down -v

Images are built from this source tree, not pulled — a code change needs --build. Config lives in deployment/docker_compose/.env (gitignored); changes there need --force-recreate.

If the UI says "the backend is currently unavailable," it's almost always nginx holding a stale upstream IP, not a real failure. docker compose restart nginx. See docs/OPERATIONS.md for the rest.

Repo layout

Onyx's structure, which we inherited:

backend/	FastAPI + Celery. Python 3.13, SQLAlchemy, LiteLLM. alembic/ holds migrations.
web/	Next.js 16, React 19, TypeScript, Tailwind.
deployment/	Docker Compose, Helm, Terraform. We use docker_compose/.
docs/	OPERATIONS.md and system-prompt.md are ours; the rest is upstream Onyx's, left where upstream put it.
prompts/	Ours. Tracked system prompts for Athena's agents — none installed yet.
e2e/	Ours. Playwright smoke tests, standalone package.json.
mobile/, desktop/, widget/, extensions/, cli/	Onyx surfaces we don't use. Untouched.

Docs

File	What it is
docs/OPERATIONS.md	Services, config, admin routes, and the failure modes we've actually hit
docs/system-prompt.md	The NER system prompt — version of record
prompts/README.md	System prompts for the planned agents (documentation, GitHub, FinishLine, Penelope, general) — drafts, not installed
e2e/README.md	Browser smoke tests
CONTRIBUTING.md	How to work on this
AGENTS.md, backend/AGENTS.md, web/CLAUDE.md	Upstream Onyx's own engineering guides. Accurate for this tree.

Before this leaves localhost

Not optional, and not yet done:

• Registration is wide open. The first stranger to reach the signup endpoint gets an account. Turn on invite-only at /admin/security first.
• Credentials are plaintext in Postgres.
• The code interpreter executes code in an app that would be club-reachable. Confirm sandbox isolation and network egress.
• Upstream fixes are not automatic. Onyx patches vulnerabilities in code we run, but they only reach us when someone merges upstream/main. Someone has to own doing that on a schedule.

License

Upstream's dual license, unchanged — see LICENSE. Onyx's copyright notice is preserved as required.

Everything outside the ee directories is MIT. backend/ee/, web/src/ee/, and web/src/app/ee/ are under the Onyx Enterprise License, which permits reading and modifying the code but requires a paid Onyx subscription to use it in production. Athena does not have one, so the enterprise features stay gated off by license tier: the ee module loads, but with no license key the paid features are unavailable. Everything Athena actually uses — chat, connectors, the agent loop — is MIT. Enabling a gated ee feature is a licensing decision, not just a config change.