Documentation

BOSS docs

Permission-first Binance Spot copilot for Agent OS. English only.

Quick start (local)

git clone https://github.com/nrlartt/boss.git
cd boss
npm install
npm test
npm start

Desk: http://127.0.0.1:8790/app/
MCP: http://127.0.0.1:8790/mcp
Copy .env.example → .env only if you need local API keys

Hosted demo

The public Railway instance runs without Binance API keys. Anyone can observe and plan; nobody can spend your balance from the hosted URL.

Landing: site root
Live desk: /app/
Health: /api/health
Market data via Binance public vision API on cloud hosts

MCP setup

Run BOSS next to the official Binance Agent OS MCP:

{
  "mcpServers": {
    "binance": { "url": "https://agent.binance.com/mcp/agentic" },
    "boss": { "url": "http://127.0.0.1:8790/mcp" }
  }
}

On the hosted site, replace the BOSS URL with <your-origin>/mcp.

Safety model

Verdict	Meaning
BLOCK	Hard rule failed. No approval, no send.
UNKNOWN	Missing required fact (usually balances). Plan OK; send refused.
CLEAR	Gate open — still requires typing EXECUTE.

Approved orders carry an HMAC newClientOrderId stamp. FOREIGN / FORGED / MISMATCHED classifications burn trade scope until restored from the desk.

FAQ

Is the hosted URL using my balance?

No. The public demo has no API keys. Anyone can analyze and plan; nobody can spend your Binance funds from the hosted instance.

Is this live trading?

Hosted mode is live market data with observe/plan only. Real sends happen through your own Agent OS connection or a local desk with your keys — never on the public demo server.

Why UNKNOWN so often?

Missing account balances stay UNKNOWN on BALANCE_SUFFICIENT. BOSS never treats absent data as zero — attach balances and re-plan to reach CLEAR.

How is BOSS different from a size cap?

Caps check the order. BOSS checks the full permission path: policy matrix, EXECUTE token, HMAC stamp, and post-trade classification.

Can I connect Cursor to the hosted MCP?

Yes — use https://<your-railway-host>/mcp. The hosted session is shared; observe and plan only. Use a local BOSS instance for private trading workflows.