@machine0/cli 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+<h1 align="center">machine0</h1>
+<p align="center">Instant, AI-ready cloud VMs from your terminal</p>
+
+<p align="center"><code>npm install -g @machine0/cli</code></p>
+
+# Overview
+
+machine0 lets you create, provision and snapshot cloud VMs from your terminal. VMs have dedicated resources (including GPUs). Small VMs boot instantly. The default image ships with dev tools, modern shell tooling, coding agents and Docker pre-installed.
+
+Built on top of leading cloud infrastructure. Multi-region. Pay-as-you-go.
+
+## Quickstart
+
+```bash
+$ npm install -g @machine0/cli
+$ machine0 account login
+$ machine0 new my-vm
+$ machine0 ssh my-vm
+```
+
+## Benefits
+
+- 🧰 **Fully Loaded:** VMs come pre-installed with everything you need to work with AI.
+- ⚡ **Instant boot:** Small VMs are kept warm and boot in seconds.
+- 📐 **Multiple sizes:** From lightweight sandboxes to GPU instances.
+- 🌍 **Multiple regions:** Run VMs in the US, UK, EU or Asia.
+- 📌 **Fixed IPs:** Every VM gets a dedicated IP for its lifetime.
+- 🔒 **HTTPS endpoints:** Every VM gets `https://<vm>.mac0.io`.
+- 🔑 **SSH key management:** Use your own keys or create managed keypairs on the server.
+- 📦 **Ansible provisioning:** First-class support for running playbooks on your VMs.
+- 📸 **Snapshots:** Snapshot any VM into a reusable image.
+- 💳 **Pay-as-you-go:** Billed per minute. No commitments, no surprises.
+
+## Use Cases
+
+- 🤖 **Agent sandboxes:** Small instances are cheap and boot instantly. Snapshot your setup once, then spin up identical sandboxes on demand.
+- 🦞 **OpenClaw:** Use the `openclaw` image to get a machine running OpenClaw out of the box. Use `medium` or larger.
+- 💻 **Dev environments:** The provisioned image comes with Node, Bun, Python, Rust, Go, Docker and Claude Code. SSH in and start building.
+- 🌐 **Hosting:** Every VM has dedicated resources, a fixed IP and an HTTPS endpoint. Host APIs, bots, databases — anything that needs to stay up.
+- 🔧 **Ansible provisioning:** Write a playbook, run `machine0 provision my-vm playbook.yml`, done. Use a coding agent to author playbooks and disposable VMs to test them.
+
+# Documentation
+
+machine0 is CLI-first, but there is also a [web UI](https://api.machine0.io).
+
+## Creating a VM
+
+Small VMs boot instantly:
+
+```
+$ machine0 new my-vm
+✓ VM is starting
+$ machine0 ssh my-vm
+[ ubuntu@my-vm ] ~ $
+```
+
+## Images
+
+We provide the following system images to every account. These images are provisioned using our [Ansible Playbook](https://github.com/barnaby/machine0-ansible).
+
+```
+$ machine0 images ls
+┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ Name            Description                                                                                                                          │
+│ base-24-04      Includes the latest versions of Docker, node, python, go and rust. As well as coding agents such as Claude Code, Codex and OpenCode. │
+│ openclaw        'base-24-04' with OpenClaw pre-installed. Requires a 'medium' instance or larger.                                                    │
+│ ubuntu-24-04    Fresh Ubuntu 24.04 LTS. Used to provision the base image.                                                                            │
+└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+You can also create your own images (for example to clone your environment easily):
+
+```bash
+# Create a fresh VM we'll use as a template.
+$ machine0 new my-vm
+
+# Update the VM using `machine0 ssh` or `machine0 provision`, then image it.
+$ machine0 image my-vm my-base-image
+
+# Create as many VMs from the image as you'd like.
+$ machine0 create my-clone --image my-base-image
+
+# Optionally, set the image as the default.
+$ machine0 config set DEFAULT_VM_IMAGE=my-base-image
+```
+
+## Ansible Provisioning
+
+machine0 has first-class support for provisioning VMs with [Ansible](https://github.com/ansible/ansible). Use coding agents to author playbooks and disposable VMs to test them.
+
+```bash
+$ machine0 provision my-vm playbook.yml
+```
+
+We use this functionality to create the `base-24-04` image using a fresh Ubuntu. If you'd like to learn more, you can check out our [Ansible Playbook](https://github.com/barnaby/machine0-ansible).
+
+## Sizes & Regions
+
+We provide the following machine sizes. The price is the same regardless of where you spin up: `us` (New York), `uk` (London), `eu` (Amsterdam) & `asia` (Singapore).
+
+```bash
+$ machine0 sizes
+┌────────────────────────────────────────────────────────────┐
+│ Size      CPU        RAM      Disk      $/hour    ~$/month │
+│ small     1 vCPU     1 GB     25 GB     $0.01     $7       │
+│ medium    2 vCPU     2 GB     60 GB     $0.02     $15      │
+│ large     2 vCPU     4 GB     80 GB     $0.04     $29      │
+│ xl        4 vCPU     8 GB     160 GB    $0.08     $58      │
+│ xxl       8 vCPU     16 GB    320 GB    $0.16     $117     │
+│ xxxl      16 vCPU    32 GB    640 GB    $0.32     $234     │
+└────────────────────────────────────────────────────────────┘
+```
+
+You can use CLI options to specify the size and region of a machine. The default size is `small` (instant boot) and the default region is `eu`. You can change them using the `config` command ([see below](#configuration)).
+
+```bash
+$ machine0 new my-vm --size large --region us
+```
+ 
+## SSH Keys
+
+By default, machine0 uses your local public key (`~/.ssh/id_rsa.pub`). Your private key never leaves your machine. You can also create managed keypairs that are stored on the server — useful for teams or ephemeral setups.
+
+```bash
+$ machine0 keys ls
+┌────────────────────────────────────────────────────────┐
+│ Name                                Type       Default │
+│ barnaby@Barnabys-MBP.localdomain    PUBLIC     *       │
+└────────────────────────────────────────────────────────┘
+
+# Create a managed private / public keypair
+$ machine0 keys create my-managed-key --type managed --default
+```
+
+## Billing
+
+machine0 is pay-as-you-go. Resources are billed per minute.
+
+- **Machines** are billed while they exist (including when stopped, since they reserve cloud resources).
+- **Images**  are billed based on disk size at $0.06/GB/month.
+- Creating a resource requires enough balance for at least 10 hours of usage.
+- If your balance drops below 1 hour of runway, resources are automatically torn down.
+- Auto top-up can be enabled to prevent accidental teardowns.
+- Minimum top-up is $5 USD.
+- Outstanding credits are refundable if you decide machine0 is not for you.
+
+Check your balance:
+
+```
+$ machine0 account info
+┌──────────────────────────────────────┐
+│ Email             system@machine0.io │
+│ Wallet Balance    $9.02              │
+│ Auto Top-Up       enabled            │
+└──────────────────────────────────────┘
+```
+
+## CLI Reference
+
+```bash
+$ machine0
+
+USAGE
+  machine0 <command> [flags]
+
+COMMANDS
+   ls                                            List VMs
+   get <vm>                                      Show VM details
+   new <vm> [options]                            Create a VM
+   start <vm>                                    Start a VM
+   stop <vm>                                     Stop a VM
+   reboot <vm>                                   Reboot a VM
+   rm [vm] [options]                             Remove a VM (--all for all)
+   ssh <vm> [command] [options]                  SSH into a VM or run a command
+   provision <vm> <playbook> [options]           Run an Ansible playbook on a VM
+   sizes                                         Show available VM sizes and pricing
+
+IMAGES
+   images ls                                     List images
+   images get <image>                            Show image details
+   images create <vm> <image> [description]      Snapshot a VM into an image
+   images update <image> [options]               Update image settings
+   images rm [image] [options]                   Remove an image (--all for all)
+
+ACCOUNT
+   account info                                  Show account details
+   account login                                 Log in
+   account logout                                Log out
+
+KEYS
+   keys ls                                       List keys
+   keys get <key> [options]                      Show key details
+   keys new <key> [options]                      Add a key (managed or public)
+   keys update <key> [options]                   Update key settings
+   keys rm <key> [options]                       Remove a key
+
+  managed = keypair stored on server, local = register your own public key
+```
+
+### Configuration
+
+machine0 stores configuration in `~/.machine0/config.env`. You can get and set variables as follows:
+
+```
+$ machine0 config get
+┌───────────────────────────────────────────────┐
+│ SSH_KEY_PATH         ~/.ssh                   │
+│ DEFAULT_SSH_USER     ubuntu                   │
+│ DEFAULT_VM_SIZE      medium                   │
+│ DEFAULT_VM_REGION    eu                       │
+│ DEFAULT_VM_IMAGE     ubuntu-24-04-provisioned │
+└───────────────────────────────────────────────┘
+
+$ machine0 config set DEFAULT_VM_IMAGE=my-image
+✓ Config written to ~/.machine0/config.env
+```
+
+## Security
+
+- No keys stored on server by default.
+- SSH access only. Password authentication is disabled on all VMs.
+- Root login is disabled. All access is through the `ubuntu` user with sudo.
+- Managed keys can be downloaded once. Local keys never leave your machine.
+- Cloud-init randomizes the root password on every VM.
+
+# FAQ
+
+**Where is machine0 hosted?**
+VMs run on DigitalOcean's infrastructure. The API runs on GCP Cloud Run. Both are production-grade.
+
+**Can I export my data?**
+Yes. Your VMs are standard Ubuntu machines. SSH in and copy anything you need. There's no lock-in.
+
+**What if I run out of credits?**
+Resources are torn down when your balance can't cover 1 hour of usage. Enable auto top-up to prevent this.
+
+**How do I get support?**
+Send an email to [support@machine0.io](mailto:support@machine0.io), and we'll reply quickly.