Skip to main content
The Simulate API lets you programmatically create, manage, and control simulation environments. Test your homelab configurations in isolated sandboxes before deploying to production.

​
Base URL

EnvironmentBase URL
Local (default)http://localhost:5270/api/v1
Self-hostedhttps://your-sim-server/api/v1

​
Quick start

​
1. Create a simulation

curl -X POST http://localhost:5270/api/v1/simulations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-test-env",
    "nodes": [
      {"name": "server-1", "os": "ubuntu-22.04"}
    ]
  }'
Response: 
{
  "id": "sim_abc123",
  "name": "my-test-env",
  "status": "creating",
  "nodes": [
    {
      "id": "node_xyz789",
      "name": "server-1",
      "status": "creating",
      "ssh_port": 30001
    }
  ]
}

​
2. Wait for ready state

# Poll until status is "running"
curl http://localhost:5270/api/v1/simulations/sim_abc123

​
3. SSH into your node

ssh -p 30001 root@localhost

​
4. Clean up

curl -X DELETE http://localhost:5270/api/v1/simulations/sim_abc123

​
Endpoint reference

MethodEndpointDescription
Simulations
GET/simulationsList all simulations
POST/simulationsCreate new simulation
GET/simulations/{id}Get simulation details
DELETE/simulations/{id}Delete simulation
POST/simulations/{id}/startStart all nodes
POST/simulations/{id}/stopStop all nodes
POST/simulations/{id}/snapshotCreate snapshot
POST/simulations/{id}/restoreRestore from snapshot
Nodes
GET/simulations/{id}/nodesList nodes in simulation
GET/simulations/{id}/nodes/{nodeId}Get node details
POST/simulations/{id}/nodes/{nodeId}/execExecute command
POST/simulations/{id}/nodes/{nodeId}/restartRestart node
Templates
GET/templatesList available templates
GET/templates/{id}Get template details
POST/simulations/from-templateCreate from template

​
Common patterns

name: Test Homelab Config
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Start Sim server
        run: docker run -d -p 5270:5270 ghcr.io/kombify/sim
        
      - name: Create simulation
        run: |
          RESP=$(curl -s -X POST http://localhost:5270/api/v1/simulations \
            -H "Content-Type: application/json" \
            -d '{"name": "ci-test", "nodes": [{"name": "test", "os": "ubuntu-22.04"}]}')
          echo "SIM_ID=$(echo $RESP | jq -r .id)" >> $GITHUB_ENV
          
      - name: Wait for simulation
        run: |
          for i in {1..30}; do
            STATUS=$(curl -s http://localhost:5270/api/v1/simulations/$SIM_ID | jq -r .status)
            if [ "$STATUS" = "running" ]; then break; fi
            sleep 2
          done
          
      - name: Run tests
        run: ssh -p 30001 root@localhost 'echo "Running tests..."'
        
      - name: Cleanup
        if: always()
        run: curl -X DELETE http://localhost:5270/api/v1/simulations/$SIM_ID

SIM_ID="sim_abc123"

# Create simulation
curl -X POST http://localhost:5270/api/v1/simulations \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "nodes": [{"name": "server", "os": "ubuntu-22.04"}]}'

# Make changes via SSH...

# Snapshot before risky operation
SNAP=$(curl -s -X POST "http://localhost:5270/api/v1/simulations/$SIM_ID/snapshot" \
  -H "Content-Type: application/json" \
  -d '{"name": "before-changes"}' | jq -r .id)

# Make risky changes...

# If something breaks, restore
curl -X POST "http://localhost:5270/api/v1/simulations/$SIM_ID/restore" \
  -H "Content-Type: application/json" \
  -d "{\"snapshot_id\": \"$SNAP\"}"

# Execute a command on a specific node
curl -X POST "http://localhost:5270/api/v1/simulations/sim_abc123/nodes/node_xyz789/exec" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "apt-get update && apt-get install -y docker.io",
    "timeout": 120
  }'
Response:
{
  "exit_code": 0,
  "stdout": "Reading package lists...\n...",
  "stderr": "",
  "duration_ms": 45230
}

​
Error handling

All errors follow this format: 
{
  "error": {
    "code": "SIMULATION_NOT_FOUND",
    "message": "Simulation sim_xyz does not exist"
  }
}

​
Common error codes

CodeHTTP StatusMeaning
SIMULATION_NOT_FOUND404Simulation doesn’t exist
NODE_NOT_FOUND404Node doesn’t exist
ALREADY_RUNNING409Simulation already started
RESOURCE_LIMIT507System resources exhausted
TEMPLATE_NOT_FOUND404Template doesn’t exist

​
Resource requirements

Each simulation node requires host resources:
Node TypeCPUMemoryDisk
Minimal1 vCPU512Mi2Gi
Standard2 vCPU2Gi10Gi
Large4 vCPU8Gi50Gi
Sim uses containerized VMs. Running many simulations simultaneously may exhaust host resources.

​
Next steps

Simulations

Full simulations API reference

Nodes

Individual node management

Templates

Pre-built simulation templates

Sim Overview

About kombify Simulate