kombify Simulate lets you test your homelab configuration in a safe sandbox. Make mistakes, break things, learn — without risking your real servers.The simple version
What is Simulate? kombify Simulate creates virtual servers on your computer using Docker. These virtual servers look and act like real servers — you can SSH into them, install software, and test your entire homelab setup. When something breaks, just delete it and start over in seconds.
Why use Simulate?
kombify Simulate uses multiple engines (Docker, Incus, QEMU, Azure, DigitalOcean) to simulate real Linux servers. Each simulated node:
Runs a complete Linux distribution (Ubuntu, Debian, Rocky, Alpine)
Has its own SSH server accessible on unique ports (30000-39999)
Can be networked together in custom topologies
Supports resource limits matching real hardware specs
Architecture: Go backend with REST API for automation. Supports 5 engines for different fidelity levels.Key features
Instant servers Spin up simulated servers in seconds — no ISO downloads or VM setup
Real SSH access SSH into any simulated server just like a real one
Safe experimentation Break things without consequences — delete and recreate in seconds
Network simulation Test multi-node setups with custom networks and topologies
How it works
Start Simulate
Run kombify Simulate via Docker — it needs access to Docker socket to create containers
Create simulation
Name your simulation and choose which nodes you want
Add nodes
Add virtual servers with your choice of OS and resources
Connect and test
SSH into nodes, install software, test your configuration
Clean up
Delete the simulation when done — everything disappears
Quick Start
Start Simulate
docker run -d \ -p 5270:5270 \ -p 30000-39999:30000-39999 \ -v /var/run/docker.sock:/var/run/docker.sock \ ghcr.io/kombify/sim:latest
Verify API
Check the API is running: curl http://localhost:5270/health
Create Simulation
curl -X POST http://localhost:5270/api/v1/simulations \ -H "Content-Type: application/json" \ -d '{"name": "my-homelab"}'
Add Nodes
curl -X POST http://localhost:5270/api/v1/nodes \ -H "Content-Type: application/json" \ -d '{ "name": "server-1", "simulation_id": "sim_xxx", "os": "ubuntu-22.04", "resources": { "cpu": 2, "memory": "2048Mi" } }'
SSH into Node
# Port is assigned dynamically from range 30000-39999 # Check the node details for the assigned SSH port ssh -p 30001 root@localhost # Password: kombisim
Architecture Supported Operating Systems OS Image Ubuntu 22.04 ubuntu-22.04Ubuntu 24.04 ubuntu-24.04Debian 12 debian-12Rocky Linux 9 rocky-9Alpine 3.19 alpine-3.19
SSH ports are dynamically assigned from the range 30000-39999. Check the node details via API for the assigned port.
Simulation Engines kombify Simulate supports multiple backends for different fidelity levels:
Engine Type Best for Docker Container-based Fast iteration, CI/CD (default) Incus System container Full OS simulation with systemd QEMU Virtual machine Hardware-level fidelity Azure Cloud VM Real cloud infrastructure testing DigitalOcean Cloud VM Real cloud infrastructure testing
Set the engine via the KOMBISIM_ENGINE environment variable.
Use Cases Testing StackKits
Multi-Node Testing
CI/CD Testing
Test a StackKit configuration before deploying: # Start simulation kombify sim start --from kombination.yaml # Run validation kombify validate --against-sim # Deploy to simulation kombify deploy --target sim # Verify everything works kombify test --target sim
Test HA configurations with multiple nodes: # sim-config.yaml simulation : name : ha-test nodes : - name : node-1 os : ubuntu-22.04 role : primary - name : node-2 os : ubuntu-22.04 role : replica - name : node-3 os : ubuntu-22.04 role : replica network : subnet : 172.20.0.0/24
Run tests in CI pipelines: # .github/workflows/test.yml jobs : test : runs-on : ubuntu-latest steps : - uses : kombify/sim-action@v1 with : config : test-config.yaml - name : Run integration tests run : | kombify test --target sim
API Overview Simulations # List simulations curl http://localhost:5270/api/v1/simulations # Create simulation curl -X POST http://localhost:5270/api/v1/simulations \ -d '{"name": "test"}' # Delete simulation curl -X DELETE http://localhost:5270/api/v1/simulations/{id}
Nodes # List nodes in simulation curl http://localhost:5270/api/v1/nodes?simulation_id={sim_id} # Create node curl -X POST http://localhost:5270/api/v1/nodes \ -d '{ "name": "web-server", "simulation_id": "sim_xxx", "os": "ubuntu-22.04" }' # Get node details curl http://localhost:5270/api/v1/nodes/{id} # Delete node curl -X DELETE http://localhost:5270/api/v1/nodes/{id}
Resource Limits Configure resources per node:
curl -X POST http://localhost:5270/api/v1/nodes \ -d '{ "name": "db-server", "os": "ubuntu-22.04", "resources": { "cpu": 4, "memory": "4096Mi", "disk": "20Gi" } }'
Networking Custom Networks # Create isolated network curl -X POST http://localhost:5270/api/v1/networks \ -d '{ "name": "backend", "subnet": "172.30.0.0/24", "simulation_id": "sim_xxx" }' # Attach node to network curl -X POST http://localhost:5270/api/v1/nodes/{id}/networks \ -d '{"network_id": "net_xxx", "ip": "172.30.0.10"}'
Network Topology Example Best Practices
Use realistic resource limits
Match your simulation resources to actual hardware specs: nodes : - name : raspberry-pi resources : cpu : 4 memory : "4096Mi" # 4GB like real Pi 4
kombify Simulate lets you safely test failures: # Stop a node to test failover curl -X POST http://localhost:5270/api/v1/nodes/{id}/stop # Simulate network partition curl -X POST http://localhost:5270/api/v1/networks/{id}/disconnect \ -d '{"node_id": "node_xxx"}'
Delete simulations when done to free resources: curl -X DELETE http://localhost:5270/api/v1/simulations/{id}
Next Steps
Self-Hosting Guide Deploy Simulate on your own infrastructure
Templates Pre-built simulation templates
Simulation Engines Understanding the different engine backends
API Reference Full API documentation
