cloudsim 1.0.1

Local-first cloud infrastructure simulator (Flask API + CLI).

CloudSim

CloudSim is a local-first cloud infrastructure simulator (Flask API + CLI) designed to teach you how the cloud works.

---

Cloud Architect Academy

Want to learn the cloud step-by-step? We've built a premium interactive course website just for you.

---

Install

PyPI (normal)

pip install cloudsim

TestPyPI (testing)

TestPyPI does not mirror all dependencies, so include the real PyPI index for dependencies:

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple cloudsim==1.0.2

Configuration (.env)

Fastest setup:

cloudsim config init --workspace ./cloudsim-workspace
cloudsim config show

# Start API
cloudsim-server

cloudsim config init writes:

• <workspace>/.env (your environment config)
• ~/.cloudsim/config.json (default workspace pointer, so you can run cloudsim from any folder)

If you do not want a global default workspace file, use:

cloudsim config init --workspace ./cloudsim-workspace --no-default

CloudSim reads environment variables from a workspace .env file:

• <workspace>/.env

If you installed via pip, an example file is also included inside the installed package at cloudsim/.env.example. To print its path:

python -c "import cloudsim; from pathlib import Path; print(Path(cloudsim.__file__).resolve().parent / '.env.example')"

Quick start (PowerShell):

$env:CLOUDSIM_WORKSPACE = "E:\\codex\\cloudsim-workspace"
New-Item -ItemType Directory -Force $env:CLOUDSIM_WORKSPACE | Out-Null
Copy-Item .\\.env.example "$env:CLOUDSIM_WORKSPACE\\.env"

Quick start (macOS/Linux):

export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"
mkdir -p "$CLOUDSIM_WORKSPACE"
cp ./.env.example "$CLOUDSIM_WORKSPACE/.env"

PostgreSQL (optional, for "real" Cloud SQL):

• CLOUDSIM_PG_HOST=127.0.0.1
• CLOUDSIM_PG_PORT=5432
• CLOUDSIM_PG_ADMIN_USER=postgres
• CLOUDSIM_PG_ADMIN_PASSWORD=pg123
• CLOUDSIM_PG_ADMIN_DB=postgres

If these are not set (or Postgres is not reachable), CloudSim continues to work using per-VM SQLite by default.

Workspace (Where VMs/DBs Are Created)

CloudSim writes runtime state into a workspace directory (not inside the installed package directory).

Workspace resolution order:

1. CLOUDSIM_WORKSPACE
2. ~/.cloudsim/config.json (workspace) (created by cloudsim config init)
3. current working directory

Windows (PowerShell):

$env:CLOUDSIM_WORKSPACE = "E:\codex\cloudsim-workspace"

macOS/Linux:

export CLOUDSIM_WORKSPACE="$HOME/cloudsim-workspace"

Files created in the workspace:

• <workspace>/.cloudsim/simulation.db (global state)
• <workspace>/.cloudsim/sql_service.db (simulated Cloud SQL accounts/tenancy)
• <workspace>/vms/<vmId>/vm_state.db (per-VM state snapshot)
• <workspace>/vms/<vmId>/vm_sqlite.db (per-VM SQLite database)
• <workspace>/autoscale-vms/<vmId>/... (autoscaled VMs)

Start Backend API

python -m cloudsim.app

Default API base URL: http://127.0.0.1:5000

CLI: Run Globally Or Inside A VM Shell

There are two common ways to use CloudSim CLI:

A) Global CLI (works immediately, no PATH changes)

python -m cloudsim.cli_services.runtime --help
python -m cloudsim.cli_services.runtime health

B) Direct cloudsim command (global install)

pip install cloudsim installs a launcher (cloudsim / cloudsim.exe) into your Python scripts folder. You can run cloudsim directly only if that scripts folder is on your PATH.

Windows: find user-base

python -m site --user-base

Add <user-base>\Scripts to PATH, open a new terminal, then:

cloudsim --help

macOS/Linux: find user-base

python -m site --user-base

Add <user-base>/bin to PATH, open a new terminal, then:

cloudsim --help

Example paths:

• Windows (Microsoft Store Python): C:\Users\CHIRAG\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\Scripts
• Windows (python.org installer, common): C:\Users\CHIRAG\AppData\Roaming\Python\Python313\Scripts
• macOS/Linux (common): $HOME/.local/bin

C) Direct cloudsim command (virtualenv)

Activating a venv automatically adds its scripts folder to PATH, so cloudsim works inside that venv.

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
cloudsim --help

Windows (cmd):

python -m venv .venv
.\.venv\Scripts\activate.bat
cloudsim --help

macOS/Linux:

python -m venv .venv
source .venv/bin/activate
cloudsim --help

VM Shell (cloudsim ssh)

cloudsim ssh <vmId> opens a VM workspace shell and sets VM context variables:

• CLOUDSIM_IN_VM_SHELL=1
• CLOUDSIM_VM_ID=<vmId>
• CLOUDSIM_VM_SPACE=vm_<vmId>

From inside the VM shell, per-VM commands can auto-target that VM (example: per-VM SQLite).

Create A VM

python -m cloudsim.cli_services.runtime vm create \
  --name vm1 \
  --region us-central1 \
  --machine-type e2-micro \
  --image "Ubuntu 22.04 LTS" \
  --backend-profile-id python-fastapi

Per-VM SQLite (Default "Cloud SQL" Fallback)

python -m cloudsim.cli_services.runtime sql provision --vm-id <vmId>
python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "CREATE TABLE items(id INTEGER PRIMARY KEY, name TEXT)"
python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "INSERT INTO items(name) VALUES (?)" --params-json '["alpha"]'
python -m cloudsim.cli_services.runtime sql execute --vm-id <vmId> --mode local --query "SELECT id,name FROM items"

Load Balancer + Traffic Simulation

python -m cloudsim.cli_services.runtime lb create --name lb1 --type HTTP(S) --region global --backend-vm-id <vmId>
python -m cloudsim.cli_services.runtime simulate --lb-id <lbId> --endpoint-key "GET /health" --requests 500

Autoscale Demo

python -m cloudsim.cli_services.runtime autoscale-test --requests 1000 --max-instances 5

Real PostgreSQL (Optional)

Set these env vars (or use <workspace>/.env) before starting the backend:

• CLOUDSIM_PG_HOST=...
• CLOUDSIM_PG_PORT=...
• CLOUDSIM_PG_ADMIN_USER=...
• CLOUDSIM_PG_ADMIN_PASSWORD=...
• CLOUDSIM_PG_ADMIN_DB=...

Then:

python -m cloudsim.cli_services.runtime sql real-status
python -m cloudsim.cli_services.runtime sql real-provision --vm-id <vmId>
python -m cloudsim.cli_services.runtime sql real-connect --vm-id <vmId>

License

MIT (see LICENSE).