Agnostos v3 · source and self-hosting guide

Agnostosthe self-hosted web app for research internship outreach

Agnostos v3 is a self-hosted web app for research internship outreach. It is built on the Agnostos command-line pipeline (v2). Each user signs up, uploads a resume, and adds their own mailbox and model key. From the browser they can find professors, verify emails, draft emails, send them paced from their own inbox, read replies and send follow-ups. A FastAPI server runs the v2 pipeline as a subprocess for each job.

  • FastAPI
  • SQLAlchemy + Alembic
  • PostgreSQL / SQLite
  • Fernet encryption
  • Tailwind (prebuilt)
  • Groq / OpenAI
  • OpenAlex
  • WebView2 desktop

No public hosted instanceThere is no public Agnostos service to sign up for. This page describes the source code and how to run it yourself. Hosted deployment is paused, and live sending is off by default.

The Agnostos v3 landing page served from the repository's web folder: a soft pastel layout with the headline 'Write to professors gently, and actually hear back.'
The landing page in web/index.html, rendered locally from the repository.

01What it does

Agnostos v3 puts the v2 outreach pipeline behind an accounts-based web interface. Each user's resume, settings, credentials and job outputs stay in that user's own workspace.

  1. Discover
    Find professors whose recent papers match your resume, using OpenAlex publication data.
  2. Verify & score
    Check addresses, then score each match locally before any model call.
  3. Draft
    Write a personalised email for each match with your own Groq or OpenAI key.
  4. Send & reply
    Send paced emails from your own mailbox, read replies and draft follow-ups.

Researchers library

A database-backed contact list with add, edit, delete, search, pagination, and XLSX import and export. Imports never approve or send mail.

Jobs dashboard

Pipeline commands run as background jobs. Their logs stream to the browser, and you can cancel a running job.

Desktop preview

A Windows build that serves the same interface on 127.0.0.1 inside a WebView2 window. Sending and the scheduler are always disabled in this build.

02How it works

web/

Landing page and dashboard. Plain HTML and JavaScript, with the compiled Tailwind CSS and fonts checked in. Works offline.

server/

FastAPI handles authentication, per-user workspaces, encrypted credentials, the job runner and the daily scheduler, with SQLAlchemy storage.

outreach/

The v2 command-line pipeline, unchanged. Each job runs it as a subprocess inside that user's workspace.

  • Credentials. SMTP and IMAP passwords and API keys are encrypted with Fernet using APP_SECRET. They are passed only into that user's job environment. Passwords are hashed with PBKDF2-SHA256.
  • Allow-listed jobs. The UI can run only profile, tls-check, stats, discover, verify, run, send, check-replies and replies. Each command accepts a fixed set of flags. Values are type-checked, so raw arguments never reach the shell.
  • Send gate. The API refuses send jobs, replies --send jobs and enabled schedules unless AGNOSTOS_LIVE_SEND_ENABLED=true is set deliberately. The Docker Compose file defaults it to false.
  • Storage. Accounts, settings, sessions, job history, schedules and contacts use SQLAlchemy with Alembic migrations. Docker Compose provisions PostgreSQL 17. Local development keeps using data/agnostos.db (SQLite) unless DATABASE_URL is set. Each user's files live in /data/users/<id>/.

03Status

These statements are taken from the repository's README and docs/database.md.

PartState
Accounts, settings, job history, Researchers libraryDatabase-backed. Uses SQLAlchemy and Alembic, with SQLite locally and PostgreSQL in Docker.
Pipeline sending and reply queuesStill legacy. Jobs use workbooks, and Replies uses a JSON queue. The contact library does not feed the sender.
Windows desktop previewAvailable from source. A CI artifact is built from main. It is a private preview without the v2 safety guarantees, and sending is disabled.
Hosted deploymentPaused. No public instance exists. The Oracle VM staging guide is kept as a historical plan.
Next milestoneDatabase-backed campaigns, drafts, approvals and send attempts; a durable worker queue; a shared React interface and a Tauri desktop client.
Not for live campaigns yet. Do not expose v3 as a public mail service before the v2 features and safety fixes have been carried over and campaigns have been migrated. To send real outreach today, use the Agnostos v2 command-line tool on your own computer.

Screenshots

Agnostos landing page with the headline 'Write to professors gently, and actually hear back'.
Landing page (web/index.html).
Agnostos dashboard sign-in card with email and password fields and a sign-in button.
Dashboard sign-in (web/app.html), before an account exists. Both pages were captured from the repository's static files; no user data is shown.

04Run it yourself

Quick start (local)

start.cmd          # Windows
./start.sh         # macOS / Linux

Then open http://localhost:8000. The scripts install requirements.txt and server/requirements.txt and start Uvicorn on port 8000. Note that they bind to 0.0.0.0, so other machines on your network can reach the server.

No-send preview of the Researchers library

$env:AGNOSTOS_SCHEDULER_ENABLED = "false"
python -m uvicorn server.app:app --host 127.0.0.1 --port 8000

Open http://localhost:8000/app.html, sign in, and select Researchers. Disabling the scheduler does not block Pipeline jobs that you start manually.

Windows desktop preview

You need Python 3.13 (64-bit) and the Microsoft Edge WebView2 Runtime.

py -3.13 -m pip install -r desktop-requirements.txt
py -3.13 desktop.py

# distributable folder (needs Node.js/npm for the stylesheet build)
.\build-desktop.ps1 -Python "C:\Path\To\Python313\python.exe"
.\dist\Agnostos\Agnostos.exe --health-check
.\dist\Agnostos\Agnostos.exe

Distribute the whole dist\Agnostos folder. The first launch creates %LOCALAPPDATA%\Agnostos\, which holds its own SQLite database, encryption key, uploads and job output. Back up that directory as a whole. Deleting its .app_secret makes the encrypted settings unreadable.

Docker Compose with PostgreSQL

# .env (never commit it)
APP_SECRET=<Fernet key; keep the original key when upgrading>
POSTGRES_PASSWORD=<long random hex password>
AGNOSTOS_SCHEDULER_ENABLED=false
AGNOSTOS_LIVE_SEND_ENABLED=false

docker compose up -d --build

The app is published only on 127.0.0.1:8000, and PostgreSQL is not published to a host port. Run one API process only; the job runner and scheduler are not a distributed queue. Put an HTTPS reverse proxy in front before exposing the app.

What each user needs

  • A model key. A Groq key is free. With OpenAI gpt-5-mini, the README estimates about $0.004 per draft.
  • A mailbox with an app password. For Gmail, turn on 2FA and create an app password.
  • A resume (PDF or DOCX), and optionally a CV PDF to attach.

05Limitations

  • No public instance exists, and hosted deployment is paused. Anyone who uses Agnostos v3 runs it on their own machine or server.
  • The sending path is the legacy v2 pipeline and does not include v2's later safety fixes. The desktop preview and the default Docker settings disable sending.
  • If you host it, users' mailbox passwords are stored on your server. Use a strong APP_SECRET, keep backups encrypted and publish a privacy note.
  • Every user's jobs run on one machine. A paced send of 40 emails takes 4 to 7 hours, so the host needs a process that stays up, a persistent disk and outbound SMTP. Serverless and sleeping free tiers do not work.
  • Each user sends from their own mailbox, so deliverability and rate limits apply per user. Keep DAILY_SEND_CAP at or below 40.
  • In the desktop preview, other processes on the same PC can reach the loopback HTTP service while the window is open.