Skip to content
Back to search

charter

MarketplaceWorks with Claude CodeGitHub

Agent skills for Charter, the compute marketplace on TOON: find an offer, open a lease, pay it by the interval and collect the job's output with the toon CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/drew-dot-com--charter/badge.svg)](/listings/drew-dot-com--charter)

HTML

<a href="/listings/drew-dot-com--charter"><img src="/api/listings/drew-dot-com--charter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines
  1. {
  2. "name": "charter",
  3. "owner": {
  4. "name": "Drew Pierson",
  5. "url": "https://github.com/drew-dot-com"
  6. },
  7. "description": "Agent skills for Charter, the compute marketplace on TOON: find an offer, open a lease, pay it by the interval and collect the job's output with the toon CLI.",
  8. "plugins": [
  9. {
  10. "name": "charter",
  11. "source": "./plugins/charter",
  12. "version": "0.3.0",
  13. "description": "Rent Charter compute from an agent node: read the kind 31390 offers, open a lease, pay each interval and fetch the output with toon_cli, or rent a home with a kept disk and SSH in.",
  14. "category": "protocol",
  15. "keywords": ["toon", "charter", "compute", "lease", "ilp"]
  16. }
  17. ]
  18. }
README.md · README · 181 lines
  1. # Charter
  2. [![CI](https://github.com/drew-dot-com/charter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/drew-dot-com/charter/actions/workflows/ci.yml)
  3. Compute leases on the TOON payment network. A host posts an offer for a machine, a renter pays per
  4. interval, and a container runs the renter's job for as long as the payments keep arriving. There is
  5. no account on either side, and the host can be a home machine with no domain and no open port (a
  6. hidden host, reached over Anyone).
  7. **Status: v1, first-party.** Every lease so far has Drew Pierson on both sides: he runs the one host,
  8. the door and the edge node, and both renters. There are no outside users yet. Four job images:
  9. `charter-job-python` runs the renter's own Python script (up to 8 KiB, NumPy included) with no
  10. network at all and returns its stdout, stderr and exit code; `charter-job-fetch` fetches up to five
  11. pages in a headless browser and returns a screenshot and the text of each; `charter-home` is a box
  12. the renter lives in: a 2 GiB disk kept between leases, SSH in at an onion address on the Anyone
  13. network, and network out only through the Anyone network, with `charter-x402` in it to pay the rent
  14. from a Base wallet by plain x402 (`jobs/home/x402-rent.mjs`); `charter-hermes` is the same home with
  15. Hermes Agent and the `charter` CLI preinstalled and a default boot that runs them (the boot pays
  16. the box's own rent). Why the python job is safe enough for a
  17. home host: `docs/superpowers/specs/2026-10-17-python-job-design.md`. The home's design:
  18. `docs/superpowers/specs/2026-11-04-home-image-design.md`.
  19. ## How it works
  20. - **Offer.** The host publishes a signed Nostr event, kind 31390, tag `["L","charter"]`: size,
  21. prices, the host's ILP address, the key to seal packets to, and badges. It lives 45 minutes and is
  22. republished every 20.
  23. - **Lease.** The host's `toon` node serves three priced apps: `charter-open` (start a lease),
  24. `charter-tick` (pay one interval, an hour on the live host) and `charter-status` (read state and output). Each
  25. answers only its own action. The container is created at open and started only once the first
  26. interval is paid. A lease whose renter stops paying is closed at the end of the paid time.
  27. - **Paying.** Packets are routed by ILP and settled by x402 channels. A renter with a `toon` node
  28. pays directly. A renter with only a browser wallet pays the door over x402 (USDC on Base), and the
  29. door pays the host over TOON. The door is a paying hop that never holds more than one interval:
  30. it pays the host each interval only after the renter's payment for it has verified.
  31. Prices on the live host: open 0.001 USDC, one hour 0.007 USDC (about 5 USDC for 30 days), a status read 0.0001 USDC. Until 2026-11-04 the interval was 30 seconds at 0.005.
  32. ## Rent
  33. From a browser: open the storefront at https://charter.mainnet.toonprotocol.dev, connect a wallet holding USDC on Base, pick a machine, enter
  34. URLs and click Rent. Your wallet signs once to put a deposit (at least 0.10 USDC) into an x402
  35. channel. Each interval after that is signed by the page, silently. What you do not use comes back
  36. when the lease ends.
  37. From an agent over HTTP, with an x402 client and USDC on Base: https://charter.mainnet.toonprotocol.dev/agents
  38. From any MCP client (Claude Code, Claude Desktop, Cursor and others): `claude mcp add charter -- npx -y charter-mcp`. The server keeps its own wallet in a key file, pays one x402 payment a tool call within an hourly and a daily cap, and needs no account. Source and the full tool list: [mcp/](mcp/).
  39. walks through every call and every price; https://charter.mainnet.toonprotocol.dev/llms.txt is the
  40. summary a model reads first. Only the tick is paid over x402; the door pays the host for the open and
  41. the reads. `scripts/bazaar-tick.mjs` is a worked example: one python lease, one tick paid with
  42. `@x402/fetch` from a key file, so a facilitator with a catalog lists the route (`--dry-run` pays nothing).
  43. From a `toon` node:
  44. ```sh
  45. charter offers --relay wss://relay.mainnet.toonprotocol.dev
  46. charter rent --offer <pubkey>:<id> --urls https://example.com --max-intervals 1 --relay wss://relay.mainnet.toonprotocol.dev --json
  47. ```
  48. `TOON_PASSPHRASE_FILE` names the file with the node wallet's passphrase.
  49. ### A home
  50. Open with your SSH public keys (one per line in a file) instead of a job:
  51. ```sh
  52. charter rent --offer <pubkey>:<id> --home keys.pub --max-intervals 2 --relay wss://relay.mainnet.toonprotocol.dev
  53. ```
  54. Over HTTP the body is `{ "offerId": "...", "home": { "sshKeys": ["ssh-ed25519 AAAA... comment"] } }`.
  55. Once the onion address is published (within about a minute of the first tick) the lease status
  56. carries `access: { "ssh": { "host": "<56 chars>.anyone", "port": 22, "user": "tenant" } }` and the
  57. CLI prints the line to log in with:
  58. ```sh
  59. ssh -o ProxyCommand="nc -x 127.0.0.1:<your Anyone SOCKS port> %h %p" tenant@<host>
  60. ```
  61. A toon node has such a port; with no Anyone client there is no way in. The box is Debian with
  62. Python 3, `uv`, Node 22 and git, as user `tenant` with no root, 1 CPU and 1 GiB. Everything it
  63. sends leaves through the host's Anyone client (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` are set; a
  64. raw socket to the internet fails). `~/.charter/boot.sh` runs at every start, and
  65. `/charter/paid-through` holds when the paid time runs out.
  66. The key set is the home's identity: the same keys open the same 2 GiB disk and the same onion
  67. address, and there is no key rotation. A home that paid a tick is kept 7 days, free, after its
  68. lease closes; one that never paid is removed at close. Anyone with your public keys can open your
  69. home and hold it, though not enter it. The operator can read your disk: secrets go in over SSH,
  70. never through Charter. The live host has two home slots, one of them Edison's. What the host promises about uptime:
  71. - No uptime figure. Expect restarts. Your disk survives them; your processes do not, so put what
  72. must run in `~/.charter/boot.sh`.
  73. - A tick pays an hour from the end of the paid time. Pay the next tick half an hour early (the
  74. tenant loop already does) so a short outage does not end the lease. Paying several ticks ahead
  75. buys that much patience and nothing else; a lease that closes refunds nothing.
  76. - A closed home keeps its disk and onion address for 7 days. Open again with the same keys.
  77. - A restart of the host program leaves a running home alone. A reboot of its VM puts a paid home
  78. back on its disk (`restarts` goes up), as long as the paid time has not run out.
  79. From inside the box, the same CLI keeps paying with `CHARTER_PAYER=toon-client` and the box's own
  80. wallet (`CHARTER_TOON_KEY_FILE`, `CHARTER_TOON_CHANNEL_STORE`, `CHARTER_TOON_CHAIN`; the connector and
  81. the offer are already set in the box as `CHARTER_CONNECTOR_URL` and `CHARTER_OFFER_JSON`):
  82. ```sh
  83. charter renew --offer <pubkey>:<id> --lease "$CHARTER_LEASE_ID" --max-intervals <n>
  84. ```
  85. `renew` pays each tick when it is due, so restarting `boot.sh` costs nothing extra. After `<n>` ticks it exits and nothing pays, so a box that should stay up runs `renew` again or picks `<n>` for the time wanted.
  86. When more than one process in the box pays (the rent, an agent's paid fetches, its posts to a relay), they
  87. must share one channel without two of them signing on it at once: a voucher names a running total, and a
  88. second signer races the first and gets its packets refused. So the box runs one `charter payer`, the
  89. process that owns the channel, and everything else pays through it with `CHARTER_PAYER=url`:
  90. ```sh
  91. charter payer & # owns ~/.charter/channels.json, serves 127.0.0.1:3510
  92. CHARTER_PAYER=url charter renew --offer <pubkey>:<id> --lease "$CHARTER_LEASE_ID" --max-intervals <n>
  93. ```
  94. The service also answers `GET /extract?url=` (a paid anonymous page fetch, the contract a Hermes
  95. `web-toon` plugin speaks), `POST /relay/post` (a signed note paid onto a relay) and
  96. `GET /relay/read` (a free relay read through the box's proxy); `docs/env.md` lists its variables.
  97. A home costs about 5 USDC for 30 days; a box that pays its own rent needs 2 USDC in its own channel and
  98. a little Base ETH for the one on-chain channel open. The whole of it, for agents, is
  99. https://charter.mainnet.toonprotocol.dev/agents#home.
  100. From an agent (Claude Code) with a `toon` node: the `charter` plugin in this repo is a skill that
  101. says what each packet holds and how `toon` 0.3 sends it, in the shape of
  102. [toon-protocol/toon-plugins](https://github.com/toon-protocol/toon-plugins).
  103. ```sh
  104. /plugin marketplace add drew-dot-com/charter
  105. /plugin install charter@charter
  106. ```
  107. The skill is `plugins/charter/skills/renting-charter-compute/SKILL.md`; its `references/lease-loop.sh`
  108. runs one whole lease as one command.
  109. ## Host
  110. Next to a running `toon` node, with Docker and Node 22 or later:
  111. ```sh
  112. npm ci && npm run build && npm install -g --prefix ~/.local .
  113. docker build -t charter-job-fetch jobs/fetch
  114. docker build -t charter-job-python jobs/python
  115. docker build -t charter-home jobs/home # only if the host offers homes
  116. docker build -f jobs/hermes/Dockerfile -t charter-hermes . # only for Hermes homes; from the repo root, after npm run build, and after charter-home
  117. toon add charter-open --to relay --url http://127.0.0.1:7401/ --price 1000 --yes
  118. toon add charter-tick --to relay --url http://127.0.0.1:7402/ --price 7000 --yes
  119. toon add charter-status --to relay --url http://127.0.0.1:7403/ --price 100 --yes
  120. ```
  121. Then fill `~/.config/charter/env` from `deploy/host/env.example` and enable
  122. `deploy/host/charter-host.service` (systemd user unit). `charter-host land` redeems the host's
  123. vouchers on chain. Every variable is in `docs/env.md`; the full deploy, door included, is
  124. `docs/demo.md`.
  125. A job container gets 1 CPU, 1 GiB, 256 pids, a read-only root, no capabilities and
  126. `no-new-privileges`. With `CHARTER_PROXY` set, its traffic leaves through the host's Anyone proxy.
  127. To offer homes, run `sudo bash deploy/host/install-home.sh` once in the VM (Charter's own Anyone
  128. client, the `charter-home` bridge and its firewall, and a sudo rule for `losetup` only), add
  129. `charter-home` (and `charter-hermes`, if built) to `CHARTER_ALLOW_IMAGES` and set `CHARTER_MAX_HOMES` and the other home variables
  130. in `docs/env.md`. A home gets 512 pids and the same limits otherwise. Operating them:
  131. `docs/ops.md`, "Homes".
  132. ## Develop
  133. ```sh
  134. npm ci
  135. npm test # node --test
  136. npm run typecheck
  137. npm run dev:door # the storefront with no payments and a fake host
  138. ```
  139. ## License
  140. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.