Qub Private Alpha

Give AI agents a controlled Qub card from your terminal.

Qub is a hosted terminal money workspace. You sign in, see your money, create Qub cards for AI agents, set limits, and approve anything that needs a human decision.

The terminal is the product. The browser is only used for login.

Quick Start

Requires Node 20+.

npx -y qub-private-alpha install    # one-time: shims `qub` onto your PATH
qub init                             # first-run: browser login + 7-question setup
qub whoami                           # confirms profile + session
qub balance                          # view money
qub agents                           # six agents pre-provisioned
qub card create ledger               # give an agent a controlled card
qub approvals                        # review what's waiting on you
qub chat "how am i doing this week?"
qub logout                           # disconnect

qub init is the canonical starter. It runs the boot animation, opens your browser for login (if you're not already signed in), walks you through a 7-question wizard (currency, risk profile, etc.), and activates your agents — all in one visible flow. Already logged in? qub init skips the login step and just runs the wizard.

If you prefer not to install:

npx qub-private-alpha login
npx qub-private-alpha balance

The install command writes a qub shim to ~/.local/bin/qub and appends

export PATH="$HOME/.local/bin:$PATH" to your shell config (~/.zshrc on zsh, ~/.bashrc on bash). Future terminals pick qub up automatically.

To use it right now in the same shell (without restarting), pick one:

# A. reload your shell config in this terminal
source ~/.zshrc && qub login

# B. invoke the shim by absolute path (no shell reload needed)
~/.local/bin/qub login

Then any later command works as qub ...:

qub login
qub card create ledger
qub chat ledger "what can you safely handle this week?"

-y only skips npm's install confirmation prompt. Users who don't want to install can run npx qub-private-alpha ... directly for every command.

What Qub Does

• Runs as a local terminal app.
• Connects to Qub's hosted backend after qub login.
• Shows balances, spending, activity, and approval requests.
• Lets you create agent cards with spending rules.
• Gives each agent a clear scope, cap, and approval policy.
• Routes out-of-policy actions to qub approvals.
• Keeps AI and database secrets on the hosted backend, not on user laptops.

Agent Cards

An agent card is a controlled spending surface for an AI agent. You decide what the agent can do before it can act.

qub card create ledger
qub card show ledger
qub chat ledger "review this card policy"
qub card pause ledger
qub approvals

Card policy supports:

• Monthly caps
• Weekly limits
• Per-transaction caps
• Auto-approve thresholds
• Merchant or category rules
• Working-hour windows
• Approval required outside policy

Private alpha note: this package exposes the terminal card-control experience. Real payment and card-network capabilities depend on the hosted Qub account configuration enabled for your beta.

Common Commands

| Command | What it does | |---|---| | qub login | Connect this terminal to your Qub account. | | qub logout | Disconnect this terminal. Revokes the server-side session. | | qub whoami | Show the active Qub identity and session. | | qub use <id> | Persist the active profile (no QUB_PROFILE_ID= prefix needed). | | qub balance | Show account balances and net worth. | | qub spend | Show category spend and caps. | | qub agents | List available AI money agents. | | qub card create ledger | Create a controlled card for the Ledger agent. | | qub card list | Show cards and status. | | qub approvals | Review pending agent or money actions. | | qub chat "how am i doing?" | Ask Qub AI about your money. | | qub chat ledger "weekly review" | Talk to a specific agent. | | qub api keys create my-bot | Mint an API key for programmatic access. | | qub mcp install claude | Add Qub to Claude Desktop / Cursor / Windsurf. | | qub update | Check for a newer Qub release. | | qub doctor | Check login, backend, and terminal status. |

Use Qub from your own AI projects

Qub ships a small TypeScript SDK as a named export of qub-private-alpha:

npm i qub-private-alpha

import { QubClient } from "qub-private-alpha";

const qub = new QubClient({ apiKey: process.env.QUB_API_KEY });
const balance = await qub.balance();
const approvals = await qub.approvals();

Mint a key from the CLI:

qub api keys create my-bot                # read-only by default
qub api keys create writer --scope=read,write
qub api keys list
qub api keys revoke <id>

Keys are long-lived and revocable. They're shown only once at creation — store them somewhere safe (1Password, a .env, your provider's secret manager).

Use Qub from Claude Desktop / Cursor / Windsurf

Any MCP-aware AI client can talk to Qub via the bundled MCP server:

qub mcp install claude       # one-shot config writer; rotates the key on re-run
qub mcp install cursor
qub mcp install windsurf
qub mcp list                  # show which clients are configured

After install, restart the AI client and ask "what's my Qub balance?" — it reads from your real Qub data over the hosted API.

Tools exposed by the MCP server:

• read tools (always on): qub_balance, qub_spend, qub_approvals, qub_cards, qub_whoami, qub_chat
• write tools (gated behind --allow-write, propose-only): qub_propose_send, qub_approve, qub_reject — these never move money on their own; they hand the AI a structured intent for the human to confirm in the Qub CLI or app.

To run the server directly (e.g. for a custom MCP client):

QUB_API_KEY=qub_api_xxx qub mcp serve
QUB_API_KEY=qub_api_xxx qub mcp serve --allow-write

You can also run the REPL:

qub

Inside the REPL, type help, chat ledger, approvals, or exit.

No API Keys Required

Normal Qub users do not configure OpenAI, Anthropic, Neon, or Vercel keys. You also do not need to set DATABASE_URL — that variable is only used by maintainers running the CLI against a local Neon database directly.

After login, Qub talks to the hosted backend at:

https://terminal-chi-dun.vercel.app

The CLI stores only a local session token under ~/.qub/. AI calls, database access, and server-side secrets stay on Qub's backend.

If you run a Qub command before qub login, the CLI prints a friendly hint pointing you to the login flow rather than crashing with a setup error.

Real profile vs demo profile

When you qub login for the first time, your Neon profile starts empty: six agents are created (Scout / Tally / Vault / Pace / Ledger / Sentinel) with zero budgets, six category caps with zero limits, and three policy tiers with sensible defaults. There are no accounts, contacts, transactions, approvals, cards, or scheduled tasks attributed to you. Every read command returns a clean empty-state hint until you've populated your data.

To explore the product with realistic data, switch to the seeded demo profile:

QUB_PROFILE_ID=demo qub balance
QUB_PROFILE_ID=demo qub agents
QUB_PROFILE_ID=demo qub shield-demo

The demo profile contains five accounts, twenty transactions, three approvals, and the full agent activity timeline — useful for screenshots, onboarding videos, and trying out flows without setting up real data.

Local Files

Qub keeps local terminal state in ~/.qub/:

~/.qub/
├── config.toml
├── session.json
├── cards.json
└── history

To remove Qub's local files and the installed qub shim:

qub uninstall

For Maintainers

This section is only for people running or developing the Qub backend.

npm install
npm install --prefix apps/web
npm run build
npm test
npm run typecheck --prefix apps/web

Local backend development:

npm run dev --prefix apps/web
QUB_API_URL=http://localhost:3000 qub login

The hosted backend lives in apps/web. Deploy that directory as the Vercel project root. Apply the Neon migrations after Neon Auth is enabled:

• migrations/001_qub_neon.sql — core schema + demo seed.
• migrations/002_qub_cli_sessions.sql — hosted CLI session tables.
• migrations/003_qub_more_state.sql — policy tiers, scheduled tasks, Atlas plans, Qub cards; agent extension columns; non-negative balance check.
• migrations/004_qub_api_keys.sql — long-lived api keys for programmatic access (SDK + MCP).

Production environment variables are set on Vercel, not committed to the repo:

| Var | Effect | |---|---| | DATABASE_URL | Neon Postgres connection string. | | NEON_AUTH_BASE_URL | Neon Auth base URL. | | NEON_AUTH_COOKIE_SECRET | Cookie signing secret. | | QUB_CLI_TOKEN_SECRET | HMAC secret for terminal session tokens. | | QUB_PUBLIC_APP_URL | Public Vercel URL for login links. | | OPENAI_API_KEY | Enables hosted Qub AI. | | ANTHROPIC_API_KEY | Optional future provider key for hosted agent routing. | | QUB_AI_MODEL | Optional hosted model override. |

Local-only development can also use OPENAI_API_KEY or ANTHROPIC_API_KEY, but users of the hosted CLI should not set those keys.

Project Docs

• User guide — quickstart, CLI reference, SDK, MCP, deployment
• Terminal design notes
• Roadmap and task list
• Product memory

License

Internal private alpha.