Documentation

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

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

sudo will prompt for a password. That's your computer's own login password, not a Troxy password, and nothing will show on screen as you type it - that's normal, just type it and press Enter.

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. "Support Agent", "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 action matching your conditions will be blocked automatically.

How it Works

Troxy sits between your AI agent and every action it attempts. Before the agent acts, it calls the matching Troxy checkpoint. 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": "Support Agent"
}

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, secrets), 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, handling secrets, 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.

Terminal interception (--proxy)

If init detects Claude Code's terminal CLI, it asks whether to turn on terminal interception - a local background service that watches Claude Code's own traffic to Anthropic and applies your policies and model routing there too, not just to MCP tool calls. Answer the prompt, or skip it non-interactively:

troxy init --key txy-your-key-here --proxy      # turn it on, no prompt
troxy init --key txy-your-key-here --no-proxy   # leave terminal traffic alone

You can change this later without re-running init:

troxy proxy status
troxy proxy enable
troxy proxy disable

Repo instructions (--concise)

Init can also write a short Troxy section into your project's AGENTS.md (or a global one) so any agent working in the repo knows to check in. Choose project-scoped or global, or skip it:

troxy init --key txy-your-key-here --concise           # global (recommended default)
troxy init --key txy-your-key-here --concise project   # this repo only
troxy init --key txy-your-key-here --no-concise         # skip

Change it later the same way as proxy:

troxy concise status
troxy concise enable [--project]
troxy concise disable [--project]

troxy proxy

Turns Claude Code terminal interception on or off without re-running init.

troxy proxy status
troxy proxy enable
troxy proxy disable

When enabled, a local background service watches Claude Code's terminal traffic to Anthropic and applies your routing/policy checks to it, the same way the MCP tools do for tool calls. It only affects the terminal CLI, never Claude Desktop.

troxy concise

Turns the Troxy section in AGENTS.md on or off without re-running init.

troxy concise status
troxy concise enable            # writes to the global AGENTS.md
troxy concise enable --project  # writes to this repo's AGENTS.md instead
troxy concise disable [--project]

troxy tools

Re-scans this machine for AI coding tools (Claude Code, Cursor, GitHub Copilot, Windsurf, Continue, Aider) and reports which ones it found to the dashboard's "My AI tools" view. Run this any time you install or remove one.

troxy tools

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 and revokes the API key server-side.

troxy uninstall

This command does the following:

1. Calls POST /mcp/self-revoke to revoke the API key on the server
2. Stops and removes the background MCP service
3. Removes the troxy-mcp entry from all detected client configs (Claude Desktop, Cursor, Windsurf)
4. 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 create a new API key in the dashboard and run troxy init --key txy-your-key. 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

Policies cover six checkpoints, not just payments. create/set-priority/pause/resume/delete are admin-only and always org-wide now - personal-scope and per-MCP policies no longer exist. list/describe/test need no --org and show every policy that applies to you.

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

The six checkpoints (--domain)

See exactly which fields and operators each one supports - the same table the server validates against:

troxy policies fields --domain payment    # or any of the six, or omit --domain to see all

Fastest: start from a template

~55 built-in templates mirror the dashboard's own template library:

troxy policies templates
troxy policies templates --category "Secrets"
troxy policies create --name "Block a secret going public" --template "Block a secret going somewhere public" --org

Manual conditions

troxy policies create --name "Cap over 100" --action BLOCK --domain payment --field amount --operator gt --value 100 --org

Add more conditions with repeatable --and / --or (field=X,operator=Y,value=Z):

troxy policies create --name "Big exports" --action BLOCK --domain destructive   --field action_verb --operator eq --value export   --and "field=resource,operator=contains,value=customer" --org

Or go straight to raw JSON for scripting ({"conditions": [...], "or_conditions": [...]}, exactly what the API expects):

troxy policies create --name "Scripted policy" --action BLOCK --json '{"conditions":[{"field":"amount","operator":"gt","value":100}]}' --org

troxy policies create --name "Block large Amazon orders" --action BLOCK --describe "block Amazon purchases over $200" --org

Try before you save

Dry-run a condition against a sample event - nothing is written, no audit row, no approval:

troxy policies test --domain payment --field amount --operator gt --value 100 --example '{"amount": 150}'

Pause, resume, reprioritize, delete

All four require --org:

troxy policies set-priority --name "Block large" --priority 10 --org
troxy policies resume --name "Block large" --org
troxy policies pause --name "Block large" --org
troxy policies delete --name "Block large" --org

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 evaluations on this machine's MCP. When paused, all 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 activity 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. Stored credentials for browser-based agents 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 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 an activity 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 actions, blocked count, decision breakdown (ALLOW / BLOCK / ESCALATE / NOTIFY), and top agents.

troxy usage-bar

Shows what Troxy's model routing and context trimming actually did for your Claude Code usage bar over a given period. Requires a login session.

troxy usage-bar              # last 30 days
troxy usage-bar --period 7   # last 7 days

Reports real counts - requests seen, how many got swapped to a cheaper model, how many had context trimmed - not an estimated percentage. How much longer this actually makes your bar last depends on your own mix of requests, so we report what happened and let you judge the effect, rather than quote one shared number at everyone.

troxy pay, simulate an evaluation

Sends an 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 action limit"

troxy send, simulate a message

Same idea as troxy pay, for the comms domain. Sends an /evaluate/email request - testing a message/email policy before an agent hits it for real.

troxy send --recipient "someone@external.com" --subject "Q3 numbers" --body "See attached" --channel email

troxy signin, simulate a login

access domain - sends /evaluate/login. Tests a login/signup policy.

troxy signin --site "some-saas.com" --type login
troxy signin --site "some-saas.com" --type signup

troxy action, simulate a destructive action

destructive domain - sends /evaluate/action. Tests a policy on deletes, exports, permission changes, and similar consequential actions.

troxy action --verb delete --resource "customer_records" --items 500 --reversible false

troxy model-call, simulate an AI/model checkpoint

model domain - sends /evaluate/model. Tests a policy on the agent's own model choice, token volume, or cost.

troxy model-call --model "claude-opus-5-5" --provider anthropic --cost 2.50 --tokens 50000 --effort high

troxy scan, simulate a secrets checkpoint

secrets domain - sends /evaluate/secrets. Tests a policy on content about to leave the agent (API keys, credentials, PII, etc.) before it's sent somewhere.

troxy scan --content "sk-live-abc123..." --destination public --do send --type message

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 actions over a limit

Block any action at or above $1,000:

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

Example: Block a specific target

Block actions targeting a specific merchant domain:

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

Example: Cap daily action volume

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

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

Example: Get notified on large actions

Allow but notify you for any action over $200:

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

Example: Require approval for large actions

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

troxy policies create   --name "Escalate large actions"   --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": "Support Agent"          // 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:

Uninstalling / disconnecting (POST /mcp/self-revoke)

If the user asks you to uninstall, disconnect, or remove Troxy, deleting your local config, rules file, or stored API key is not enough - the key stays live on the server and your agent keeps showing up in the dashboard until it's revoked. Call this endpoint as your last step, using the same API key you authenticate with everywhere else, before you delete it locally:

curl -X POST https://api.troxy.io/mcp/self-revoke   -H "Authorization: Bearer txy-..."

A key can only revoke itself this way, it can't list or touch any other token, so no login/JWT is needed. After this call succeeds, go ahead and remove your local API key, rules file, and any other Troxy config.

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

Decisions 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