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.

Which agents can I use Troxy with?

Any AI agent can use Troxy, through one of two integration paths depending on where it runs:

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-cli 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 agent, that's it. The API key it saves is used only to reach the checkpoints (payments, email, login, destructive actions), fetch the agent's own setup instructions, 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 agent. Validates the key, names the agent in your dashboard, and connects it to every Troxy checkpoint.

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.

Naming the agent

By default init asks for a name interactively, defaulting to the machine's hostname. Pass --name to skip the prompt. The name is what appears in your dashboard sidebar and on every decision the agent makes, so give each agent its own.

troxy init --key txy-your-key-here --name "Lyra SuperAgent"

What gets connected

Init adapts to where it is run.

On a machine with an MCP client (Claude Desktop, Cursor, Windsurf, Zed, Continue, OpenClaw) it patches that client's config and installs the background service. Restart the client and the Troxy tools appear in its tool list.

On a hosted agent (Base44, or anything running on someone else's servers) there is no MCP client to patch and nothing to install. Init prints the checkpoint instructions instead, with your key already filled in, and writes them to AGENTS.md in the working directory. An agent that runs the command reads the output, and from that point knows to check with Troxy before it acts.

Either way the result is the same: the agent checks with Troxy before paying, sending email, logging in or signing up, and before anything destructive.

The instruction text is fetched from Troxy at run time, not baked into the CLI, so re-running init always gives the current set of checkpoints without upgrading the package.

troxy update

Updates the Troxy CLI to the latest version from npm, and refreshes a hosted agent's checkpoint instructions.

troxy update

On a hosted agent the instructions are refreshed even when the package is already current, because they are served by Troxy rather than shipped in the package. Run it after we announce a new checkpoint and the agent picks it up, no reinstall involved. On a machine with an MCP client this does nothing extra: that client already gets a fresh tool list every session.

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'

AI builder (login required): describe the policy in plain English and Troxy AI drafts it for you to confirm before it's created. Rate-limited per day, same limit as the dashboard's builder.

troxy policies create --describe "block Amazon purchases over $200"

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 "Multi-agent cap" --action BLOCK --mcp "My Laptop,Server" --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"

By default, a policy applies to every agent (all MCPs plus Troxy Chat). Use --mcp, --chat, and --no-chat to narrow that down. It's the same scoping available from the dashboard's Policies page under "Applies to."

troxy mcps

Manage MCP connections on your account, not just this machine. 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 (or any MCP with --mcp):

troxy mcps rename --name "my-agent"
troxy mcps rename --mcp "old-name" --name "Staging Server"

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

To connect another agent or machine, create a key for it without touching this machine's config:

troxy mcps create --name "Staging Server"

The key is shown once, save it, then run troxy init --key <key> on that machine. To permanently disconnect an MCP:

troxy mcps revoke --mcp "Staging Server"

To pause, resume, or set a monthly budget for any MCP (not just this machine, use troxy pause/troxy resume for that):

troxy mcps pause  --mcp "Staging Server"
troxy mcps resume --mcp "Staging Server"
troxy mcps budget --mcp "Staging Server" --currency USD --limit 500
troxy mcps budget --mcp "Staging Server" --action escalate
troxy mcps set-default-action --mcp "Staging Server" --action BLOCK

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. To pause/resume a different MCP, use troxy mcps pause/resume --mcp.

troxy approvals

Resolve pending ESCALATE holds from the terminal instead of the dashboard or email link. Requires a login session.

troxy approvals list
troxy approvals approve --id a1b2c3d4
troxy approvals decline --id a1b2c3d4

Use the short ID shown by troxy approvals list, any unambiguous prefix works.

troxy settings

Account-wide preferences: default action, approval timeout, and notification emails. Requires a login session.

troxy settings show
troxy settings set --default-action BLOCK
troxy settings set --approval-timeout 4
troxy settings set --notify-email me@example.com --notify-on-block --no-notify-on-allow

troxy chat-budget

Troxy Chat's monthly spend limit, separate from any MCP budget. Requires a login session.

troxy chat-budget show
troxy chat-budget set --currency USD --limit 500
troxy chat-budget set --action notify
troxy chat-budget set --currency EUR --clear

troxy secrets

Manage the LLM provider keys Troxy Chat uses. Values are entered at a masked prompt, never as a command-line flag, so they never land in your shell history. Requires a login session.

troxy secrets list
troxy secrets set --name "OpenAI"
troxy secrets delete --name "OpenAI"

Only api_key and text secrets are managed here. Saved payment cards for the browser purchasing agent are dashboard-only.

troxy account

Requires a login session.

troxy account clear-data   # wipe activity, policies, and pending approvals, keeps account + API keys
troxy account delete       # permanently delete your account, cannot be undone

troxy account delete asks you to type your account email to confirm before doing anything irreversible.

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
troxy pay --merchant "Delta"  --amount 250 --category travel

The output shows the decision and which policy triggered it:

  ✓ ALLOW  ←  "Always Allow"
  ⏳ ESCALATE  ←  "Amazon spending limit"

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 a specific merchant

Block payments to a specific merchant:

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

Example: Cap daily transaction volume

Block an agent once it's made more than 20 payments in a day, regardless of amount:

troxy policies create   --name "Cap daily volume"   --action BLOCK   --field tx_per_day   --operator gt   --value 20

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 large payments

Hold any payment of $2,000 or more until you approve it in the dashboard:

troxy policies create   --name "Escalate large payments"   --action ESCALATE   --field amount   --operator gte   --value 2000

Example: Different policies per agent

Policies are one global, ordered list, scope any policy to specific agents with --mcp and --chat instead of a condition field:

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

This policy only fires for the MCP named "Research Bot" (from troxy mcps list), every other agent is unaffected. Leave --mcp/--chat off and a policy applies to every agent, including Troxy Chat, by default. You can do the same from the dashboard's Policies page under "Applies to."

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: merchant_name, amount.

{
  "merchant_name": "Amazon",
  "amount": 49.99,
  "merchant_category": "software", // optional, shown in your activity log
  "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

Connecting a cloud agent directly

If your agent runs on a platform that can't run troxy-cli locally, for example a cloud-hosted agent builder, call the Troxy API directly over HTTPS instead of using MCP. This is the same evaluation Troxy's own MCP server performs, just over plain REST.

Generate a dedicated API key in the dashboard under API Keys for each integration, so you can identify and revoke it independently of your other agents. Send it as a bearer token on every request:

Authorization: Bearer txy-...

POST /evaluate

Call this before initiating any payment. Required fields: merchant_name, amount.

curl -X POST https://api.troxy.io/evaluate   -H "Authorization: Bearer txy-..."   -H "Content-Type: application/json"   -d '{
    "merchant_name": "Amazon",
    "amount": 49.99,
    "merchant_category": "software",
    "currency": "USD",
    "agent": "My Agent"
  }'

Response:

{
  "decision": "ALLOW",
  "audit_id": "a1b2c3d4-...",
  "policy": "Always Allow"
}

POST /evaluate/email

Call this before sending any email on the user's behalf. Required field: recipient. Include body with the full plaintext of the email — Troxy policies scan it for secrets and confidential content, and can't do so if it's omitted, summarized, or truncated. When the email goes to more than one person, pass every To/Cc/Bcc address in recipients so mass-email policies can apply; omit it for a one-to-one email and Troxy counts a single recipient.

curl -X POST https://api.troxy.io/evaluate/email   -H "Authorization: Bearer txy-..."   -H "Content-Type: application/json"   -d '{
    "recipient": "someone@example.com",
    "recipients": ["someone@example.com", "cc@example.com"],
    "subject": "Re: invoice",
    "body": "Full plaintext of the email...",
    "agent": "My Agent"
  }'

Response shape and decisions are the same as POST /evaluate above. There is no confirm step, since sending an email has no separate "did it succeed" callback — the decision is final.

POST /evaluate/login

Call this before logging into or signing up for any website on the user's behalf. Required fields: site (the domain) and login_action ("login" or "signup").

curl -X POST https://api.troxy.io/evaluate/login   -H "Authorization: Bearer txy-..."   -H "Content-Type: application/json"   -d '{
    "site": "example.com",
    "login_action": "login",
    "agent": "My Agent"
  }'

Response shape and decisions are the same as POST /evaluate above. Like email, there's no confirm step.

POST /payments/:id/confirm

Call this after attempting the charge, using the audit_id from the evaluate response. ALLOW and NOTIFY decisions stay PENDING until confirmed, so budgets and the dashboard reflect what actually happened.

curl -X POST https://api.troxy.io/payments/a1b2c3d4-.../confirm   -H "Authorization: Bearer txy-..."   -H "Content-Type: application/json"   -d '{ "status": "success", "provider": "my-agent" }'

status is one of success, failed, or cancelled.

POST /evaluate/action

Call this before any destructive or hard-to-undo action: deleting files or records, dropping or truncating a table, force-pushing or deleting a branch, destroying infrastructure, revoking access, overwriting data. Required field: action_verb.

curl -X POST https://api.troxy.io/evaluate/action   -H "Authorization: Bearer txy-..."   -H "Content-Type: application/json"   -d '{
    "action_verb": "delete",
    "resource": "/var/data/exports",
    "item_count": 4000,
    "reversible": false,
    "agent": "My Agent"
  }'

Response shape and decisions are the same as POST /evaluate above, and there is no confirm step.

Waiting for an approval (ESCALATE)

An ESCALATE response includes an approval_token and a next_step field spelling out this whole flow in plain language, so you never need to consult these docs at runtime. Do not stop and ask the user to tell you when they have approved — poll this endpoint instead. It long-polls, blocking for up to ~20 seconds per request and returning the moment the owner approves or declines, so a loop over it costs almost nothing.

{
  "decision": "ESCALATE",
  "approval_token": "kR9x...",
  "reason": "Matched policy 'Escalate over $200'.",
  "next_step": "Do not proceed yet. ... Poll GET https://api.troxy.io/approvals/kR9x.../wait ..."
}

This endpoint needs no API key — the approval_token is the credential, and it can only read the status, never approve on its own:

curl https://api.troxy.io/approvals/kR9x.../wait

It returns {"resolution": "APPROVED"}, {"resolution": "DECLINED"}, or a still-pending response. Keep polling while pending, up to your own timeout; a hold also expires on its own (1 hour by default).

Once approved, call the same evaluate endpoint again with identical details plus the approval_token. That second call returns ALLOW without re-escalating, and the token is single-use:

curl -X POST https://api.troxy.io/evaluate/email   -H "Authorization: Bearer txy-..."   -H "Content-Type: application/json"   -d '{
    "recipient": "someone@example.com",
    "subject": "Re: invoice",
    "body": "Full plaintext of the email...",
    "approval_token": "kR9x..."
  }'

The same flow applies to /evaluate, /evaluate/email, /evaluate/login, and /evaluate/action. If the token is missing, already used, declined, or expired, the call returns a 400 explaining which.

Agent status endpoints

Read-only endpoints for showing the user their Troxy state, all authenticated the same way:

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