Skip to main content

​
Getting Started Guide

Plato Hub makes it easy to develop and manage simulators. This guide will walk you through cloning your first simulator and setting up a development environment.

​
Overview

With Plato Hub, you can:
  • Clone existing simulators to your local machine
  • Develop in isolated environments with full Docker support
  • Test changes in real-time with live reloading
  • Deploy changes with automatic versioning

​
Installation

First, install the Plato SDK for your platform: 
uv init

# macOS Silicon (M1/M2/M3)
uv add plato-sdk==1.0.95.dev20251027235103

# macOS Intel
uv add plato-sdk==1.0.95.dev20251027235111

# Linux AMD64
uv add plato-sdk==1.0.95.dev20251027235232

​
Your First Simulator

Let’s clone and run an existing simulator to see how everything works.
1

Clone a Simulator

Clone an existing simulator (we’ll use espocrm as an example):
uv run plato hub clone espocrm
This creates a local directory with the simulator code and sets up git remote configuration.You can explore available hub commands:
uv run plato hub
2

Navigate to Simulator

Enter the cloned simulator directory:
cd espocrm
You’ll find the simulator’s source code, configuration files, and documentation.
3

Check Configuration

Look at the simulator configuration:
cat plato-config.yml
This file defines compute resources, datasets, and entrypoints for the simulator.

​
Understanding the Structure

A typical Plato simulator has this structure: 
espocrm/
├── plato-config.yml          # VM and dataset configuration
├── datasets/
│   └── base/
│       └── docker-compose.yml   # Main application services  
├── src/
│   └── espocrm/
│       └── env.py           # Mutation listeners and environment setup
└── .plato-hub.json          # Hub configuration (auto-generated)

​
Key Files

plato-config.yml

Defines compute resources, datasets, and how services start up

docker-compose.yml

Defines your application services (database, web app, etc.)

env.py

Configures mutation listeners for tracking database changes

.plato-hub.json

Links your local directory to the remote simulator repository

​
Configuration Structure

The plato-config.yml file defines how your simulator runs:
plato-config.yml
service: espocrm  # Service name for this simulator

datasets:
  base: &base  # YAML anchor for reusing configuration
    compute: &base_compute
      cpus: 1                    # Number of vCPUs allocated to VM
      memory: 3072               # Memory in MB
      disk: 10240                # Disk space in MB
      app_port: 80               # Main application port
      plato_messaging_port: 7000 # Port for Plato worker (keep unless conflicting with an app port)

    metadata: &base_metadata
      name: EspoCRM
      description: EspoCRM Simulator
      source_code_url: https://github.com/espocrm/espocrm
      start_url: https://sims.plato.so     # URL to access the running app
      license: GPL-3.0
      variables:                  # Login credentials for the simulator
        - name: username
          value: admin
        - name: password
          value: password
      flows_path: base/flows.yaml     # Path to action flow definitions

    services: &base_services
      main_app:                       # Identifier for this service
        type: docker-compose
        file: base/docker-compose.yml
        healthy_wait_timeout: 600     # Max seconds to wait for containers
        required_healthy_containers:  # Containers that must be healthy
          - espocrm                   # Container name from docker-compose.yml

    listeners: &base_listeners
      db:                             # Identifier for this listener
        type: db                      # Listener type
        db_type: postgresql           # postgresql, mysql, or sqlite
        db_host: 127.0.0.1
        db_port: 5432
        db_user: espocrm
        db_password: espocrm
        db_database: espocrm
        volumes:                      # Volume mounts for signal exchange
          - /home/plato/db_signals:/tmp/postgres-signals
          # Format: <vm_path>:<container_path>[:ro|rw]
          # Add more volumes as needed for your application

​
Next Steps

Now that you have a simulator cloned locally, you can:
Each simulator can have multiple datasets (like base, test-data, production-copy) with different configurations and data sets.