Buyer quickstart

Outcome. A funded buyer wallet, a configured market CLI, a discovered listing, a settled VM lease you can SSH into, and a clean teardown.

Before you run

If you completed Start here, the CLI is already installed and verified and ~/.config/arkhai/buyer.toml is scaffolded — skip §1 and reuse §2 as a reference while you add your wallet key and SSH public key. The At this revision note beside §2's negotiation block explains the default pricing before you copy it.

The synchronized document contains three moving installation conveniences: an unversioned PyPI install, a releases/latest download, and an unpinned git clone. They do not resolve to this site's inspected revision automatically. To reproduce the behavior documented here, use the source-install path and, immediately after cloning and before building or installing, run:

git checkout --detach 648682c67a26caf9283492e999923ab6ca1206ee

The moving release shortcut is useful for the current released CLI, but it must not be treated as evidence for this pinned guide.

Environment. The examples below target Base Sepolia (chain ID 84532) with test USDC, exactly as the synchronized document states. Every network command in this guide runs against the Registry URLs configured in buyer.toml and against the seller's storefront; buying creates a real on-chain escrow on the configured chain. The named public preproduction Registry in the synchronized body is an optional read target only. It was observed to allow unauthenticated reads on 2026-08-13; that dated probe is not a promise of continuing access, and write authority was neither tested nor granted. It may be empty and does not establish inventory or availability.

---

Install the market CLI, point it at a listing registry, find a listing, buy compute, and SSH into the leased VM.

For the seller side see seller-quickstart.md.

Prerequisites

• Linux or macOS (Windows: WSL).

• Python 3.12+.

• A wallet on the EVM chain the seller publishes on, funded with gas plus whatever ERC-20 the seller accepts. Examples below use Base Sepolia + USDC at 0x036CbD53842c5426634e7929541eC2318f3dCF7e (test funds from faucet.circle.com); any EVM chain with Alkahest deployed works.

• An RPC URL for that chain.

• An SSH keypair for leased VMs:

  ssh-keygen -t ed25519 -N "" -f ~/.ssh/mms_buyer_id_ed25519

  The pubkey gets injected into every VM you lease via cloud-init.

1. Install

From PyPI (lightest — just the buyer CLI). The market console script ships in arkhai-core-buyer; arkhai-vms-buyer adds the VM-compute plugin:

uv tool install arkhai-core-buyer --with arkhai-vms-buyer

Released build (latest):

curl -fsSL https://github.com/arkhai-io/simple-compute-market/releases/latest/download/install.sh | bash

Installs market into ~/.local/bin. The installer uses uv to provision the Python version required by the buyer CLI; a literal python3.12 system command is not required. Pin a version with ... | bash -s -- --version market-cli-v0.5.3.

In noninteractive Linux environments, allow apt dependency installation explicitly:

curl -fsSL https://github.com/arkhai-io/simple-compute-market/releases/latest/download/install.sh \
  | MARKET_INSTALL_ASSUME_YES=1 bash

Or from the repo:

git clone https://github.com/arkhai-io/simple-compute-market.git
cd simple-compute-market
make build-buyer
export PATH="$PWD/domains/vms/buyer/.venv/bin:$PATH"
market --version

2. Configure

market reads ~/.config/arkhai/buyer.toml. Scaffold with market config init-user or write directly:

[wallet]
private_key    = "0x<YOUR_BUYER_PRIVATE_KEY>"
ssh_public_key = "ssh-ed25519 AAAA...your-key buyer@host"

[chains.base_sepolia]
chain_id = 84532
rpc_url  = "https://sepolia.base.org"   # public RPC; or your own provider

[registry]
# The Arkhai public listing registry (preprod, Base Sepolia listings):
urls = ["http://34.41.205.175/registry"]
# Or point at any other listing registry, e.g. a self-hosted one:
# urls = ["http://<REGISTRY_HOST>:8080"]

[registry.auth]
# Required when the listing registry gates reads (REGISTRY_REQUIRE_READ_API_KEY=true).
# The public preprod listing registry is currently read-open — no token needed.
# Keys must match the URLs in [registry] urls exactly (scheme, host,
# port, no trailing slash).
# "http://<REGISTRY_HOST>:8080" = "<your-token>"

[negotiation]
# Ordered policy chain run per round. The buyer's default chain pairs
# `buyer_escrow_shape_guard` (vetoes if the seller mutates a buyer-
# pinned field) with the `bisection` terminal. Switch the terminal to
# `"rl"` for the trained pufferlib checkpoint (~1GB torch download).
# For per-escrow-kind dispatch, replace this list with a
# [negotiation.policies] table; see docs/configuration.md.
# See docs/configuration.md for the full reference.
policies = ["buyer_escrow_shape_guard", "bisection"]

At this revision

This example explicitly installs the opt-in bisection policy, and §4's --initial-price/--max-price flags supply scalar price bounds for it. The pinned configuration contract defines listed_price as the default: it opens at the advertised amount and never counters. For direct listed-price acceptance, omit the policies line (or set policy = "listed_price") and omit those two flags in §4. See Optional negotiation and the pinned configuration reference.

3. Browse

market listing list
market listing list --gpu-model H200
market listing show <listing_id>

list queries every URL in [registry] urls in parallel and dedupes.

4. Buy

Warning

This command spends configured funds: once a listing is matched it locks a real on-chain escrow on the configured chain (Base Sepolia with test USDC in this guide). If the run fails after escrow creation, resume it with market buy --from <run_id> — re-running market buy from scratch creates a second escrow and locks more funds.

market buy \
  --gpu-model H200 \
  --duration-hours 1 \
  --initial-price 2 \
  --max-price 2 \
  --settlement-timeout 1800 \
  --yes

The CLI discovers a matching listing, negotiates via bisection, locks escrow on chain, and polls until the seller returns status: ready with VM credentials.

Useful flags:

• --initial-price / --max-price — bid range in human / whole-token units per hour (USDC: --max-price 2 = $2/hr; the CLI scales by the token's on-chain decimals()).
• --gpu-count-min, --region, --vcpu-min, --ram-gb-min, --disk-gb-min — additional listing filters.
• --settlement-timeout — default 600s. Real cloud-init can take 5-10 min; bump to 1800 if you see timeouts before progress.
• --token-contract — optional filter: only consider listings whose accepted escrow uses this ERC-20. Omit it and the token comes from the chosen listing. --token-decimals skips the on-chain decimals() lookup.

The terminal output includes a Connection block. Use the vm_host_ip field (the printed ssh_command references the inventory alias, not the DNS name):

ssh -i ~/.ssh/mms_buyer_id_ed25519 -p <port> tenant<id>@<vm_host_ip>

5. Resume an interrupted buy

Every market buy writes a JSONL run log at ~/.local/state/arkhai/buy-runs/<run_id>.jsonl:

market logs runs                  # list past runs + last status
market logs show <run_id>         # full event log for one run
market buy --from <run_id>        # resume from wherever the run stopped

buy --from picks up the same run-log — mid-negotiation, post-escrow, or post-submit — and walks it to terminal. market settle --from is a narrower alias that skips straight to stages 3-5 (escrow.create + settle + poll); it assumes the negotiation already agreed.

If buy crashed after escrow creation but before settle, always resume — re-running a bare market buy against the same listing creates a second escrow and locks more funds.

6. Tear down

Leases auto-expire at agreed_duration_seconds. The seller's lease watchdog releases the resource and either claims or refunds the escrow once the timeout passes.

To exit early after expiration_unix:

market escrow reclaim <escrow_uid>

Common pitfalls

• Prices on the CLI are human / whole-token units per hour. 2 with 6-decimal USDC = $2/hr. Run-log entries record post-scaling base units.
• A bisection opening below the seller's advertised floor can terminate immediately. Set --initial-price to at least the listing's advertised primary rate. The default listed_price policy opens at that rate automatically.
• market buy and settle are not idempotent on chain. A buy that fails after escrow creation locks funds until expiration_unix. Resume with market buy --from <run_id>, don't re-buy from scratch.
• VM SSH uses vm_host_ip, not the alias the ssh_command field prints (tenant<id>@kvm1 etc. — the host name is the seller's inventory alias, not DNS).
• The tenant user has no sudo password. Cloud-init only injects your SSH pubkey.
• [registry.auth] keys must match [registry] urls exactly — scheme, host, port, no trailing slash. Mismatch silently sends unauthenticated requests, you get 401s.