Skip to main content
Caravanserai lets you run Docker Compose-style workloads across a fleet of machines through a single control plane. Define your services as a Project, and Caravanserai schedules, starts, and monitors them on the best available Node in your cluster.

Quick Start

Deploy your first project in under 5 minutes.

Installation

Build and run the control plane, agents, and CLI.

Core Concepts

Understand Nodes, Projects, and the scheduling lifecycle.

API Reference

Full HTTP API reference for Nodes and Projects.

​
How it works

1

Run the control plane

Start cara-server — the central API server and controller manager that receives workload requests and manages cluster state.
2

Add nodes

Start cara-agent on each machine you want in your cluster. Agents self-register with the control plane and begin heartbeating.
3

Deploy a project

Write a YAML manifest describing your containers and apply it with caractrl apply -f project.yaml. The scheduler picks a node and your containers start.
4

Manage your cluster

Use caractrl get, delete, and port-forward to inspect resources, tear down workloads, and tunnel into running containers.

​
Key features

No Kubernetes required

Purpose-built for small-to-medium self-hosted clusters. No etcd, no CNI plugins, no cluster certificates.

Docker Compose semantics

Services within a Project share a Docker bridge network and resolve each other by name — just like Compose.

Declarative manifests

Define Nodes and Projects in YAML. Apply, inspect, and delete resources with caractrl.

Port forwarding

Tunnel local ports directly to containers on remote nodes over a secure WebSocket connection.