Skip to main content

Virtual-machine domain guide

Outcome. You can follow one VM lease end to end — what the listing says, what the lease terms mean, how capacity becomes a running machine, what the buyer receives, and how the lease ends — with each step tied to the role that owns it.

The VM domain is the largest in-tree reference domain: listings describe compute slices, negotiation carries lease intent, fulfillment provisions machines, and settlement coordinates with the lease lifecycle.

Prerequisites​

  • Complete Start here so market --version and market --help work locally.
  • For a buyer run, complete the wallet, chain, Registry, and SSH-key setup in the Buyer quickstart.
  • For a seller run, start the storefront in mock mode through the Seller quickstart. Live delivery additionally requires a KVM-capable host and the reachability check in Fulfillment and seller delivery.

The synchronized role guides use Base Sepolia and test USDC. Mock seller mode verifies the market and settlement-facing surface without touching libvirt; HTTP provisioning mode can create and tear down real VMs on the seller's hosts. A Registry may validly return no matching listing.

Install and configure​

The VM plugin is installed with arkhai-vms-buyer and registers the VM listing, buy, negotiate, and settle commands. Keep domain terms in buyer.toml and seller inventory rather than browser state. Verify the installed surface before any network call:

market --version
market --help

Listing vocabulary​

A VM listing row declares its sellable shape — gpu_model, gpu_count, vcpu_count, ram_gb, disk_gb, region — plus commercial terms (min_price per hour, accepted token, max_duration_seconds) and a trusted capacity reference (attribute.pool_id or a projected resource_id, never a host address). Buyers filter on exactly this vocabulary (market listing list --gpu-model H200; market buy adds --gpu-count-min, --region, --vcpu-min, --ram-gb-min, --disk-gb-min).

Lease terms​

The buyer's provision terms carry start/end lease intent and machine access requirements; the SSH public key from buyer.toml is injected into every leased VM via cloud-init. Price negotiation, where configured, moves only the hourly amount (Optional negotiation); the duration the parties agreed (agreed_duration_seconds) bounds the lease.

From settlement to a running machine​

The seller side turns the settled deal into a machine through the physical path: site admission and reservation, pool routing, scheduler assignment, provider execution over Ansible and libvirt (cloud-init, virt-install, SSH port-forward NAT). Mock mode short-circuits provisioning for surface validation; live mode requires KVM-capable hosts. Seller-side detail: Fulfillment and seller delivery and the seller quickstart.

Run the buyer path​

Browse first, then run the configured purchase only when you are prepared to create payment escrow on the target chain:

market listing list --gpu-model H200

market buy \
  --gpu-model H200 \
  --duration-hours 1 \
  --settlement-timeout 1800 \
  --yes

Listed-price acceptance is the default policy. The explicit price-range and bisection configuration in the synchronized buyer example is opt-in; see Optional negotiation before adding it.

What the buyer receives​

A ready deal returns status: ready with a Connection block. Connect with the vm_host_ip field — the printed ssh_command references the seller's inventory alias, which is not DNS:

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

The tenant account has no sudo password; cloud-init only injects your SSH public key. Real cloud-init can take five to ten minutes — raise --settlement-timeout to 1800 rather than assuming failure.

Interruption and resume​

Every buy writes a JSONL run log. market logs runs lists past runs, market logs show <run_id> prints one, and market buy --from <run_id> resumes from wherever the run stopped — mid-negotiation, post-escrow, or post-submit. If a buy crashed after escrow creation, always resume: re-running a bare market buy against the same listing creates a second escrow and locks more funds. market settle --from is the narrower alias that skips straight to escrow-create, settle, and poll.

Lease end​

Leases auto-expire at the agreed duration; the seller's lease watchdog releases the resource and claims or refunds escrow. To exit early after expiration_unix:

market escrow reclaim <escrow_uid>

Expected output and verification​

  • Discovery prints a JSON array. [] is a valid no-match result.
  • A completed buy reaches status: ready and prints a Connection block with vm_host_ip, port, tenant name, and credential material supplied by the seller.
  • SSH to vm_host_ip succeeds with the buyer key; do not treat the seller's inventory alias as public DNS.
  • The seller can correlate the deal through its stage events while capacity remains held until seller-owned teardown succeeds.

Troubleshoot​

  • No matching listing — inspect raw Registry JSON and its filter spec; do not assume every Registry supports the same vocabulary.
  • Buy stops after escrow creation — resume with market buy --from <run_id>; starting a new buy can create a second escrow.
  • Ready status but SSH fails — use vm_host_ip, check the returned port, and allow cloud-init five to ten minutes in live mode.
  • Seller never reaches ready — verify provisioning-container Ansible reachability and that the listing's pool or resource remains admissible at the site authority.

Next steps​

Source and revision​

The synchronized walk-throughs are the buyer quickstart and seller quickstart; normative delivery contracts are the fulfillment, physical-provisioning, and VM storefront fulfillment specifications at the pin.