Alphadesk Terminal

AlphaDesk — dense, fast market-research terminal & MCP integration platform

A dense, fast market-research terminal and integration platform. Readers connect their own market-data and news providers; AlphaDesk is the workspace that connects, checks and presents what those providers — and the public record at SEC EDGAR and the US Treasury — actually say. Questions are asked in the reader's own AI agent (Claude, ChatGPT, Codex, Cursor, opencode), which reads the same records through 53 read-only agent tools (MCP).

AlphaDesk reads: quotes and charts, news, SEC filings, financial statements, ownership and insider activity, earnings and corporate calendars, options, crypto. It does not trade, route orders, hold positions, score ideas or write summaries.

Two ways to use it — the managed cloud or your own server. The code is open source under the GNU AGPL-3.0, with a commercial licence for anyone who cannot meet its terms. See Licence.

Figures in every screenshot are blurred on purpose: they came from a reader's own vendor keys, and vendors restrict public display of their data. The layout is the real thing.

Quick start — run it yourself, for one person

You need Python 3.11+ (or Docker; where a command below says python and your shell only knows python3, use that, or the virtual environment's own python), and your own market-data and news keys for anything beyond SEC EDGAR and Treasury data. No account, no sign-in, no database to set up.

pip install alphadesk

python -m alphadesk.main init --email you@example.com

python -m alphadesk.main dashboard

Open http://127.0.0.1:8000, then connect your vendors on the Account page and your agent on Agent access. init runs once: it makes the settings file ~/.alphadesk/.env (owner-only) holding a vault key that seals your stored vendor keys, the contact address the SEC asks for, and single-person mode. Keep a copy of that file — without the vault key the stored vendor keys cannot be opened. The server listens on this machine only.

To run exactly what the cloud runs — Postgres and a login of your own, instead of SQLite and no sign-in — set it up with --like-cloud. It asks for a password (type it in a terminal; it is never printed), makes the settings file with a password hash, and creates the Postgres database if the server is running:

brew install postgresql@16 && brew services start postgresql@16

python -m alphadesk.main init --email you@example.com --like-cloud

Then python -m alphadesk.main dashboard as above, and sign in with that email and password. Use --login for a different login email, --database-url for another Postgres, and --password-hash (from python -m alphadesk.main hash-password) to skip the prompt. For a setup with no typing at all, for example from a script:

python -m alphadesk.main init --email you@example.com --like-cloud --password-hash "$HASH" --database-url postgresql://localhost:5432/alphadesk

What to know about the Postgres path:

• Version. It is built and run against Postgres 16. The driver is a pure-Python one that comes with the install, so there is nothing to compile.
• The database. init --like-cloud creates the database if the server is running and the user may create databases. If it cannot, it still writes the settings and prints what to do, usually createdb alphadesk (or start Postgres first). Tables are created at the first start, and starting again is safe.
• The word-search index. The first start also tries to create the pg_trgm extension and the indexes that make word search fast. If the database user may not create extensions (some managed services), the log says so once and search still works, only without the index. Ask the service to allow pg_trgm, or run CREATE EXTENSION pg_trgm as an administrator, and restart.
• Moving from SQLite. The two stores are separate: switching an existing setup to Postgres starts with an empty ledger. Your vendor keys sealed in the old store are not carried over, so keep the settings file and add the keys again on the Account page, or import them with python -m alphadesk.main keys import-file.
• Backups. The ledger is one database: back it up with pg_dump. Keep the vault key in the settings file as well, because stored vendor keys cannot be opened without it.

With Docker instead:

ALPHADESK_CONTACT_EMAIL=you@example.com docker compose up -d

The first start does the same setup inside a data volume and keeps it there. It also starts Postgres beside the app, the same database the live server runs, so what you test locally is what runs in the cloud; the word search uses a Postgres index there that SQLite cannot have.

What to know about the Docker path:

• The first build is large and slow. The image holds Python, a CPU-only build of the machine-learning library and the 1.2 GB embedding model that search by meaning uses, baked in so a starting container fetches nothing. Expect several gigabytes and a long first build. ALPHADESK_SEMANTIC_SEARCH=off stops the model being loaded when the app runs; it does not shrink the image.
• Two volumes hold everything. alphadesk-data has the settings file (with the vault key) and alphadesk-pg has the database. docker compose down keeps both; docker compose down -v deletes them and with them your history and stored keys.
• Back up the settings file. docker compose cp alphadesk:/data/.env ./alphadesk.env copies it out. Without the vault key the stored vendor keys cannot be opened.
• Update. git pull, then docker compose up -d --build. Settings and data stay. Watch it with docker compose logs -f alphadesk.
• No sign-in inside the container. It runs in single-person mode on 127.0.0.1:8000, as above. For a login of your own use the host setup with --like-cloud, or put an access token in front as described below.
• Agents. Create the token on the Agent access page as usual; the tools answer on http://127.0.0.1:8000/api/agent/tools/mcp. To reach them from another machine, set ALPHADESK_BASE_URL to the address that machine uses and ALPHADESK_ALLOWED_HOSTS for any other name, and keep an access token in front.

Reachable from other machines? Sign-in is off in this mode, so anyone who can reach the port can use it and read your connected vendors. Keep it on 127.0.0.1, or set an access token — the browser then asks for it once, and agents keep using the tokens you make on Agent access:

python -c "import secrets; print(secrets.token_urlsafe(24))"

Put the result in ~/.alphadesk/.env as ALPHADESK_ACCESS_TOKEN=... (with Docker, pass it as an environment variable) and restart. Over the internet, put HTTPS in front of it.

Other ways to run it, serving other people, and every setting are under Two ways to run it and Configuration reference.

---

Contents

1. What AlphaDesk is — and is not
2. Two ways to run it
3. Design principles
4. Features
5. Data sources
6. Search
7. Agent access (MCP)
8. Accounts, security and privacy
9. Architecture
10. Repository layout
11. Development
12. Configuration reference
13. Production deployment and operations
14. Testing and quality
15. Known limitations
16. History
17. Licence

---

What AlphaDesk is — and is not

It is offered free at present (payments are designed but switched off; see Accounts).

---

Two ways to run it

Option A — Managed cloud

1. Open the hosted terminal and sign in with the email and password its operator set. There is one user per server and no sign-up.
2. On the Account page, connect the market-data and news providers you already use (Alpaca, FMP, Finnhub, Polygon, …). SEC EDGAR and the US Treasury need no key.
3. Optional: connect your own agent from the Agent access page (in the sidebar, beside Account) — a token for Claude Code, Codex, Cursor or opencode, or add the server URL as a connector in Claude.ai or ChatGPT.

Option B — Self-hosted (AGPL-3.0)

You need a SEC User-Agent with real contact details (SEC blocks requests without one), Python 3.11+ or Docker, and — for anything beyond EDGAR and Treasury data — your own vendor keys.

1. Configure. Copy the template and fill in the two required values:

cp alphadesk/deploy/env.example .env

| Setting