Quickstart

August 12, 2026 ยท View on GitHub

This is the shortest path from an empty Linux/KVM host to a running microVM you can exec into and SSH into. For the full option list see CONFIGURATION.md; for running and troubleshooting a fleet see OPERATIONS.md.

Prerequisites

  • A Linux host with KVM (/dev/kvm present). macOS can build and cross-check but cannot run microVMs.
  • Rust stable toolchain.
  • The release ELF vmlinux and an ext4 rootfs readable by taritd.
  • For cluster mode only: PostgreSQL reachable from every node.
  • For host networking only: root or CAP_NET_ADMIN, plus ip and nft.

1. Build both binaries

taritd (this repo) and the vmm microVM backend (sibling repo):

cd /path/to/tarit/orch
cargo build --release -p taritd

cd /path/to/tarit/vmm
cargo build --release --features "vmm-core/kvm vmm-core/boot vmm-memory-backend/kvm"

cd /path/to/tarit
sudo make guest
sudo install -d -m 0755 /var/lib/taritd
sudo install -m 0644 guest-assets/vmlinux guest-assets/rootfs.ext4 /var/lib/taritd/

make guest verifies the pinned release kernel checksum and falls back to the same checksum-pinned source build if the artifact is unavailable.

2. Run one node

cd /path/to/tarit/orch

export TARIT_API_KEY="$(openssl rand -hex 24)"
export TARIT_LISTEN='127.0.0.1:8080'
export TARIT_VMM_BIN='/path/to/tarit/vmm/target/release/vmm'
export TARIT_KERNEL='/var/lib/taritd/vmlinux'
export TARIT_ROOTFS='/var/lib/taritd/rootfs.ext4'
export TARIT_ROOTFS_READONLY=1        # optional read-only guest mount; base isolation is always CoW
export TARIT_SOCKET_DIR="$HOME/.taritd/sockets"
export TARIT_DB="$HOME/.taritd/fleet.db"

./target/release/taritd

Check it is up:

curl -sf http://127.0.0.1:8080/health
curl -sf -H "X-API-Key: $TARIT_API_KEY" http://127.0.0.1:8080/v1/cluster

The same binary is also a CLI. Point it at the node and reuse the API key:

export TARIT_BASE_URL='http://127.0.0.1:8080'
./target/release/taritd vm list

3. Create a VM and run a command

# HTTP
vm=$(curl -sf -H "X-API-Key: $TARIT_API_KEY" -H 'content-type: application/json' \
  -d '{"vcpus":1,"memory_mib":256}' http://127.0.0.1:8080/v1/vms \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

# or CLI
# vm=$(./target/release/taritd --json vm create --vcpus 1 --memory-mib 256 | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

./target/release/taritd exec "$vm" 'uname -a'

4. Interactive PTY and SSH

Both reach the guest through the vsock agent. There is no in-guest sshd.

Register your public key, then open an interactive PTY over the CLI:

./target/release/taritd ssh-key add ~/.ssh/id_ed25519.pub
./target/release/taritd pty "$vm"          # interactive shell; resize and exit work

Enable the SSH gateway to use a normal ssh client. The SSH username is the VM id; the gateway authenticates by registered key and bridges to the guest PTY:

export TARIT_SSH_GATEWAY=1
export TARIT_SSH_GATEWAY_ADDR='0.0.0.0:2222'
# restart taritd with these set, then:
ssh -p 2222 "$vm"@<taritd-host>

The same PTY stream is available over WebSocket at WS /v1/vms/{id}/pty/{pty_id}/connect?token=<connect_token> (binary frames are raw bytes, text frames are JSON resize/exit). The session connect_token comes from the POST /v1/vms/{id}/pty/sessions response. One connection may be active at a time, and the session remains reconnectable for five minutes after disconnect.

5. Cluster mode (optional)

Cluster mode is selected by setting TARIT_DATABASE_URL (shared PostgreSQL) and a strong shared TARIT_PEER_SECRET on every node. Any node then accepts API traffic and forwards to the owning host.

export TARIT_DATABASE_URL='postgres://user:pass@db.example:5432/taritd?sslmode=require'
export TARIT_PEER_SECRET="$(openssl rand -hex 32)"
export TARIT_HOST_ID="$(hostname)"
export TARIT_RPC_ADDR="http://$(hostname -i | awk '{print \$1}'):8080"

Each node needs its own TARIT_HOST_ID, TARIT_RPC_ADDR, TARIT_SOCKET_DIR, and TARIT_DB. See OPERATIONS.md for the full three-node table, load balancer guidance, and RDS setup, and RESILIENCE.md for the failover and scale behavior each of these settings drives.

Next steps