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.

1. Install the CLI

npm install -g troxy-cli

2. Get your API key

3. Initialize Troxy

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

This will:

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

That's it. Your AI agent's payments are now protected. You'll see a green dot with your agent's name in the dashboard within 60 seconds.

4. Create your first policy

npx troxy policies create --name "Block large payments" --action BLOCK --field amount --operator gte --value 500

Any payment over $500 will now 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 an email notification
ESCALATE — held until you manually approve it

The MCP server also sends a heartbeat every 60 seconds so the dashboard shows real-time connection status with your agent's name.

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 file looks like this:

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

Field	Description
apiKey	Your Troxy API key (starts with `txy-`). Set during `troxy init`.
agentName	The display name shown in your dashboard next to the connected dot. Also sent with every payment evaluation so you can write per-agent policies.

Changing the agent name

To rename an agent, edit the config file directly:

# Open the config
nano ~/.troxy/config.json

# Change "agentName" to your new name, save, then restart the service
sudo systemctl restart troxy-mcp   # Linux
# or on macOS:
launchctl unload ~/Library/LaunchAgents/ai.troxy.mcp.plist
launchctl load ~/Library/LaunchAgents/ai.troxy.mcp.plist

The dashboard will show the updated name within 60 seconds (after the next heartbeat).

Environment variables

Instead of a config file, you can pass values via environment variables. These take precedence over the config file:

Variable	Description
TROXY_API_KEY	Your API key. Overrides `apiKey` in config.
TROXY_AGENT_NAME	Agent display name. Overrides `agentName` in config.

This is useful for containerized environments or when you don't want to write a config file:

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

Re-running init

To start fresh on a machine (e.g. to change the API key or agent name), uninstall the service first then re-run init:

# Linux — stop and disable the existing service
sudo systemctl stop troxy-mcp
sudo systemctl disable troxy-mcp
sudo rm /etc/systemd/system/troxy-mcp.service
sudo systemctl daemon-reload

# macOS — unload the LaunchAgent
launchctl unload ~/Library/LaunchAgents/ai.troxy.mcp.plist
rm ~/Library/LaunchAgents/ai.troxy.mcp.plist

# Then remove the config and re-run init
rm ~/.troxy/config.json
npx troxy init --key txy-your-new-key-here

troxy init

Sets up Troxy on a new machine. Run this once per agent. It validates the key, asks for an agent name, patches MCP client configs, and installs the background service.

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

Log in with your dashboard credentials to use management commands (cards, policies, activity). The API key alone is not enough for these.

npx troxy login
npx troxy logout

troxy cards

npx troxy cards list
npx troxy cards create --name "Personal" --budget 500
npx troxy cards delete --name "Personal"

--name — card alias used in evaluate_payment calls
--budget — monthly spend limit in USD (optional)

troxy policies

npx troxy policies list
npx troxy policies create --name "Block large" --action BLOCK --field amount --operator gte --value 500
npx troxy policies enable  --name "Block large"
npx troxy policies disable --name "Block large"
npx troxy policies delete  --name "Block large"

Option	Values
--action	`ALLOW`, `BLOCK`, `NOTIFY`, `ESCALATE`
--field	`amount`, `merchant_name`, `merchant_category`, `merchant_country`, `currency`, `agent_name`, `hour`, `day_of_week`
--operator	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `between`
--value	The comparison value (e.g. `500`, `"amazon"`, `Monday`)
--value2	Upper bound for `between` operator

troxy activity

npx troxy activity
npx troxy activity --limit 50

Shows recent payment decisions — agent name, merchant, amount, decision, and which policy matched.

troxy status

npx troxy status

Checks that the Troxy API is reachable and your key is valid.

Example: Block payments over a limit

Block any payment at or above $1,000:

npx 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:

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

Block payments to a specific merchant:

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

Example: Get notified on large purchases

Allow but send you an email for any transaction over $200:

npx 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:

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

Example: Different rules per agent

Give one agent a tighter limit than others. First, create a restrictive policy for a specific agent:

npx troxy policies create   --name "Research agent cap"   --action BLOCK   --field amount   --operator gte   --value 50

Then scope it to only that agent using a second condition in the dashboard (multi-condition support). The agent_name field matches the name you set during troxy init — for example "Research Bot".

Tip: Policy priority matters. Policies are evaluated top-to-bottom — the first one that matches wins. Use the dashboard to drag and reorder them.

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": "Personal",        // card alias created in dashboard
  "merchant_name": "Amazon",
  "amount": 49.99,
  "merchant_category": "software", // optional — helps category-based policies
  "currency": "USD",               // optional, defaults to USD
  "agent": "Shopping Bot"          // optional — override agent name for this call
}

Possible responses and what the agent should do:

Decision	Agent behavior
ALLOW	Proceed with payment
BLOCK	Do not proceed — inform user payment was blocked
NOTIFY	Proceed with payment (notification sent to owner)
ESCALATE	Do not proceed — wait for human approval before retrying

Auto-start on reboot

troxy init installs a background service that starts automatically when the machine boots.

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

# View 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

Note: On Linux servers (EC2, VPS, etc.), the service is installed as a systemd unit and enabled at boot. On macOS, it's installed as a LaunchAgent and starts on login.

Troubleshooting

Dashboard shows "MCP disconnected"

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

# Check status
sudo systemctl status troxy-mcp

# Restart
sudo systemctl restart troxy-mcp

# Watch live logs to confirm heartbeats
journalctl -u troxy-mcp -f

You should see [troxy] heartbeat ok in the logs. The dashboard dot updates within 60 seconds.

Agent name shows as "unknown" in activity

Transactions logged before you set an agent name won't have one. New transactions will use the name from your config. To update it: 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"

npx troxy login

Cards, policies, and activity commands require a dashboard session (email + password), not just the API key.

Service fails to start (wrong binary path)

If journalctl -u troxy-mcp shows a "command not found" error, the service may have been installed with an incorrect path. Uninstall and reinstall:

sudo systemctl stop troxy-mcp
sudo systemctl disable troxy-mcp
sudo rm /etc/systemd/system/troxy-mcp.service
sudo systemctl daemon-reload
npx troxy init --key txy-your-key-here

npm permission error during install

sudo npm install -g troxy-cli

Check API health

npx troxy status

Documentation

Quick Start

1. Install the CLI

2. Get your API key

3. Initialize Troxy

4. Create your first policy

How it Works

Config file

Changing the agent name

Environment variables

Re-running init

troxy init

troxy login / logout

troxy cards

troxy policies

troxy activity

troxy status

Example: Block payments over a limit

Example: Block specific merchant categories

Example: Get notified on large purchases

Example: Require approval for international payments

Example: Different rules per agent

Connecting via MCP

evaluate_payment tool

Auto-start on reboot

Troubleshooting

Dashboard shows "MCP disconnected"

Agent name shows as "unknown" in activity

"No MCP clients detected" during init

CLI shows "authentication required"

Service fails to start (wrong binary path)

npm permission error during install

Check API health