Skip to main content
Run kombify Simulate on your own server using Docker Compose. Simulate is a local-first development tool with no authentication required by default.
Requirements: Docker 24+ and Docker Compose v2 on Linux, macOS, or Windows with WSL2.

​
Quick start

1

Create project directory

mkdir -p ~/kombisim && cd ~/kombisim
mkdir -p data
2

Create Docker Compose file

docker-compose.yml
services:
  kombisim:
    image: ghcr.io/kombify/sim:latest
    container_name: kombisim
    restart: unless-stopped
    ports:
      - "5270:5270"           # REST API
      - "30000-39999:30000-39999"  # SSH access to simulated nodes
    environment:
      - KOMBISIM_PORT=5270
      - KOMBISIM_DATA_DIR=/data
      - KOMBISIM_LOG_LEVEL=${KOMBISIM_LOG_LEVEL:-info}
      - KOMBISIM_ENGINE=${KOMBISIM_ENGINE:-docker}
    volumes:
      - ./data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5270/health"]
      interval: 30s
      timeout: 10s
      retries: 3
3

Start the service

docker compose up -d
4

Verify it's running

curl http://localhost:5270/health
No authentication is required by default. Simulate is designed as a local development and training tool.

​
Port mapping

PortPurpose
5270REST API and web interface
30000-39999SSH access to simulated nodes
The SSH port range supports up to 10,000 simultaneous simulated nodes. Each node is assigned a unique port within this range when created.
The SSH port range is 30000-39999. Older documentation may reference 2222-2322 — this is outdated and incorrect.

​
Environment variables

VariableDefaultDescription
KOMBISIM_PORT5270API server port
KOMBISIM_DATA_DIR/dataData directory (SQLite storage)
KOMBISIM_LOG_LEVELinfoLog verbosity: debug, info, warn, error
KOMBISIM_ENGINEdockerSimulation engine (see below)

​
Engine selection

Simulate supports multiple engines for running simulated nodes. Set the engine via the KOMBISIM_ENGINE environment variable.
Uses Docker containers to simulate nodes. Requires the Docker socket to be mounted.
environment:
  - KOMBISIM_ENGINE=docker
volumes:
  - /var/run/docker.sock:/var/run/docker.sock
Best for: local development, CI/CD pipelines, lightweight simulations.
The Docker engine is the default and requires no additional setup beyond mounting the Docker socket. Cloud engines (Azure, DigitalOcean) require provider credentials configured in Simulate.

​
Verify installation

# Check the container is running
docker compose ps

# Check health endpoint
curl http://localhost:5270/health

# View logs
docker compose logs -f kombisim

​
Data persistence

Simulate stores all state in SQLite within the /data directory. The ./data bind mount ensures data survives container restarts and upgrades. To back up your Simulate data: 
# Stop the container first for a consistent backup
docker compose stop kombisim
cp -r ./data ./data-backup-$(date +%Y%m%d)
docker compose start kombisim

​
Troubleshooting

docker compose logs kombisim
Common causes:
  • Port conflict: Another process is using port 5270 or ports in the 30000-39999 range.
  • Docker socket not available: Ensure /var/run/docker.sock exists and is accessible.
  1. Confirm the node is running: check the API or web interface
  2. Verify ports 30000-39999 are not blocked by a firewall
  3. Use the port shown in the node details, e.g. ssh -p 30001 root@localhost
  • Docker engine: Verify the Docker socket is mounted and the Docker daemon is running
  • Incus/QEMU: These engines require the respective tools installed on the host
  • Cloud engines: Check that provider credentials are configured correctly

​
Next steps

Templates

Use pre-built templates for common simulation setups

SSH access

Connect to your simulated nodes via SSH