Full virtual machines
QEMU/KVM
Cloud images, initial SSH accounts and public keys, with optional guest sudo. Stopped VMs support CPU/RAM updates and virtual-disk growth; guest partitions and filesystems grow separately.
Prepare a QEMU guest →A lightweight private cloud
VMs and containers, on your own hosts.
TTstack gives developers and small teams one place to create, access, stop, restart and delete environments across a small fleet.
Architecture
Fleet coordination. Local execution.
The controller places workloads and coordinates environments. Each host agent owns its engines, disks and networking.
Clients
tt CLI
REST client
Browser dashboard
HTTP
tt-ctl
Placement and lifecycle
Fleet observations
Controller
SQLite
HTTP
tt-agent
One per resource host
Native engines and storage
Agent
SQLite
ttcore supplies API models, capability contracts and
host implementations.
Read the architecture guide →
Usage
Create an environment. Keep its disk.
With a configured CLI, a registered QEMU host and a prepared
alpine-cloud image, this example retains the guest
until you delete it.
Create and inspect
tt env create demo --image alpine-cloud \
--engine qemu --cpu 1 --mem 256 --disk 2048 \
--ssh-key ~/.ssh/id_ed25519.pub --lifetime 0
tt env show demo
Use the guest IP from the agent host, or the configured SSH
endpoint reported by env show from a remote client.
Wait for SSH readiness.
Stop, restart and delete
# Stop retains the guest disk.
tt env stop demo
# Start boots the retained disk again.
tt env start demo
# Delete removes disks and recovery points.
tt env delete demo
Omit --lifetime 0 for the six-hour default; expiry also
deletes the guest disks. running describes the VM
process, not SSH or application readiness. Follow the
full installation walkthrough
and
SSH guide
for setup and access.
Engines
Choose the guest you need.
One lifecycle interface, with explicit requirements for each engine and storage backend.
Prepared microVMs
Firecracker
A prepared kernel and ext4 rootfs under jailer, with resource limits, read-only configuration and stopped-VM resizing. Prepared images can support SSH; the built-in smoke image checks boot and networking only.
Prepare a Firecracker guest →Application containers
Docker/Podman
Images with a long-running default command and requested application ports. The selected runtime stays bound to the agent inventory. Container disk quotas, managed SSH and VM network policies are unavailable.
Prepare a container →Lifecycle
Explicit state, retained resources.
Creation is saved before provisioning. A timeout can leave running or partial resources; inspect the existing environment before retrying.
creating- A saved plan is being provisioned.
active- All VM processes run without reported errors.
stopped- Execution has stopped; disks remain.
failed- Inspect errors and retained resources.
deleting- Cleanup continues until resources are removed.
Start boots stopped guests; VM memory does not survive a stop. Delete and expiry remove guest storage and backups. The controller retries incomplete deletion; host reboot does not automatically restart guests. Lifecycle and recovery contract →
Operations
Know what the host can do.
Capability checks guide admission. Runtime state, image eligibility and capacity still matter when each operation executes.
Inspect support
tt capabilities shows the design matrix.
tt host show HOST_ID shows scoped host prerequisites
and denial reasons.
Place by reservation
CPU, memory and disk figures are configured budgets and reservations. VM placement prefers eligible zvol hosts, then packs by remaining memory.
Placement and storage →Resize while stopped
QEMU and Firecracker accept CPU/RAM changes and root-disk growth. Updates preserve the VM identity and disk; shrinking is unsupported.
Offline resource updates →Keep a disk recovery point
Opt-in, stopped-only backups use qualified zvol snapshots or strict Linux file reflinks. Restore overwrites the current disk and leaves the VM stopped.
Backup eligibility and retries →Choose network controls
Linux QEMU and Firecracker support routed outgoing denial and separate guest isolation from host services, peers and private networks.
Networking and isolation →Prepare images on each host
Local recipes prepare guest images; deployment installs services. Register hosts separately and wait for their image catalog before placement.
Images and discovery →Scope and access
A manager for small, trusted fleets.
- One administrator boundary. Deployment configures a shared API key; owner names are labels. Services use HTTP without built-in TLS. Protect management access with a trusted network or protected tunnel/proxy. Manual starts without a key leave the API unauthenticated.
- Local resources, caller-owned policy. There is no image distribution, guest migration, HA or cross-host private network. User identity, application installation and idle-stop policy belong to callers. Disk recovery points share the host storage's failure domain.
- Evidence for named revisions. The 50-host and 1000-VM limits are guardrails, not benchmarked capacity. Implementation, host probes and live guest validation prove different things; the compatibility guide and dated reports record the tested combinations and limits.
Documentation
Start with the guide for your task.
Current behavior lives in maintained guides. Proposals retain design context; validation reports record evidence at specific revisions.
-
Architecture
Ownership, request flow, persistence and placement.
-
Deployment
Prerequisites, installation, fleet setup and upgrades.
-
Guest images
Recipes, storage layouts and guest networking.
-
REST API
Requests, returned states and failure recovery.
-
Initial SSH access
Accounts, public keys, endpoints and readiness.
-
Technical capabilities
Design support, scoped host reports and admission.
-
VM disk backup
Recovery points, destructive restore and exact retries.
-
Compatibility
Platform limits, CI and recorded live evidence.