Concepts
Understand Caveman's workflow and the key entities that power your infrastructure. From Git to production in a single, opinionated path.
What is Caveman?
Caveman is a deployment and infrastructure management platform. It connects your code repositories to your cloud providers, handles builds, manages configuration, and gives you visibility into what's running where.
Unlike tools that try to do everything, Caveman is opinionated. We believe the best infrastructure tools are invisible—they work so you can focus on building.
Everything starts with Git.
We insist on connecting a repository. Your deployment configs, environment templates, and CI workflows live in code. This isn't optional—it's how you get reproducible, auditable infrastructure.
Simplicity First
Every feature we add is weighed against the complexity it introduces. We make decisions for you—opinionated defaults that work for 95% of cases. You can always override, but you shouldn't have to configure your monitoring tool just to see if your API is up.
Workspaces
A workspace is your team's home. It contains services, dashboards, credentials, and members. Users can belong to multiple workspaces with different roles (owner, admin, member).
When you sign up, you get a personal workspace. Create additional workspaces for teams, projects, or clients—each with its own isolated resources.
Sources
Sources are credentials that connect Caveman to your code and container registries. They enable two key capabilities:
Clone repositories, read configs, trigger builds from source code.
Pull container images for deployment. Push built images to registries.
We insist on connecting a repository.
Your repo contains more than code. It has Dockerfiles, compose files, environment templates, and deployment scripts. When you connect a repo, we can use these configs directly—no manual re-entry, no drift.
Only you can use this source. Good for personal projects.
All workspace members can use this source. Good for team projects.
Services
A service is a logical unit—your API, your database, your worker, your ML model. Services have types: web, database, worker, gpu_workload, and more.
All instances of a service run the same code with the same configuration.
Different config = different service. This isn't a limitation; it's clarity.
When you deploy a web API, every instance should behave identically. They share the same environment variables, secrets, and feature flags. This eliminates "works on machine A but not on machine B" bugs entirely.
"api-production" and "api-staging" are separate services with different configs.
One "api" service where some machines have DEBUG=true and others don't.
Caveman is the source of truth for configuration.
Environment variables are stored here, encrypted at rest. We push to providers (Fly, RunPod, GCP), not pull from them.
Most tools treat cloud providers as the source of truth. You set env vars in Fly's dashboard, RunPod's UI, or AWS console. Then you hope they're in sync. They never are.
Caveman flips this. Your config lives here, encrypted with AES-GCM. When you deploy, we push to your provider. One source, multiple targets. No drift.
Service Registries
A service registry links your service to its sources and targets. Each service can have:
Where to pull code/images from. Your Git repo or container registry.
Where to deploy to. The host that runs your service instances.
Hosts
Hosts are deployment targets—the infrastructure where your services run. Connect your cloud accounts and bare metal servers to deploy anywhere.
Same service. Fly + GCP + bare metal. We don't care.
Your "api" service can span multiple clouds. We see them all as instances.
Cloud lock-in is real. But it doesn't have to extend to your management layer. Run your API on Fly for low-latency edge. Run ML inference on RunPod for GPUs. Run batch jobs on cheap bare metal.
They're all instances of services in Caveman. Same dashboard. Same metrics. Same commands. The underlying platform is metadata, not a boundary.
Probe
The Caveman probe is a lightweight agent that runs on your machines. It collects metrics, streams logs, and reports back to your workspace. One binary, all platforms.
Download Probe
Available for Linux, macOS, and Docker
Installation
curl -sSL https://repo.cveman.com/install.sh | sh
docker run -d cveman/probe --token YOUR_TOKEN
RUN curl -sSL https://repo.cveman.com/install.sh | sh
# Probe auto-detects FLY_APP_NAME and region
What it Monitors
Usage, load average
Used, available, swap
Space, I/O, mounts
Bandwidth, connections
Running, top consumers
stdout, stderr, files
Auto-Discovery
When the probe connects, it sends platform metadata. On Fly.io, we detect the app name, machine ID, and region. On RunPod, similar. On bare metal, hostname and IP. If we match the machine to a service registry, it's auto-assigned.
fly_app_name=my-api
external_name=my-api
Dashboards
Dashboards give you visibility into your services. The default "Mission Control" shows all services at a glance. Create custom dashboards with panels for specific use cases.
Stream service logs
Time series metrics
Single metric value
Running processes
Structured data
Health indicators
Saved dashboards that persist across sessions. Shared with workspace.
Session-only views. Open a service, close the tab when done.