Documentation

Everything you need to connect your AI agent to Troxy and control its payments.

Quick Start

Get up and running in under 2 minutes.

Prerequisites, Node.js 18+

The Troxy CLI requires Node.js. Run node -v, if you see a version number, skip ahead to Install the CLI below.

curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs

brew install node

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

1. Install the CLI

sudo npm install -g troxy-cli

This makes the troxy command available globally. All examples below use troxy directly.

Already installed? Run troxy update to upgrade, or troxy --version to check what you have. If the update fails, see Update errors in Troubleshooting.

2. Get your API key

Log in to the Troxy dashboard, go to API Keys, and copy your API key. It starts with txy-.

3. Connect the MCP (once per machine)

troxy init --key txy-your-key-here

This will:

• Validate your API key and save it to ~/.troxy/config.json
• Ask you to name this agent (e.g. "Shopping Bot", "EC2 Agent")
• Auto-detect and patch Claude Desktop, Cursor, or Windsurf if installed
• Install a background service so the MCP server survives reboots

You'll see a green dot next to your agent's name in the dashboard within 60 seconds. You only need to run this once per machine.

4. Log in for CLI commands (12-hour session)

troxy login

This opens your browser with a Troxy login page that displays a short code. Copy the code and paste it back into the terminal. You're then authenticated for 12 hours. This is separate from the MCP key and required to run any CLI inspection or management commands (activity, mcps, policies, insights, etc.).

5. Create your first policy

Open the dashboard and go to Policies → New policy. Add a condition and choose an action. Example: set amount ≥ 500 with action BLOCK, any payment over $500 will be blocked automatically.

How it Works

Troxy sits between your AI agent and payments as an MCP tool. Before making any payment, the agent calls evaluate_payment. Troxy checks your policies in priority order and returns one of four decisions:

ALLOW, approved, agent proceeds
BLOCK, rejected, agent stops
NOTIFY, approved, but you get notified
ESCALATE, held until you manually approve it in the dashboard

The MCP server also sends a heartbeat every 60 seconds so the dashboard shows real-time connection status.

Config file

Troxy stores its local config at ~/.troxy/config.json. You can view or edit it directly:

cat ~/.troxy/config.json

A typical config looks like this:

{
  "apiKey": "txy-your-key-here",
  "agentName": "Shopping Bot"
}

Changing the agent name

Edit the config file directly, then restart the service:

nano ~/.troxy/config.json

# After saving, restart:
sudo systemctl restart troxy-mcp        # Linux
launchctl unload ~/Library/LaunchAgents/ai.troxy.mcp.plist   # macOS
launchctl load  ~/Library/LaunchAgents/ai.troxy.mcp.plist

The dashboard will show the updated name within 60 seconds.

Environment variables

Environment variables take precedence over the config file, useful for containers or CI:

TROXY_API_KEY=txy-your-key TROXY_AGENT_NAME="Prod Agent" npx troxy mcp

Re-running init

To start fresh (e.g. to swap API keys or rename the agent), uninstall first then re-run:

troxy uninstall
troxy init --key txy-your-new-key-here

Removing Troxy

There are two separate things you can do, and they're often confused, make sure you understand both:

After uninstalling, restart your AI client (Claude Desktop, Cursor, etc.) to fully stop the MCP server process.

MCP key vs login session, what requires what

troxy init connects this machine as an MCP, that's it. The API key it saves is used exclusively by the background MCP server to evaluate payments and send heartbeats. It cannot read policies, list MCPs, view activity, or do anything else.

troxy login gives you a 12-hour human session for everything else, all management and inspection commands go through this session, not the API key.

Bottom line: run troxy init once per machine to connect the MCP, then run troxy login whenever you want to manage your account from the CLI. Sessions last 12 hours.

troxy init

Run once per machine. Validates the key, asks for an agent name, patches MCP client configs, and installs the background service.

troxy init --key txy-your-key-here

After init, your key is saved to ~/.troxy/config.json, no need to pass --key to any other command.

troxy update

Updates the Troxy CLI to the latest version from npm.

troxy update

If you installed with sudo npm install -g, you'll need sudo troxy update. After updating, run troxy restart to apply the new version to the background service.

sudo troxy update
troxy restart

troxy restart

Restarts the Troxy background service. Use this after updating or after manually editing ~/.troxy/config.json.

troxy restart

troxy uninstall

Fully removes Troxy from the current machine.

troxy uninstall

This command does the following:

1. Stops and removes the background MCP service
2. Removes the troxy-mcp entry from all detected client configs (Claude Desktop, Cursor, Windsurf)
3. Deletes ~/.troxy (your local config and saved API key)

After running: restart your AI client (Claude Desktop, Cursor, etc.) so the MCP server process fully stops. Until you restart, the client may still try to connect.

Want to reinstall later? Just run troxy init --key txy-your-key again. Your policies and dashboard data are untouched.

troxy login / logout

Authenticates you as a human for 12 hours. Required for every command except troxy init and troxy status, policies, activity, MCPs, insights, pause/resume, rotate-key, all of it.

troxy login
troxy logout

After running troxy login:

1. Your browser opens to the Troxy login page
2. Log in, and the page shows you a short code
3. Copy the code and paste it back into the terminal
4. You're authenticated for 12 hours

troxy status

Shows API health and connection status. Works without login. If you're logged in, also shows your account overview (policies count, MCP connections, etc.).

troxy status

troxy policies

Read (login required):

troxy policies list
troxy policies describe --name 'Block Amazon'

Write (login required):

troxy policies create --name "Block large" --action BLOCK --field amount --operator gte --value 500
troxy policies create --name "Cap spend" --action BLOCK --mcp "My Laptop" --field amount --operator gte --value 200
troxy policies create --name "Allow Wiki" --action ALLOW --priority 5 --field merchant_name --operator contains --value Wiki
troxy policies set-priority --name "Block large" --priority 10
troxy policies resume --name "Block large"
troxy policies pause  --name "Block large"
troxy policies delete  --name "Block large"

troxy mcps

Lists all MCP connections on your account, which are connected, last seen, and their agent names. Requires a login session.

troxy mcps list

A ● means the MCP server is actively connected (heartbeat received recently). A ○ means offline or the key exists but no MCP server is running with it.

To rename the MCP on this machine:

troxy mcps rename --name "my-agent"

The new name appears in your dashboard immediately and is used for all future heartbeats.

troxy pause / resume

Pauses or resumes payment evaluations on this machine's MCP. When paused, all payment requests return BLOCK immediately. Requires a login session.

troxy pause    # block all evaluations
troxy resume   # resume normal evaluation

The paused state is visible in your dashboard (amber dot next to the MCP name). You can also pause/resume from the dashboard by hovering over an MCP and clicking the ⋯ menu.

troxy activity

Shows recent payment decisions across all your MCPs. Requires a login session.

troxy activity
troxy activity --limit 50      # show more rows (default: 20, max: 200)
troxy activity --mine          # show only decisions made by the MCP on this machine

--mine filters to decisions made by the MCP key configured on this machine via troxy init. Only works on a machine that has an MCP key configured.

troxy insights

Shows a spending and decision summary for a given period. Requires a login session.

troxy insights              # last 30 days
troxy insights --period 7   # last 7 days

Includes total requests, total spend, blocked amount, decision breakdown (ALLOW / BLOCK / ESCALATE / NOTIFY), and top merchants.

troxy pay, simulate a payment

Sends a payment evaluation request directly to Troxy, identical to what your AI agent does. Use this to test your policies. Requires a login session.

troxy pay --merchant "Amazon" --amount 50
troxy pay --merchant "Amazon" --amount 350 --card "Work"
troxy pay --merchant "Delta"  --amount 250 --card "Work" --category travel

The output shows the decision and which policy triggered it:

  ✓ ALLOW  ←  "Always Allow"
  ⏳ ESCALATE  ←  "Work card Amazon spending limits"

troxy rotate-key

Creates a new API key, saves it to ~/.troxy/config.json, and immediately revokes the old one. Requires login.

troxy rotate-key                    # rotate key (old is revoked automatically)
troxy rotate-key --name "new name"  # give the new key a custom name

After rotating, restart the MCP service to pick up the new key:

troxy restart

Example: Block payments over a limit

Block any payment at or above $1,000:

troxy policies create   --name 'Block over $1000'   --action BLOCK   --field amount   --operator gte   --value 1000

Example: Block specific merchant categories

Block payments to gambling sites:

troxy policies create   --name "Block gambling"   --action BLOCK   --field merchant_category   --operator eq   --value gambling

Block payments to a specific merchant:

troxy policies create   --name "Block Roblox"   --action BLOCK   --field merchant_name   --operator eq   --value roblox

Example: Get notified on large purchases

Allow but notify you for any transaction over $200:

troxy policies create   --name "Notify on big spend"   --action NOTIFY   --field amount   --operator gte   --value 200

Example: Require approval for international payments

Hold any non-USD payment until you approve it in the dashboard:

troxy policies create   --name "Escalate non-USD"   --action ESCALATE   --field currency   --operator neq   --value USD

Example: Different policies per agent

In the dashboard, go to Policies → New policy and add two conditions:

• agent_name equals Research Bot
• amount ≥ 50

Set the match logic to ALL (AND) and action to BLOCK. This policy only fires when that specific agent tries to spend $50 or more, all other agents are unaffected.

The agent_name value must match exactly what you set during troxy init (or what the MCP sends in the heartbeat).

Example: Tiered policies by amount

Use a single tiered policy instead of three separate ones. In the dashboard, go to Policies → New policy, set action to Tiered by amount, and define your thresholds:

• Up to $100 → ALLOW
• Up to $500 → NOTIFY
• Everything else → ESCALATE

Troxy evaluates thresholds top to bottom and fires the first match. Add as many tiers as needed and reorder freely.

Connecting via MCP

If your MCP client wasn't auto-detected during troxy init, add this manually to your client's config under mcpServers:

{
  "troxy": {
    "command": "npx",
    "args": ["troxy", "mcp"],
    "env": {
      "TROXY_API_KEY": "txy-your-key-here",
      "TROXY_AGENT_NAME": "My Agent"
    }
  }
}

Supported clients: Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Config file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

evaluate_payment tool

Your agent calls this before initiating any payment. Required fields: card_alias, merchant_name, amount.

{
  "card_alias": "Work",            // a label for which card/budget context to use
  "merchant_name": "Amazon",
  "amount": 49.99,
  "merchant_category": "software", // optional, enables category-based policies
  "currency": "USD",               // optional, defaults to USD
  "agent": "Shopping Bot"          // optional, override the agent name for this call
}

Possible responses and what the agent should do:

Auto-start on reboot

troxy init installs a background service that starts automatically at boot.

# Linux, manage the service
sudo systemctl status troxy-mcp
sudo systemctl restart troxy-mcp
sudo systemctl stop troxy-mcp

# View live logs
journalctl -u troxy-mcp -f

# macOS, manage the LaunchAgent
launchctl list | grep troxy
launchctl unload ~/Library/LaunchAgents/ai.troxy.mcp.plist
launchctl load  ~/Library/LaunchAgents/ai.troxy.mcp.plist

Troubleshooting

Dashboard shows "MCP disconnected"

The MCP service isn't running or hasn't sent a heartbeat yet (every 60 seconds).

# Check status
sudo systemctl status troxy-mcp

# Restart
sudo systemctl restart troxy-mcp

# Watch live logs, you should see "[troxy] heartbeat ok" every 60s
journalctl -u troxy-mcp -f

The dashboard dot updates within 60 seconds of the next heartbeat.

Agent name shows as "unknown" in activity

Transactions logged before you set an agent name won't have one. New ones use the name from your config. Edit ~/.troxy/config.json and restart the service.

"No MCP clients detected" during init

Troxy looks for Claude Desktop, Cursor, and Windsurf config files. If none are found, it prints the JSON snippet, paste it into your client's MCP config manually (see Connecting via MCP).

CLI shows "authentication required" or "login required"

troxy login

All CLI commands other than troxy init and troxy status require a login session. Run troxy login to start one.

API key invalid or revoked

If you see "API key invalid or revoked", your saved key is no longer accepted. Generate a new key in the dashboard under API Keys, then reconnect:

troxy init --key txy-your-new-key-here

Service fails to start (wrong binary path)

If journalctl -u troxy-mcp shows "command not found", the service was installed with an incorrect path. Fix it:

troxy uninstall
troxy init --key txy-your-key-here

npm permission error during install

If you see EACCES: permission denied when installing globally:

sudo npm install -g troxy-cli

Update errors

If troxy update fails with a permission error, run sudo troxy update. If it fails with ENOTEMPTY, remove the package manually and reinstall:

sudo rm -rf /opt/homebrew/lib/node_modules/troxy-cli && sudo npm install -g troxy-cli@latest

Check API health

troxy status