EVE AI Agent

Landing-page source: index.html. GitHub Pages is optional and is not currently a deployed product endpoint.

Self-hosted, chat-first AI assistant for EVE Online. Run it through the browser, Telegram, Discord DMs, or the terminal CLI; it combines local EVE SDE data, live ESI data, killboard intelligence, route planning, and a Responses-compatible model loop with tool calling.

The optional same-origin browser app uses the same backend agent and SQLite state. The project does not require Redis, Postgres, queues, workers, or webhooks.

v4.0.0 public release

v4 turns EVE AI Agent into a durable multi-user agent service while preserving the self-hosted single-process and SQLite architecture:

• A root agent builds and maintains a dependency-aware plan, tracks required outcomes, discovers deferred tools, and keeps working until the requested result is completed or explicitly reported unavailable.
• Independent public research can be delegated to bounded read subagents. They receive only allowlisted public tool schemas and public numeric IDs—never chat history, private ESI data, credentials, or write capabilities.
• Direct tool calls, parallel public reads, local parallel batches, and optional Programmatic Tool Calling share validation, admission, deadline, cancellation, identity, and output-size boundaries.
• The browser chat now uses a durable asynchronous SQLite queue with idempotent submission, authenticated SSE plus polling recovery, explicit cancellation, per-user lane serialization, and bounded global concurrency for public traffic.
• Browser users can keep several EVE characters attached to one account, choose the active character, and grant only the ESI scopes they want. Consent is versioned and presented in Russian and English.
• OpenAI remains the default provider path. The fixed CheapVibeCode Codex WebSocket transport supports the same application-owned local tools and defaults to the bounded public read-subagent path.
• Public deployment controls now include Turnstile verification, trusted-proxy CIDRs, HTTPS/hostname validation, request and compute-unit limits, durable restart recovery, queue health, and sanitized terminal errors.

The release evaluation covers complex multi-stage planning, tool discovery, parallel research, private/public data separation, cancellation, identity changes, terminal completeness, and a 100-user coordinator load scenario.

For a public SSO callback, use HTTPS, set the callback URL exactly in the EVE Developer Portal, generate a strong AUTH_SECRET_KEY, give ESI a reachable operator contact, and keep .env plus data/ on the host only. The detailed production checklist is in docs/deployment.md.

Capabilities

• Natural-language Telegram and Discord assistant for EVE Online questions and workflows.
• Same-origin browser chat with anonymous sessions, conversation history, optional EVE SSO, and the same guarded agent/tool loop.
• Durable multi-user browser execution with idempotent 202 acceptance, SSE/poll recovery, cancellation, per-user lanes, and bounded shared capacity.
• Dependency-aware root-agent planning, effective tool discovery, goal-ledger completion checks, parallel public reads, and sandboxed read subagents.
• EVE SSO linking for private character data, with scope-aware capability gating.
• Local SDE SQLite lookups for static game data such as systems, items, dogma, blueprints, and routes.
• Live ESI access for character, corporation, market, location, mail, skills, industry, assets, and related data when scopes are granted.
• Route planning with live danger analysis, killmail context, gate-camp signals, Thera/Turnur shortcut support, and monitor mode.
• D-scan, fleet, local, OSINT, current EVE-KILL REST/feed intelligence, EVE-Scout, and intel notes.
• Heartbeat notifications (mail, skills, wallet, industry, kills, and more) delivered to the chat where you talk to the bot.

Architecture

Telegram private chat ──> grammY long polling bot ─┐
Discord DM ───────────────> discord.js gateway bot ├─> shared agent runtime
Browser /app ─────────────> Fastify session API ───┘        │
                                                            v
                                      durable request coordinator + root agent
                                                             │
                           plan / goal ledger / tool registry / read subagents
                                                             │
                                                             v
                                    OpenAI or CheapVibeCode Responses transport
                                                             │
                                                             v
                                ESI / local SDE / EVE-KILL REST+feed ──> SQLite

Browser ──> Fastify ──> HttpOnly session + EVE SSO + /health ──> same SQLite state

Hard constraints:

• Single-process Node.js app.
• SQLite only.
• Telegram long polling only; no webhooks. Discord standard gateway connection.
• The browser app is explicit opt-in (WEB_CHAT_ENABLED=true), same-origin, and never receives provider or ESI credentials.
• Static game data comes from the installed local SDE SQLite snapshot; its build/load metadata describes that snapshot and is not a claim of current freshness. Live authoritative character/market data comes from ESI; public kill discovery comes from EVE-KILL.
• Private ESI access is isolated per user/chat and gated by get_eve_capabilities.
• The model must not see tokens, refresh flow, pagination internals, retry logic, or secrets.

Requirements

• Node.js 20.19+.
• npm.
• At least one bot token:
  • Telegram bot token from @BotFather, and/or
  • Discord bot token from https://discord.com/developers/applications (no privileged intents needed; the bot works in DMs).
• EVE Developer application from https://developers.eveonline.com/.
• A provider API key for the selected OPENAI_PROVIDER (openai or cheapvibecode).

Quick Start

git clone <your-public-fork-url> eveai
cd eveai
cp .env.example .env       # fill in the tokens
npm ci
npm run setup              # download + load EVE static data (SDE)
npm run dev

Then open a private chat with your Telegram bot, DM your Discord bot, or set WEB_CHAT_ENABLED=true and open http://localhost:3000/app.

For local EVE SSO callbacks, set the callback URL in the EVE Developer Portal to:

http://localhost:3000/auth/eve/callback

Required Environment

Minimum local .env values (enable at least one bot or the browser chat):

TELEGRAM_BOT_TOKEN=...        # and/or DISCORD_BOT_TOKEN
DISCORD_BOT_TOKEN=...
WEB_CHAT_ENABLED=true
WEB_BASE_URL=http://localhost:3000
OPENAI_PROVIDER=openai
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-5.6-sol
OPENAI_RESPONSE_STATE_MODE=stateless
OPENAI_STORE_RESPONSES=false
OPENAI_PROGRAMMATIC_TOOL_CALLING=false
OPENAI_REASONING_EFFORT=auto
OPENAI_REASONING_MODE=standard
OPENAI_TEXT_VERBOSITY=low
OPENAI_RESPONSES_TIMEOUT_MS=90000
OPENAI_RESPONSE_LANGUAGE=Russian
EVE_CLIENT_ID=...
EVE_CLIENT_SECRET=...
AUTH_SECRET_KEY=replace-with-random-secret
EVE_CALLBACK_URL=http://localhost:3000/auth/eve/callback
DEFAULT_MARKET_REGION_ID=10000002
DEFAULT_MARKET_REGION_NAME="The Forge"
ESI_USER_AGENT=EVEAI/4.0 (+https://github.com/your-org/eveai; [email protected])
EVE_KILL_USER_AGENT=EVEAI/4.0 (+https://github.com/your-org/eveai; [email protected])

Generate AUTH_SECRET_KEY with:

openssl rand -base64 32

Model defaults:

• OPENAI_PROVIDER=openai uses the official OpenAI HTTP/SSE endpoint. cheapvibecode selects the fixed CheapVibeCode Codex Responses WebSocket endpoint; arbitrary OPENAI_BASE_URL overrides remain disabled.
• The selected provider and its API key are process-wide operator settings. Browser users never provide or receive this key; each user gets an isolated opaque session and chat lane while requests share the configured concurrency and rate limits.
• OPENAI_MODEL=gpt-5.6-sol is the quality-first default. Use gpt-5.6-terra for a capability/cost balance or gpt-5.6-luna for latency-sensitive, high-volume deployments. The gpt-5.6 alias routes to Sol.
• OPENAI_PROGRAMMATIC_TOOL_CALLING=false keeps the default direct-tool path. Setting it to true opts into provider-entitled hosted programs for exactly nine bounded public-read tools: static counts, batch market prices, wormhole-type comparisons, Scout system searches, compact kill-activity summaries, market-history summaries, system-metric snapshots, doctrine summaries, and dynamic-item summaries. Restart after changing it. See OpenAI integration for schemas, budgets, exclusions, real smoke matrices, and rollback.
• OPENAI_RESPONSE_STATE_MODE=stateless is the default and rollback path. server reuses previous_response_id, requires OPENAI_STORE_RESPONSES=true, and falls back to canonical SQLite history if the provider state is missing or no longer matches its anchored assistant message.
• OPENAI_STORE_RESPONSES=false keeps provider-side Response logs opt-in. Set it to true to inspect requests in OpenAI Responses Logs; storage alone does not switch the state mode.
• OPENAI_REASONING_EFFORT=auto preserves EVE Agent's goal-based low|medium|high routing. Set none, low, medium, high, xhigh, or max to override it globally.
• OPENAI_REASONING_MODE=standard is the normal path. Set pro only for difficult quality-first workloads that justify higher latency and token use; Pro is a mode, not a separate model name.
• OPENAI_TEXT_VERBOSITY=low keeps chat answers compact; set medium if your community wants longer explanations.
• OPENAI_RESPONSES_TIMEOUT_MS=90000 controls the Responses transport deadline; raise it deliberately when evaluating Pro.
• OPENAI_RESPONSE_LANGUAGE=Russian sets the default final-answer language. Aliases like ru, русский, en, English, and custom language names are accepted; an explicit user request can override it per answer.

These are process-wide self-hosting controls shared by Telegram, Discord, and CLI. They are not per-chat preferences. See OpenAI integration and OpenAI's GPT-5.6 guide.

EVE SSO Setup (private character data)

The current process configuration requires EVE Developer credentials at startup, even if an operator initially uses only public data. Character linking itself is optional: after credentials are configured, public SDE, market, route, killboard, and OSINT workflows work without linking a character. To unlock private ESI (skills, assets, wallet, location, mail, …), register a free EVE Developer application (~5 minutes):

1. Open https://developers.eveonline.com/applications/create and sign in with your EVE account.

2. Connection Type: choose Authentication & API Access, then select the scopes you want to support (or all of them for full parity).

3. Callback URL: set it to exactly your EVE_CALLBACK_URL. For local use:

   http://localhost:3000/auth/eve/callback
   

4. Copy the Client ID and Secret Key into .env:

   EVE_CLIENT_ID=your_client_id
   EVE_CLIENT_SECRET=your_secret_key

5. Restart. /login in the CLI and /eve_login in Telegram or Discord now return a working SSO link.

Terminal CLI (no bot token needed)

Talk to the agent directly in your terminal — a third platform adapter beside Telegram and Discord, driving the same runtime. It needs the same local .env configuration as the app, but no Telegram or Discord bot token:

npm run cli

┌─ EVE AI Agent v4.0.0 · CLI ────────────────────────┐
│ Talk to the agent in your terminal. Commands:      │
│   /login   link an EVE character (opens SSO)       │
│   /whoami  show the active character               │
│   /clear   wipe this conversation                  │
│   /version check project updates                   │
│   /exit    quit                                    │
└────────────────────────────────────────────────────┘
eve> route from Jita to Amarr, is it dangerous?

Public tools (SDE lookups, market, route planning with danger analysis, killboards, OSINT) work without a linked character. Run /login to link an EVE character via SSO and unlock private ESI (skills, assets, location, mail, …). The full bots still need a Telegram or Discord token; the CLI does not. While the CLI process is open, kill_watch and route monitoring use the same durable EVE-KILL feed lifecycle as Telegram and Discord. Their SQLite state survives a restart and eligible route monitors are restored on the next CLI launch. Events missed while the CLI is closed are not replayed. Heartbeat configuration remains bot-service-only and is intentionally hidden in the CLI.

Only one bot service or CLI may own a given DB_PATH at a time. A DB-adjacent runtime lock rejects a second process so two feed pollers cannot race the global cursor.

While the agent works, the CLI shows a live activity feed — a brief "thinking" note and one line per tool/skill as it runs (e.g. 🗄 SDE query, 💰 market prices, 🛰 ESI · …) — then renders the finished answer:

eve> Сколько стоит Plex?
  💭 Checking PLEX price; resolve type_id, then market price
  🗄  SDE query · query
  💰 market prices · 1 item
PLEX: 4,621,543 ISK (global average — no regional order book).

This feed is CLI-only: the Telegram and Discord bots reply with one finished message and are unaffected. The answer is rendered once from the finalized (sanitized) text, not streamed token by token, so it is always clean and complete.

Scripts

npm run cli            # interactive terminal agent (no bot token required)
npm run dev            # tsx watch mode (recommended for running the bots)
npm run build          # compile server (tsc)
npm start              # run built app: node dist/app.js
npm run check          # typecheck + tests + lint
npm test               # vitest
npm run smoke          # env, model endpoint, app health checks
npm run smoke:openai   # authenticated provider-aware Responses probe
npm run smoke:eve-tool # authenticated model + EVE SDE tool probe
npm run eval:agent     # deterministic multi-stage orchestration evaluation
npm run eval:web-load  # 100-user durable queue/isolation load harness
npm run update:check   # read-only latest stable release check
npm run db:migrate     # run SQLite migrations
npm run setup          # download and load SDE data

On startup the app prints a status banner with database, SDE, HTTP, platform, OpenAI, and heartbeat state. Structured logger output is timestamped and redacts recognizable credentials; request-level diagnostics can still contain short user goals, tool arguments, reasoning summaries, or provider-error snippets. Treat process logs as private operational data.

Runtime Smoke Test

Authenticated OpenAI smoke test:

OPENAI_API_KEY=... npm run smoke:openai

EVE tool smoke test:

OPENAI_API_KEY=... npm run smoke:eve-tool

For a DB-only SDE tool check without calling the model:

EVE_TOOL_SMOKE_MODE=direct npm run smoke:eve-tool

The scripts print only sanitized endpoint/model/tool metadata and answer previews. They never log API keys.

Self-Hosting

See docs/deployment.md for a generic production deployment guide. Before publishing a fork or a release, run npm run audit:public, npm run check, and npm run build. Keep operator-specific server addresses, credentials, logs, certificates, and runbooks outside this repository.

Documentation

• AGENTS.md: concise repo map and invariants.
• ARCHITECTURE.md: runtime boundaries and request flows.
• docs/index.md: documentation catalog.
• docs/SECURITY.md: security rules and current gaps.
• docs/RELIABILITY.md: reliability model.
• docs/deployment.md: generic self-host guide.
• docs/openai-integration.md: OpenAI Responses API configuration.
• docs/generated/db-schema.md: SQLite schema reference.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, keep PRs focused, and run npm run check when feasible. Good first areas include documentation, reproducible bug fixes, prompt tests, EVE SDE lookups, chat formatting, and self-hosting troubleshooting.

Please do not include secrets, private deployment notes, server IPs, logs, database files, or SDE dumps in issues or pull requests.

Legal Notice

EVE Online and all related logos, images, and trademarks are the property of CCP hf. This project is a third-party tool and is not affiliated with, endorsed by, or supported by CCP Games.

Use of EVE Online SSO, ESI, SDE, and related game data is subject to the EVE Online Developer License Agreement. Each self-hosting operator is responsible for accepting and complying with that agreement when creating an EVE Developer application and running an instance.

Community Showcase Readiness

The ready-to-copy Showcase page and evidence-backed eligibility matrix are in docs/community-showcase.md. GitHub records the canonical garshany/eveai repository's initial public event on 2026-03-24, and its public CI history includes a master run on 2026-03-25. The three-month public-age requirement has therefore passed; re-check the current CCP requirements immediately before submitting.

Open-Source Safety Notice

If you are publishing a fork that previously contained private deployment files or secrets, do not make that repository public as-is. Publish from a clean sanitized export or rewrite history, rotate exposed credentials, and run a secret scan before release.

License

MIT. See LICENSE.