Skip to main content
Simulations are isolated environments where you can safely test homelab configurations. Each simulation contains one or more nodes (virtual servers) connected via virtual networks.

​
Endpoints

MethodEndpointDescription
GET/api/v1/simulationsList all simulations
POST/api/v1/simulationsCreate a new simulation
GET/api/v1/simulations/{id}Get simulation details
DELETE/api/v1/simulations/{id}Delete a simulation
POST/api/v1/simulations/{id}/startStart all nodes
POST/api/v1/simulations/{id}/stopStop all nodes
POST/api/v1/simulations/{id}/snapshotCreate a snapshot
POST/api/v1/simulations/{id}/restoreRestore from snapshot

​
List simulations

GET /api/v1/simulations
Query parameters:
ParameterTypeDescription
statusstringFilter by status: running, stopped, error
limitintMax results (default: 20)
offsetintPagination offset
Example: 
curl http://localhost:5270/api/v1/simulations
Response: 
{
  "simulations": [
    {
      "id": "sim_abc123",
      "name": "ha-cluster-test",
      "status": "running",
      "nodes_count": 3,
      "created_at": "2026-01-26T10:00:00Z",
      "started_at": "2026-01-26T10:01:00Z"
    },
    {
      "id": "sim_def456",
      "name": "single-node-test",
      "status": "stopped",
      "nodes_count": 1,
      "created_at": "2026-01-25T14:00:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

​
Create simulation

POST /api/v1/simulations
Content-Type: application/json
Request body: 
{
  "name": "my-test-env",
  "description": "Testing HA configuration",
  "nodes": [
    {
      "name": "primary",
      "os": "ubuntu-22.04",
      "resources": {
        "cpu": 2,
        "memory": "2048Mi"
      }
    },
    {
      "name": "replica-1",
      "os": "ubuntu-22.04",
      "resources": {
        "cpu": 2,
        "memory": "2048Mi"
      }
    }
  ],
  "networks": [
    {
      "name": "internal",
      "subnet": "172.20.0.0/24"
    }
  ]
}
Response: 
{
  "id": "sim_xyz789",
  "name": "my-test-env",
  "status": "creating",
  "nodes": [
    {
      "id": "node_aaa111",
      "name": "primary",
      "status": "creating",
      "ssh_port": 30001
    },
    {
      "id": "node_bbb222",
      "name": "replica-1",
      "status": "creating",
      "ssh_port": 30002
    }
  ],
  "networks": [
    {
      "id": "net_ccc333",
      "name": "internal",
      "subnet": "172.20.0.0/24"
    }
  ],
  "created_at": "2026-01-26T10:30:00Z"
}

​
Get simulation details

GET /api/v1/simulations/{id}
Response: 
{
  "id": "sim_xyz789",
  "name": "my-test-env",
  "description": "Testing HA configuration",
  "status": "running",
  "nodes": [
    {
      "id": "node_aaa111",
      "name": "primary",
      "os": "ubuntu-22.04",
      "status": "running",
      "ssh_port": 30001,
      "ip_addresses": {
        "internal": "172.20.0.10"
      },
      "resources": {
        "cpu": 2,
        "memory": "2048Mi"
      }
    }
  ],
  "networks": [
    {
      "id": "net_ccc333",
      "name": "internal",
      "subnet": "172.20.0.0/24",
      "gateway": "172.20.0.1"
    }
  ],
  "created_at": "2026-01-26T10:30:00Z",
  "started_at": "2026-01-26T10:31:00Z"
}

​
Start simulation

Starts all nodes in the simulation. 
POST /api/v1/simulations/{id}/start
Response: 
{
  "id": "sim_xyz789",
  "status": "starting",
  "message": "Starting 2 nodes..."
}

​
Stop simulation

Stops all nodes but preserves their state. 
POST /api/v1/simulations/{id}/stop
Response: 
{
  "id": "sim_xyz789",
  "status": "stopping",
  "message": "Stopping 2 nodes..."
}

​
Delete simulation

Removes the simulation and all its nodes. This is permanent. 
DELETE /api/v1/simulations/{id}
Query parameters:
ParameterTypeDescription
forceboolForce delete even if running
Response: 
{
  "id": "sim_xyz789",
  "deleted": true
}

​
Create snapshot

Saves the current state of all nodes. 
POST /api/v1/simulations/{id}/snapshot
Content-Type: application/json
Request body: 
{
  "name": "before-database-migration",
  "description": "Snapshot before testing DB migration"
}
Response: 
{
  "id": "snap_111222",
  "simulation_id": "sim_xyz789",
  "name": "before-database-migration",
  "size_mb": 512,
  "created_at": "2026-01-26T11:00:00Z"
}

​
Restore from snapshot

Restores all nodes to a previous snapshot state. 
POST /api/v1/simulations/{id}/restore
Content-Type: application/json
Request body: 
{
  "snapshot_id": "snap_111222"
}
Response: 
{
  "id": "sim_xyz789",
  "status": "restoring",
  "snapshot_id": "snap_111222",
  "message": "Restoring 2 nodes from snapshot..."
}

​
Common patterns

# Create simulation with 3 nodes
curl -X POST http://localhost:5270/api/v1/simulations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ha-test",
    "nodes": [
      {"name": "node-1", "os": "ubuntu-22.04", "resources": {"cpu": 2, "memory": "2048Mi"}},
      {"name": "node-2", "os": "ubuntu-22.04", "resources": {"cpu": 2, "memory": "2048Mi"}},
      {"name": "node-3", "os": "ubuntu-22.04", "resources": {"cpu": 2, "memory": "2048Mi"}}
    ],
    "networks": [
      {"name": "cluster", "subnet": "172.20.0.0/24"}
    ]
  }'

# SSH into each node
ssh -p 30001 root@localhost  # node-1
ssh -p 30002 root@localhost  # node-2
ssh -p 30003 root@localhost  # node-3

SIM_ID="sim_xyz789"

# Create snapshot
curl -X POST "http://localhost:5270/api/v1/simulations/$SIM_ID/snapshot" \
  -H "Content-Type: application/json" \
  -d '{"name": "pre-change"}'

# Make your risky changes via SSH...

# 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_111222"}'

​
Next steps

Nodes API

Manage individual nodes

Templates

Pre-built simulation templates