For agent builders
Let your agent pay. Keep the limits yours.
Ghostline runs as a local MCP server next to your agent. The agent asks to pay; the policy engine, which the agent can’t edit, decides.
- 01
Install Ghostline
Mainnet needs 0.5.0 or later: install the latest release, or build ghostline, ghostline-mcp and ghostline-paid-api from source.
Guide - 02
Run your wallet with cookie login
tari_ootle_walletd 0.53.3 on 127.0.0.1 with --cookie-auth true. Never --authentication none.
Guide - 03
Create the channel record
ghostline channel init with the service's terms and a Ghostline claim key, so no wallet view key is exported.
Guide - 04
Connect the MCP server
Add the config below to your MCP host. Secrets stay in the environment, never in tool arguments.
Guide - 05
Open, then let the agent pay
ghostline_open_channel quotes first; it broadcasts only after you set GHOSTLINE_OPEN_SUBMIT=1.
Guide
MCP config
One block of config.
Claude Desktop reads it from claude_desktop_config.json; Claude Code reads the same shape from a project’s .mcp.json. Any MCP host that runs stdio servers works.
{
"mcpServers": {
"ghostline": {
"command": "ghostline-mcp",
"env": {
"GHOSTLINE_CHANNEL_FILE": "/home/you/ghostline/channel.json",
"GHOSTLINE_WALLET_COOKIE": "/home/you/wallet/.cookie",
"GHOSTLINE_POLICY_BUDGET": "5000",
"GHOSTLINE_POLICY_MAX_PER_CALL": "1000",
"GHOSTLINE_POLICY_VENDOR_HEX": "<service public key>",
"GHOSTLINE_POLICY_AUDIT_LOG": "/home/you/ghostline/audit.jsonl",
"GHOSTLINE_OPEN_MAX_FEE": "20000"
}
}
}
}Spending policy
The leash, line by line.
Each payment goes through policy before signing. When configured, the audit log records decisions and refusals. On mainnet, the sixth call of run 5 was refused with cumulative 6000 exceeds policy budget 5000.
- GHOSTLINE_POLICY_BUDGET5000
- Maximum cumulative spend for the channel in µT. An amount equal to the budget is allowed.
- GHOSTLINE_POLICY_MAX_PER_CALL1000
- Maximum price of one call in µT. Set this with the budget.
- GHOSTLINE_POLICY_VENDOR_HEX<service key>
- Service authorization public key in hex. The signing path uses it as the allowed vendor.
- GHOSTLINE_POLICY_HUMAN_THRESHOLD1000
- Ask for consent on calls at or above this positive price in µT.
- GHOSTLINE_POLICY_APPROVE_NEW_VENDOR1
- Ask on the first payment to a vendor.
- GHOSTLINE_POLICY_REQUIRE_HUMAN1
- Ask on every payment.
- GHOSTLINE_POLICY_AUDIT_LOG<run>/policy-audit.jsonl
- Optional private JSONL file for decisions. A failed audit write prevents signing.
What the agent gets
Thirteen tools. No secrets as arguments.
Pay
ghostline_call_paid
GET a paid HTTP resource. On 402, if GHOSTLINE_SESSION is set, signs a voucher from the session and retries once.
ghostline_sign_voucher
Sign the next Ghostline voucher for `price`. Uses GHOSTLINE_PAYER_SECRET, GHOSTLINE_SESSION, and policy env vars. Does not take a secret argument.
Channel
ghostline_open_channel
Open the channel in GHOSTLINE_CHANNEL_FILE. No arguments. Dry-run unless GHOSTLINE_OPEN_SUBMIT=1. Review the returned fee estimate, then set GHOSTLINE_OPEN_MAX_FEE to an explicit µT cap before broadcasting. Live open stores the deposit mask and creates the payer session. Refuses when the file already holds a deposit mask.
ghostline_close_channel
Close GHOSTLINE_CHANNEL_FILE. No arguments. Settles inside the expiry margin and refunds at or after expiry. A down output is output_spent. Broadcasts only when GHOSTLINE_CLOSE_SUBMIT=1. GHOSTLINE_CLOSE_DRY_RUN=1 prices the transaction and does not broadcast. Does not return the deposit mask.
ghostline_channel_session
Create the payer session for GHOSTLINE_CHANNEL_FILE, or keep one whose channel id matches. No arguments. Does not reset a cumulative total or return the deposit mask.
ghostline_channel_status
Off-chain channel totals and observer panel from GHOSTLINE_SESSION (optional GHOSTLINE_LEDGER). Does not take secrets. Not a chain confirmation.
ghostline_channel_list
One row per channel file in GHOSTLINE_CHANNEL_DIR. No arguments. Skips JSON that is not a channel record. Does not return the deposit mask, keys, or fee accounts.
ghostline_channel_calls
Accepted-call prices from ledgers under GHOSTLINE_CHANNEL_DIR. No arguments. Does not return voucher hex. Older ledgers are not backfilled.
ghostline_channel_file
Off-chain totals, expiry window, and channel-output presence for GHOSTLINE_CHANNEL_FILE. No arguments. Does not return the deposit mask, keys, or fee accounts.
Inspect
ghostline_channel_id
Compute the 32-byte Ghostline channel id from open parameters (hex).
ghostline_verify_voucher
Verify a hex-encoded Ghostline voucher against channel parameters.
ghostline_inspect_tx
List stealth outputs in a sealed Ghostline tx hex (resource, tag, commitment, nonce, encrypted data). No secret.
ghostline_unblind_tx
Recover value and mask from stealth outputs in a sealed tx hex encrypted to GHOSTLINE_PAYER_SECRET. Does not take a secret argument.