# LangAlpha: a persistent workspace agent for market research

> LangAlpha is a Python 3.13+ agent harness that keeps market research in a sandbox filesystem across sessions. It installs through Docker Compose or uv, and its value depends on whether you already have LLM and market-data access.

**ginlix-ai/LangAlpha** — Claude Code for Financial Market

- Repository: https://github.com/ginlix-ai/LangAlpha
- Website: https://langalpha.ai
- Stars: 1,792 · Forks: 294
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ginlix-ai-langalpha

## What LangAlpha solves, and for whom

Most finance chat tools treat a question as the whole interaction. LangAlpha's README frames the opposite case: research is iterative, a thesis gets revised as new data arrives, and a single prompt cannot hold weeks of that. The project calls itself a vibe investing agent harness and positions itself next to code agent harnesses. The comparison is deliberate. In a code agent, a repository persists and each change builds on the previous state. LangAlpha gives the agent a persistent workspace instead, so accumulated research compounds rather than resetting.

The intended user is someone doing recurring market work: a rebalance, a sector deep dive, an earnings cycle. The README's own example is a workspace per research goal, with the agent interviewing the user about goals and style before producing a first deliverable. That is a heavier commitment than a chat window. You are agreeing to keep files, threads and notes in one place and return to them.

It is not a retail quote screen and not a signal service. The repository ships MCP servers, skills for DCF models and initiating coverage reports, automations that fire on price conditions, and channel integrations for Slack, Discord, Feishu and Telegram. The feature list is broad, which is itself a signal: this is infrastructure for people who will configure it.

## How the agent, sandbox and checkpointer fit together

The architecture diagram in the README shows a React 19 and Vite web UI talking to a FastAPI backend over REST and SSE, with a separate WebSocket proxy for market data. A CLI and TUI client uses the same REST and SSE surface. The backend routes threads, workspaces, market data, OAuth, automations and skills, then hands work to a chat handler that resolves the LLM and dispatches a workflow into a background task manager. Execution is decoupled from the HTTP connection, so a long analysis does not die when a browser tab closes.

State lives in PostgreSQL through two pools. One holds application data: users, workspaces, threads, turns, BYOK keys, automations. The other is the LangGraph checkpointer, which stores agent state and checkpoints. Redis does three jobs: an SSE event buffer described as holding 150K events for reconnect replay, an API cache for market data with stale-while-revalidate, and steering. That buffer is why a dropped SSE connection can resume rather than lose the agent's activity stream.

The part worth understanding before adopting is Programmatic Tool Calling. Instead of pouring raw financial data from MCP servers into the model context, the agent writes and executes Python in the sandbox to process it. The README states this enables multi-step analysis while reducing token waste. The trade-off is real: the agent now needs a working Python environment with the right libraries, and failures move from prompt errors into code errors. The pyproject.toml is unusually explicit about why it requires Python 3.13 rather than 3.12. The comment says the Redis pools block on an asyncio.Condition, and before 3.13 a waiter cancelled at its own deadline swallowed a notify instead of re-delivering it, so a caller could be told the pool was exhausted while a connection sat free. The file adds that nothing in the repository can compensate for that. That is a hard floor, not a preference.

## Installing LangAlpha and running a first workspace

The docker-compose.yml header gives the shortest path. Copy the environment template, fill in API keys, and bring the stack up. The compose file starts PostgreSQL and Redis under the infra profile, and the Makefile wraps the same flow with a provider argument.

```bash
cp .env.example .env
docker compose up
```

The .env.example notes that the two required keys are the ones to set for a Docker quick start, and that everything else has defaults that work out of the box. It also states LangAlpha works with zero external keys, with Docker providing sandbox execution, Yahoo Finance MCP servers providing free data once enabled in agent_config.yaml, and LLM access coming from your own subscription via OAuth. Read that sentence carefully: zero external keys is not zero configuration. You still enable the MCP servers in agent_config.yaml.

For the full stack through the Makefile, pass the sandbox provider explicitly. The up target builds the sandbox image only when the provider is docker.

```bash
make up PROVIDER=docker
```

For backend and frontend development outside Docker, the install target syncs dependencies with uv. It checks .env for OTEL_EXPORTER_OTLP_ENDPOINT and adds the observability extra when that variable is set.

```bash
make install
```

The interactive setup wizard is the target to reach for when you would rather answer prompts than edit files. The Makefile describes it as covering LLM, data, sandbox, and web search and fetch.

```bash
make config
```

After the stack is running, the first real use is creating a workspace. The README describes the agent interviewing you about your goals and style, producing a first deliverable, and saving everything to the workspace filesystem. If you want to check the plumbing before trusting a research run, the README points at docs/api/README.md for the API surface and libs/ptc-cli/ for the TUI client.

## Where LangAlpha is the wrong tool

The infrastructure footprint is the first limit. A FastAPI backend, two PostgreSQL pools, Redis with a 150K event buffer, and a sandbox provider is a service to operate, not a library to import. The compose file sets a memory limit of 8g on the backend service and a pids limit of 8192, which tells you what the authors expect a working instance to consume. If your need is a one-off question about a ticker, this is the wrong shape entirely.

Sandbox choice is a genuine fork. With DAYTONA_API_KEY set, the sandbox provider auto-detects to daytona; when it is empty, it falls back to docker. The Docker path needs the host socket mounted, and .env.example notes that a rootless Docker context requires pointing DOCKER_HOST_SOCKET at /run/user/<uid>/docker.sock. Get that wrong and the agent has no execution environment, which breaks Programmatic Tool Calling and every skill that depends on it.

Data quality is not something the harness fixes. The README lists a multi-tier provider hierarchy with native tools for quick lookups and MCP servers for bulk work, and .env.example mentions Financial Modeling Prep as a high-quality paid source alongside the free Yahoo Finance servers. If your decisions need licensed or consolidated data, the free tier is not a substitute, and the repository does not claim otherwise.

The upgrade path carries a specific hazard. pyproject.toml pins langgraph>=1.2.2,<2 and states the floor is the beta DeltaChannel on-disk format, where message checkpoints are delta snapshot and sentinel blobs. The comment warns that langgraph below 1.2 cannot read them, and that downgrading after delta blobs exist strands threads on resume. If you already run a LangGraph checkpointer database, confirm the version before pointing LangAlpha at it.

## How LangAlpha differs from FinRobot and FinGPT

The related searches around this project include FinRobot, FinGPT and FinAgent, so the comparison is worth making concrete. The difference is not the model or the data vendor. It is what persists between runs.

FinGPT-style projects are oriented around models and datasets: fine-tuning, sentiment or forecasting tasks, and the artifacts are weights and predictions. LangAlpha does not train anything. It ships a harness, and its durable artifact is a workspace directory containing your research, plus an agent.md notes file and separate memory stores under .agents/user/memory/ and .agents/workspace/memory/. A memo store at .agents/user/memo/ accepts uploaded PDFs and markdown notes the agent reads on demand.

FinRobot-style agent frameworks are typically invoked as a script or notebook run against a task. LangAlpha's unit of work is a workspace with threads, turns and checkpoints in PostgreSQL, plus SSE streaming and reconnect replay so a run survives a dropped connection. That is a server, not a function call.

If your goal is to fine-tune a model on financial text, LangAlpha is irrelevant. If your goal is to keep a running research process with an agent that can execute Python against market data and remember what it concluded last week, the workspace model is the feature that distinguishes it. The cost is that you now own a stateful service and its database migrations.

## Upgrade cost, licence and what stays your problem

LangAlpha is Apache-2.0, declared in pyproject.toml as license text and shown as a badge in the README. That permits commercial use and modification, and it also means no warranty and no support obligation from the authors. The repository ships a LICENSE file at the top level, and that file, not this article, governs what you may do. If you plan to redistribute a modified build or embed it in a product, have your own counsel read it. Nothing here is legal advice.

The dependency set is pinned tightly enough that upgrades need attention. The langgraph range is >=1.2.2,<2, and langgraph-checkpoint-postgres is >=3.1,<4 with a comment saying the ceiling mirrors langgraph<2 because the postgres saver serializes the same delta blobs and moves in lockstep. That is a coupled pair: you cannot bump one without the other. The Python floor of 3.13 is not negotiable either, for the asyncio reason given in the file.

Operationally, the release cadence in the repository is brisk. Recent tags include v2026.09.07, desktop-v0.2.3 and a self-hosted desktop-oss-v0.2.3 variant, all dated 2026-09-07. The last push to the default branch was 2026-09-08. Frequent releases are good for fixes and bad for churn: read the release notes before upgrading a running instance, because checkpoint format changes are the kind of thing that strands threads rather than failing loudly.

The upgrade cost you should budget for is data, not code. Migrations live in the migrations directory with alembic.ini at the root, and the checkpointer shares the same database family. Back up before upgrading, and test a resume of an existing thread rather than only a fresh run.

## Conclusion

Adopt LangAlpha if you run Python 3.13, already hold LLM and market-data credentials, and want research that survives between sessions in a workspace filesystem you control. Skip it if you need a hosted product with no infrastructure, or if you only want a single question answered once. Before committing, verify the sandbox provider path (docker or Daytona), the agent_config.yaml MCP entries for your data vendors, and whether the LangGraph delta checkpoint format in your existing database can be read by the pinned langgraph>=1.2.2,<2 range.

## FAQ

### What is LangAlpha?

It is an agent harness for interpreting financial markets and supporting investment decisions, described in the README as a vibe investing agent harness. It gives the agent a persistent workspace per research goal, so files, threads and accumulated research survive between sessions.

### Do I need API keys to run LangAlpha?

The .env.example states the project works with zero external keys, with Docker providing sandbox execution, Yahoo Finance MCP servers providing free data once enabled in agent_config.yaml, and LLM access from your own subscription via OAuth. It still recommends setting the two required keys for a Docker quick start.

### Which Python version does LangAlpha require?

Python 3.13 or newer. The pyproject.toml comment explains that the Redis pools block on an asyncio.Condition, and before 3.13 a waiter cancelled at its deadline swallowed a notify instead of re-delivering it, so a caller could be told the pool was exhausted while a connection sat free.

## Sources

- [ginlix-ai/LangAlpha on GitHub](https://github.com/ginlix-ai/LangAlpha)
- [License: Apache-2.0](https://github.com/ginlix-ai/LangAlpha/blob/main/LICENSE)
- [Project website](https://langalpha.ai)
- [README](https://github.com/ginlix-ai/LangAlpha/blob/main/README.md)
- [Releases](https://github.com/ginlix-ai/LangAlpha/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ginlix-ai-langalpha