Skip to content
Ghostline

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.

  1. 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
  2. 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
  3. 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
  4. 04

    Connect the MCP server

    Add the config below to your MCP host. Secrets stay in the environment, never in tool arguments.

    Guide
  5. 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.

Keep the payer secret out of this file. Set GHOSTLINE_PAYER_SECRET in the environment that starts your host, and give each server only its own wallet’s cookie.
claude_desktop_config.json
{
  "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.