TTstack — Lightweight Private Cloud

TTstack is a lightweight private cloud platform for mid-size teams and individual developers. Centralized management of VMs and containers across multiple physical hosts.

Quick Start

make release
sudo tt deploy all                          # deploy agent + controller
sudo tt image create all --engine docker    # generate Docker images
sudo tt image create alpine-cloud           # generate QEMU cloud image (SSH-ready)

tt config <controller-ip>:9200 --api-key <api-key> # key printed by deploy
tt host add <agent-ip>:9100                 # register a host

tt env create demo --image alpine-cloud --engine qemu --port 22
tt env show demo                            # see port mappings
ssh root@<host-ip> -p <mapped-port>         # password: ttstack

VM Access

Engine	How to access	Default credentials
QEMU cloud images	ssh root@<host> -p <mapped-port>	password: ttstack
QEMU custom images	SSH via port forwarding	your own
Docker	docker exec -it <container-id> sh	—
Firecracker	serial console only	—
Jail (FreeBSD)	jexec <jail-name> sh	—
Bhyve (FreeBSD)	SSH via port forwarding	depends on image

QEMU cloud images auto-configure via cloud-init: root password, SSH, networking — all set on first boot. See docs/guest-images.md.

Security

All /api/* endpoints require a Bearer token when --api-key is set (auto-generated on deploy). The web dashboard (/) remains open.

# Set in deploy.toml:
[general]
api_key = "your-secret-key"

# Or configure CLI directly:
tt config <addr> --api-key <api-key>

# Or via environment:
export TT_API_KEY=your-secret-key

Built-in Images

12 ready-to-use recipes — deploy and start creating VMs immediately:

Recipe	Engine	Description
alpine debian ubuntu rockylinux	Docker	Base OS containers
nginx redis postgres	Docker	Popular services
fc-alpine	Firecracker	Alpine microVM (~50MB)
alpine-cloud debian-cloud ubuntu-cloud	QEMU	SSH-ready cloud images
freebsd-base	Jail	FreeBSD 14.3 base

tt image recipes                            # list all
sudo tt image create all --engine docker    # all Docker images
sudo tt image create alpine-cloud           # one QEMU cloud image
sudo tt image create all                    # everything for this platform

See docs/guest-images.md for custom image creation.

Key Features

• Multi-engine: QEMU/KVM, Firecracker, Docker/Podman (Linux); Bhyve, Jail (FreeBSD)
• Multi-host fleet: up to 50 hosts, 1000 VM instances, best-fit scheduling
• Environments: group VMs with lifecycle control and auto-expiry (default 6h)
• Storage backends: ZFS snapshots, Btrfs subvolumes, raw copies
• Web dashboard: built-in monitoring UI at http://<controller>:9200
• Simple deploy: three binaries, SQLite, one command (tt deploy all)

Architecture

┌──────────┐             ┌──────────────┐             ┌───────────┐
│  tt CLI  ├──── HTTP ──►│   tt-ctl     ├──── HTTP ──►│ tt-agent  │ × N
└──────────┘             │ (controller) │             │ (per-host)│
┌──────────┐             │ + Web UI     │             └─────┬─────┘
│ Browser  ├──── HTTP ──►└──────┬───────┘                   │
└──────────┘                    │                    VM engines + storage
                           SQLite DB

Binary	Role
tt	CLI client
tt-ctl	Central controller: scheduling, state, web UI
tt-agent	Host agent: VM lifecycle, images, networking

CLI Reference

tt config <addr> [--api-key <api-key>]     Set controller address and API key
tt status                           Fleet-wide status

tt host add/list/show/remove        Manage hosts
tt env create/list/show/delete      Manage environments
tt env stop/start <name>            Lifecycle control

tt image list/recipes/create        Manage images
tt deploy agent/ctl/all/dist        Deploy TTstack

env create options

Option	Description	Default
-i, --image <name>	Base image (repeatable)	required
--engine <type>	qemu, firecracker, docker, bhyve, jail	qemu
--cpu <N>	vCPUs per VM	2
--mem <MiB>	Memory per VM	1024
--disk <MiB>	Disk per VM	40960
--dup <N>	Replicas per image	1
-p, --port <PORT>	Guest port to expose (repeatable)	—
--lifetime <SEC>	Auto-expiry (0 = 6h default)	21600
--deny-outgoing	Block outbound traffic	false

Platform Support

Platform	Engines	Networking
Linux	QEMU/KVM, Firecracker, Docker/Podman	nftables NAT
FreeBSD	Bhyve, Jail	PF NAT

Documentation

Document	Contents
docs/deployment.md	Full deployment guide, config reference, directory layout
docs/guest-images.md	Image formats, custom image creation, VM access details
docs/rest-api.md	REST API endpoints with curl examples
docs/compatibility.md	Platform test results and known issues

Project Structure

TTstack/
├── Cargo.toml              Workspace
├── Makefile                Build + deploy targets
├── tools/
│   └── deploy.toml.example Fleet configuration template
└── crates/
    ├── core/               Shared library (engines, storage, networking, models)
    ├── agent/              Host agent (tt-agent)
    ├── ctl/                Controller (tt-ctl)
    └── cli/                CLI client (tt)

License

MIT