kombify Simulate

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?

🔧 Technical details

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.04`
Ubuntu 24.04	`ubuntu-24.04`
Debian 12	`debian-12`
Rocky Linux 9	`rocky-9`
Alpine 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

Base URL: https://api.kombify.io/v1/simulation (SaaS) or http://localhost:5270/api/v1 (self-hosted/local)

Simulations

# List simulations
curl https://api.kombify.io/v1/simulation/simulations

# Create simulation
curl -X POST https://api.kombify.io/v1/simulation/simulations \
  -d '{"name": "test"}'

# Delete simulation
curl -X DELETE https://api.kombify.io/v1/simulation/simulations/{id}

Nodes

# List nodes in simulation
curl https://api.kombify.io/v1/simulation/nodes?simulation_id={sim_id}

# Create node
curl -X POST https://api.kombify.io/v1/simulation/nodes \
  -d '{
    "name": "web-server",
    "simulation_id": "sim_xxx",
    "os": "ubuntu-22.04"
  }'

# Get node details
curl https://api.kombify.io/v1/simulation/nodes/{id}

# Delete node
curl -X DELETE https://api.kombify.io/v1/simulation/nodes/{id}

Resource Limits

Configure resources per node:

curl -X POST https://api.kombify.io/v1/simulation/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 https://api.kombify.io/v1/simulation/networks \
  -d '{
    "name": "backend",
    "subnet": "172.30.0.0/24",
    "simulation_id": "sim_xxx"
  }'

# Attach node to network
curl -X POST https://api.kombify.io/v1/simulation/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

Test failure scenarios

kombify Simulate lets you safely test failures:

# Stop a node to test failover
curl -X POST https://api.kombify.io/v1/simulation/nodes/{id}/stop

# Simulate network partition
curl -X POST https://api.kombify.io/v1/simulation/networks/{id}/disconnect \
  -d '{"node_id": "node_xxx"}'

Clean up after testing

Delete simulations when done to free resources:

curl -X DELETE https://api.kombify.io/v1/simulation/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

Overview

How-To

Explanations

Reference

kombify Simulate

The simple version

What is Simulate?

Why use Simulate?

Key features

Instant servers

Real SSH access

Safe experimentation

Network simulation

How it works

Quick Start

Architecture

Supported Operating Systems

Simulation Engines

Use Cases

API Overview

Simulations

Nodes

Resource Limits

Networking

Custom Networks

Network Topology Example

Best Practices

Next Steps

Self-Hosting Guide

Templates

Simulation Engines

API Reference

Overview

How-To

Explanations

Reference

Documentation Index

​The simple version

What is Simulate?

​Why use Simulate?

​Key features

Instant servers

Real SSH access

Safe experimentation

Network simulation

​How it works

​Quick Start

​Architecture

​Supported Operating Systems

​Simulation Engines

​Use Cases

​API Overview

​Simulations

​Nodes

​Resource Limits

​Networking

​Custom Networks

​Network Topology Example

​Best Practices

​Next Steps

Self-Hosting Guide

Templates

Simulation Engines

API Reference

The simple version

Why use Simulate?

Key features

How it works

Quick Start

Architecture

Supported Operating Systems

Simulation Engines

Use Cases

API Overview

Simulations

Nodes

Resource Limits

Networking

Custom Networks

Network Topology Example

Best Practices

Next Steps