docs/quickstart.md

Ref: main v0.0.5   Size: 3.0 KiB   History

# Quickstart

*From nothing to a VM you can SSH into*

eitri.sh runs a control plane so you don't have to. You bring the
hardware; the console, sync, and SSH gate are already up. No server
install at all. Prefer to run the plane yourself? [self-hosting](self-hosting.md)
does the same job on your own box, and the three steps below are unchanged
after it.

## Create an account

Open <https://console.eitri.sh> and sign in with Google. Your first
sign-in creates your tenant.

## Join a host

Any machine with KVM, or a Mac. **+ Add host** in the console prints a one-shot
command; the machine dials out, and no inbound port is needed.
[joining](joining.md) has the commands for both, and the sharp edges of a Mac.

## Start a client

SSH access uses certificates signed by **your** CA—eitri never holds a user key
that can enter your VMs. A guest trusts the CA set it is created with, so the
client and its CA come before your first VM. One binary, targeting the hosted
service by default:

```sh
OS=$(uname -s | tr A-Z a-z) ARCH=amd64             # arm64 laptop → ARCH=arm64
curl -fsSLO https://eitri.sh/dl/latest/SHA256SUMS
V=$(sed -n "s/.*eitri-cli_\(v[^_]*\)_${OS}_${ARCH}\.tar\.gz\$/\1/p" SHA256SUMS)
curl -fsSLO "https://eitri.sh/dl/latest/eitri-cli_${V}_${OS}_${ARCH}.tar.gz"
sha256sum -c SHA256SUMS --ignore-missing
tar xzf "eitri-cli_${V}_${OS}_${ARCH}.tar.gz"
sudo install -m 0755 "eitri-cli_${V}_${OS}_${ARCH}/eitri" /usr/local/bin/eitri
```

Then the guided setup:

```sh
eitri init
```

It asks for a personal access token—mint one in the console under **Settings →
Personal access tokens**—then registers a CA if your tenant has none, generating
one only if you have no key it can use, and writes `~/.eitri/config.json`.
Nothing happens without a `y`. [connecting](connecting.md) walks each step.

## Boot a VM

Console → **+ Create VM**, pick your host, create. Watch it boot in the browser
serial console. Defaults: 2 vCPUs, 2048 MB, 10 GB, the default image; status
reads `creating` while the image downloads and the guest boots, then `ready`.

A tenant with no registered CA is refused here, rather than handed a guest that
nothing can reach: the CA set is baked into the guest at create and registering
one afterwards does not reach a VM that already exists. Register a CA first—the
console's Settings page, `eitri ca upload <ca.pub>`, or the MCP `ca_upload`
tool—then create the VM.

## SSH in

`eitri init` wrote the plane, the gate and your tenant, so there is nothing
left to set:

```sh
eitri ssh <vm-name>
eitri ssh <vm-name> uptime
```

Skipped init? The console and gate fall back to the hosted defaults, and
`EITRI_TOKEN` alone is enough—`eitri ssh` asks the plane for your tenant and
its gate.

## Then what

- [connecting](connecting.md)—the jump gate, your CA, and `eitri ssh` by hand
- [networking](networking.md)—publishing a port, or putting a VM on your LAN
- [mcp](mcp.md)—letting an AI agent create and drive VMs
- [upgrade](upgrade.md)—upgrading agents, the server, cloud-hypervisor