docs/quickstart.md

Quickstart

A box is a Linux machine with root that you rent by the hour from your wallet. This page takes you from nothing to a root prompt and back, with the refund.

Open a box

Go to /app, press Connect wallet, pick a size and a number of hours (1 to 24), and choose how to pay:

  • ETH: one transaction to the Meter, open(size, hours, 0, 0) with the hours as value.
  • USDG: you sign an EIP-3009 authorization and the Meter pulls it. No gas on your side.

As soon as the receipt lands, the site asks the keeper to boot your box. It creates the microVM, starts the terminal and calls started onchain, which meters hour 1.

6 h box, stopped in hour 2
heldheldheldheldheldheld
paid 6 h, escrowed

Get root

Press terminal and sign the message rootbox:<box>:<time>. The terminal URL contains a secret derived from your box id; it changes every session and is handed only to the owner.

root@atlas:~# whoami
root
root@atlas:~# grep PRETTY /etc/os-release
PRETTY_NAME="Ubuntu 26.04.1 LTS"
root@atlas:~# apt-get update && apt-get install -y build-essential

Stop and get your hours back

Press stop and sign. The keeper stops the microVM, which snapshots the disk, and calls close(box, hoursUsed). That one transaction settles the hours you started and sends every other hour back to your wallet, in the token you paid with.

a real stop, from the ledger
reading the ledger

If the keeper has not closed a stopped box within 15 minutes, call forceClose(box) yourself: it settles the hours started before your stop and refunds the rest, so you can always get your escrow back without the keeper.

Wake it later

A stopped box sleeps. Its disk is kept for 7 days after its last session. In /app press wake: that is open(size, hours, pay, resumeOf) with the id of the box you stopped, and you find your files where you left them.