ALPHA Agent

Design · Develop · Elevate
Terminal-native agent for business, coding, and automation — from Project Alpha Tech

Quick start · The promise · Gateway · MCP · Routing · Plans · Install

---

The promise

ALPHA is not a chatbot wrapper. It is one local-first agent with three product surfaces that share the same models, memory boundaries, and quota-aware routing:

Surface	What you run	What you get
ALPHA CLI	Alpha	Interactive terminal agent — chat, coding, skills, sessions
ALPHA Gateway	Alpha gateway	OpenAI-compatible API on http://127.0.0.1:24711/v1
ALPHA MCP	Alpha mcp	Stdio tools for Cursor and other MCP clients

Rate-limited? ALPHA cascades to the next healthy model — no manual re-pick. You approve every write. Secrets stay in the environment.

---

Why teams pick ALPHA

Local-first	Ollama when data should stay on the machine
BYOK cloud	OpenRouter with your own keys
Controlled coding	Schema-validated ops, diff preview, explicit approval
Operator UX	Profiles, sessions, streaming + interrupt, /setup, skills
Smart routing	Quota / rate-limit cascade — inspect with /route
Gateway + MCP	Same stack for IDEs, SDKs, and agents

---

Quick start

git clone https://github.com/projectalphatech/ALPHA.git
cd ALPHA
.\install-alpha.ps1

Open a new terminal:

Alpha --version
Alpha

Inside ALPHA:

/setup
/help
/route

---

ALPHA Gateway

Local OpenAI-compatible HTTP API. Default bind: 127.0.0.1:24711.

Alpha gateway
# or
python -m alpha_cli gateway --port 24711

When it prints ALPHA Gateway listening…, point tools at:

http://127.0.0.1:24711/v1

Method	Path	Use
GET	/health	Liveness
GET	/v1/models	Model list
POST	/v1/chat/completions	Chat (uses route fallback)

Optional auth: set ALPHA_GATEWAY_KEY, then send Authorization: Bearer <key>.

SDK

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:24711/v1", api_key="unused")
print(
    client.chat.completions.create(
        model="auto",
        messages=[{"role": "user", "content": "Say hi in one sentence."}],
    )
    .choices[0]
    .message.content
)

PowerShell smoke test

Invoke-RestMethod http://127.0.0.1:24711/health
Invoke-RestMethod http://127.0.0.1:24711/v1/models

$body = @{
  model = "auto"
  messages = @(@{ role = "user"; content = "Say hi in one short sentence." })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:24711/v1/chat/completions `
  -ContentType "application/json" -Body $body

The gateway is an API, not a website. Opening /v1 in a browser returns JSON errors by design — use /health or /v1/models.

---

MCP

Alpha mcp
# or
python -m alpha_cli mcp

Cursor (mcp.json):

{
  "mcpServers": {
    "alpha": {
      "command": "python",
      "args": ["-m", "alpha_cli", "mcp"]
    }
  }
}

Tool	Purpose
alpha_status / alpha_doctor	Readiness
alpha_list_models / alpha_set_model	Model control
alpha_chat	Chat through ALPHA routing
alpha_memory_list / alpha_remember / alpha_forget	Memory
alpha_workspace_info	Bound workspace only

---

Smart routing

ALPHA builds an ordered cascade for chat (and coding fallback):

selected → free / alt → other free OpenRouter → local Ollama

Cooldowns live under .alpha/ so burned models are skipped for a backoff window.

ALPHA > /route

On rate limits you will see: Rate-limited → trying next model …

---

Plans

Hosted billing lives on the site. CLI model access (BYOK for third-party providers):

Tier	Models	Status
Free	Curated well-known models — local + popular free and paid names via your keys	Open with Developer Preview
Pro	Full provider catalog	Pricing
PRO+	Pro + ALPHA Model (training in progress)	Coming soon

The native ALPHA Model is reserved for PRO+.

---

Install

Requirements: Windows 10+, Python 3.11+, and either Ollama (local) or an OpenRouter API key (cloud).

Windows (recommended)

git clone https://github.com/projectalphatech/ALPHA.git
cd ALPHA
.\install-alpha.ps1

pip

git clone https://github.com/projectalphatech/ALPHA.git
cd ALPHA
py -3.11 -m pip install .
Alpha

Editable / contrib

py -3.11 -m pip install -e ".[dev]"
python -m alpha_cli

First run

copy .env.example .env
# set OPENROUTER_API_KEY=...   # optional if you use Ollama only
Alpha

---

Developer Preview

This is an alpha release for builders and early adopters. Expect provider variability and format migrations before a stable cut. Always back up any workspace before allowing the coding agent to edit it.

Ships now: interactive UI · chat + coding brains · workspace boundaries · write approval · hardware recommend · skills · profiles / sessions · /route · Gateway · MCP · Windows installers.

Not in this preview: unrestricted shell, browser automation as a product surface, hosted ALPHA Model inference, or the desktop/web app download (coming soon).

---

Commands worth knowing

Command	Purpose
/help	Command reference
/setup	Guided provider / model onboarding
/model	List, search, inspect, select models
/doctor	Provider and subsystem readiness
/route	Route cascade and cooldowns
/new /sessions /resume	Working sessions
/workspace	Bound the coding workspace
Alpha gateway	Local OpenAI-compatible HTTP API
Alpha mcp	MCP stdio server

Runtime state lives under .alpha/. Secrets never belong in git — environment only.

---

Development

py -3.11 -m pip install -e ".[dev]"
py -3.11 -m pytest tests -q

See CONTRIBUTING.md and SECURITY.md.

---

Links

• Product: alpha-agent.projectalpha.tech
• Docs: alpha-agent.projectalpha.tech/docs
• Brand: projectalpha.tech
• Support: support@projectalpha.tech

---

License

MIT — see LICENSE and THIRD_PARTY_NOTICES.md.

© Project Alpha Tech. ALPHA · Design · Develop · Elevate.