Built for Agents

# Health check — no auth required
curl https://www.cloudworldmodel.ai/api/health
# → { "status": "ok", "version": "1.0.0", "uptime": 42.3 }

# Full OpenAPI spec as JSON
curl https://www.cloudworldmodel.ai/api-docs/openapi.json

# Interactive Swagger UI
open https://www.cloudworldmodel.ai/api-docs

# 1. Call any metered endpoint without an API key.
curl -X POST https://www.cloudworldmodel.ai/api/chaos/run \
  -H "Content-Type: application/json" \
  -d '{"simulationId":"<id>","scenario":"az_outage"}'
# → 402 Payment Required
# Body: { "error": "Payment required", "accepts": [{ "scheme": "exact",
#          "network": "base", "maxAmountRequired": "5000",
#          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#          "payTo": "<wallet>", ... }] }

# 2. Use an x402-aware client to pay and retry automatically.
#    The client signs a USDC transfer on Base, submits it to the
#    Coinbase facilitator, and retries with X-Payment in the header.
#    The server verifies the receipt and processes the request normally.

from x402.client import wrap_httpx_client
import httpx, os

# Wrap any httpx client — payments are handled transparently.
client = wrap_httpx_client(
    httpx.Client(),
    wallet_key=os.environ["AGENT_WALLET_PRIVATE_KEY"],
)

# Call the API exactly as you normally would — no API key header needed.
# If the server returns 402, the wrapper pays and retries automatically.
response = client.post(
    "https://www.cloudworldmodel.ai/api/simulations/<id>/step-hybrid",
    json={"trafficRPS": 1000},
)
data = response.json()
print(data["metrics"]["cpuUsage"])    # e.g. 0.71
print(data["metrics"]["latencyP95"])  # e.g. 138.4
print(data["metrics"]["costPerHour"]) # e.g. 0.096

import { wrapFetchWithPayment } from "x402/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_WALLET_PRIVATE_KEY as `0x${string}`);

// Wrap the global fetch — any 402 response triggers automatic payment + retry.
const payingFetch = wrapFetchWithPayment(fetch, account);

const res = await payingFetch(
  "https://www.cloudworldmodel.ai/api/chaos/run",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ simulationId: "<id>", scenario: "az_outage" }),
  }
);
const data = await res.json();
console.log(data); // same response shape as the authenticated API

npm install -g "github:canvascloudai/cwm-mcp"

{
  "mcpServers": {
    "cloud-world-model": {
      "command": "npx",
      "args": ["cwm-mcp"],
      "env": {
        "CWM_API_KEY": "your_api_key_here",
        "CWM_BASE_URL": "https://www.cloudworldmodel.ai"
      }
    }
  }
}

pip install "git+https://github.com/canvascloudai/cwm-sdk.git"

from cwm import CloudWorldModel

client = CloudWorldModel(
    base_url="https://www.cloudworldmodel.ai",
    api_key="your_api_key_here",
)

# 1. Create a simulation
sim = client.create_simulation({
    "name": "prod-replica",
    "resources": [
        {
            "id": "web",
            "type": "compute",
            "name": "Web Server",
            "provider": "aws",
            "characteristics": {"size": "t3.medium"},
        }
    ],
})

# 2. Run a simulation step
result = client.simulate_step(sim["id"], traffic=1500)
m = result["metrics"]
print(m["cpuUsage"])      # e.g. 0.72
print(m["latencyP95"])    # e.g. 143.2
print(m["costPerHour"])   # e.g. 0.0464

from cwm import CloudWorldModel

client = CloudWorldModel(
    base_url="https://www.cloudworldmodel.ai/api",
    api_key="your_api_key_here",
)

# 1. Create an RL environment linked to a simulation that already contains
#    at least one AWS database resource (the engine clones it for the episode).
env_result = client.create_rl_environment(
    simulation_id="<sim-id>",
    episode_config={"maxSteps": 40},
)
env_id = env_result["environment"]["id"]

# 2. add_resource action — adds an Aurora Serverless v2 database to the sim.
#    The engine models a 2-4 step ACU scale-out delay for aurora-serverless targets.
step1 = client.rl_step(env_id, action={
    "type": "add_resource",
    "parameters": {"resourceType": "database", "provider": "aws"},
})
# Response keys: observation, reward {total, components, metrics}, done, info
obs    = step1["observation"]   # {cpu_util, rps, instances, traffic, currentTime}
reward = step1["reward"]        # {total, components: {performance, cost, stability, sla, connection_pressure?}, metrics}

# 3. Ramp window (steps 1-4): ACU warming up — cpu_util == 0, cost at minCapacity floor.
#    Only count cost + stability reward components to avoid false latency penalties.
result = step1
for _ in range(4):
    result = client.rl_step(env_id, action={
        "type": "adjust_threshold",
        "parameters": {"cpuThreshold": 70},
    })
    obs        = result["observation"]
    rc         = result["reward"]["components"]
    adj_reward = rc["cost"] + rc["stability"]
    print(f"Ramp  cpu_util={obs['cpu_util']:.3f}  adj_reward={adj_reward:.3f}")

# 4. Steady-state training loop — all reward components now meaningful. With a database
#    resource present this is five (performance, cost, stability, sla, connection_pressure).
done = result["done"]
while not done:
    result = client.rl_step(env_id, action={
        "type": "adjust_threshold",
        "parameters": {"cpuThreshold": 70},
    })
    done = result["done"]
    obs  = result["observation"]
    rw   = result["reward"]
    print(f"Train cpu_util={obs['cpu_util']:.3f}  "
          f"cost_usd_hr={rw['metrics']['costPerHour']:.4f}  "
          f"reward={rw['total']:.3f}")

# 5. Reset for the next episode.
client.rl_reset(env_id)

from cwm import CloudWorldModel

client = CloudWorldModel(
    base_url="https://www.cloudworldmodel.ai/api",
    api_key="your_api_key_here",
)

# Create a simulation with a Kubernetes node pool and bound its autoscaling.
sim = client.create_simulation({
    "name": "k8s-cluster",
    "resources": [
        {
            "id": "api-pool",
            "type": "kubernetes",
            "name": "API Node Pool",
            "provider": "aws",  # EKS (also gcp=GKE, azure=AKS, oci=OKE, digitalocean=DOKS)
            "characteristics": {
                "nodeCount": 3,        # worker nodes to start with
                "minNodes": 2,         # autoscaler won't scale below this
                "maxNodes": 10,        # autoscaler won't scale above this
                "maxThroughput": 6000, # serving capacity (RPS) at nodeCount
            },
        }
    ],
})

# /step autoscales nodeCount between minNodes and maxNodes; maxThroughput
# and hourly cost scale proportionally with the live node count.
result = client.simulate_step(sim["id"], traffic=4000)
print(result["metrics"]["cpuUsage"])    # e.g. 0.68
print(result["metrics"]["costPerHour"]) # scales with current nodeCount

npm install "github:canvascloudai/cwm-ts-sdk"

import { CwmClient } from "@cwm/sdk";

const client = new CwmClient({
  baseUrl: "https://www.cloudworldmodel.ai",
  apiKey: "your_api_key_here",
});

// 1. Create a simulation
const sim = await client.createSimulation({
  name: "prod-replica",
  resources: [
    {
      id: "web",
      type: "compute",
      name: "Web Server",
      provider: "aws",
      characteristics: { size: "t3.medium" },
    },
  ],
});

// 2. Run a simulation step and read metrics
const result = await client.simulateStep(sim.id, { traffic: 1500 });
console.log(result.metrics.cpuUsage);    // e.g. 0.72
console.log(result.metrics.latencyP95); // e.g. 143.2
console.log(result.metrics.costPerHour); // e.g. 0.0464

import { CwmClient } from "@cwm/sdk";

const client = new CwmClient({
  baseUrl: "https://www.cloudworldmodel.ai/api",
  apiKey: "your_api_key_here",
});

// 1. Create an RL environment linked to a simulation that already contains
//    at least one AWS database resource (the engine clones it for the episode).
const { environment } = await client.createRlEnvironment("<sim-id>", {
  episodeConfig: { maxSteps: 40 },
});
const envId = environment.id;

// 2. add_resource action — adds an Aurora Serverless v2 database to the sim.
//    The engine models a 2-4 step ACU scale-out delay for aurora-serverless targets.
let step1 = await client.rlStep(envId, {
  action: { type: "add_resource", parameters: { resourceType: "database", provider: "aws" } },
  tick_seconds: 60,
});
// Response keys: t, obs, metrics, reward, reward_components, done
let { t, obs, metrics } = step1;  // t=1 after first action
// obs: {cpu_util, rps, instances, traffic, currentTime}
// metrics: {cost_usd_hr, latency_p95, error_rate, uptime, sla_violations}

// 3. Ramp window (t = 1-4): obs.cpu_util === 0, metrics.cost_usd_hr at minCapacity floor (~$0.06/hr).
//    Only count cost + stability reward components — skip performance and sla during ACU ramp-up.
const RAMP_STEPS = 4;
let result = step1;
for (let i = 0; i < RAMP_STEPS; i++) {
  result = await client.rlStep(envId, {
    action: { type: "adjust_threshold", parameters: { cpuThreshold: 70 } },
    tick_seconds: 60,
  });
  ({ t, obs, metrics } = result);
  const rc = result.reward_components;
  const adjustedReward = rc.cost + rc.stability;
  console.log(`Ramp  t=${String(t).padStart(2)}  cpu_util=${obs.cpu_util.toFixed(3)}  ` +
              `cost_usd_hr=${metrics.cost_usd_hr.toFixed(4)}  adj_reward=${adjustedReward.toFixed(3)}`);
}

// 4. Steady-state training loop — all reward components are now meaningful. With a database
//    resource present this is five components — performance, cost, stability, sla, and the
//    connection_pressure DB-pool penalty (see the worked connection-pool example below).
//    metrics.cost_usd_hr climbs over 3-6 steps toward the ACU-proportional steady-state rate.
let done = result.done;
while (!done) {
  result = await client.rlStep(envId, {
    action: { type: "adjust_threshold", parameters: { cpuThreshold: 70 } },
    tick_seconds: 60,
  });
  ({ t, obs, metrics } = result);
  const reward = result.reward;
  done = result.done;
  console.log(`Train t=${String(t).padStart(2)}  cpu_util=${obs.cpu_util.toFixed(3)}  ` +
              `latency_p95=${metrics.latency_p95.toFixed(0)}ms  ` +
              `cost_usd_hr=${metrics.cost_usd_hr.toFixed(4)}  reward=${reward.toFixed(3)}`);
}

// 5. Reset for the next episode.
await client.rlReset(envId);

import { CwmClient } from "@cwm/sdk";

const client = new CwmClient({
  baseUrl: "https://www.cloudworldmodel.ai/api",
  apiKey: "your_api_key_here",
});

// Create a simulation with a Kubernetes node pool and bound its autoscaling.
const sim = await client.createSimulation({
  name: "k8s-cluster",
  resources: [
    {
      id: "api-pool",
      type: "kubernetes",
      name: "API Node Pool",
      provider: "aws", // EKS (also gcp=GKE, azure=AKS, oci=OKE, digitalocean=DOKS)
      characteristics: {
        nodeCount: 3,        // worker nodes to start with
        minNodes: 2,         // autoscaler won't scale below this
        maxNodes: 10,        // autoscaler won't scale above this
        maxThroughput: 6000, // serving capacity (RPS) at nodeCount
      },
    },
  ],
});

// /step autoscales nodeCount between minNodes and maxNodes; maxThroughput
// and hourly cost scale proportionally with the live node count.
const result = await client.simulateStep(sim.id, { traffic: 4000 });
console.log(result.metrics.cpuUsage);    // e.g. 0.68
console.log(result.metrics.costPerHour); // scales with current nodeCount

go get github.com/canvascloudai/cwm-go

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/canvascloudai/cwm-go/cwm"
)

func main() {
	client := cwm.New("https://www.cloudworldmodel.ai", "your_api_key_here")
	ctx := context.Background()

	// 1. Create a simulation
	sim, err := client.CreateSimulation(ctx, map[string]interface{}{
		"name": "prod-replica",
		"resources": []map[string]interface{}{
			{
				"id": "web", "type": "compute",
				"name": "Web Server", "provider": "aws",
				"characteristics": map[string]interface{}{"size": "t3.medium"},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	// 2. Simulate a step and read metrics (cwm.Float64(rps) sets traffic; nil keeps current)
	result, err := client.SimulateStep(ctx, sim.ID, cwm.Float64(1500), false)
	if err != nil {
		log.Fatal(err)
	}
	m := result.Metrics
	fmt.Printf("CPU: %.1f%%  P95: %.1fms  Cost: $%.4f/hr\n",
		m.CPUUsage*100, m.LatencyP95, m.CostPerHour)
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/canvascloudai/cwm-go/cwm"
)

func main() {
	client := cwm.New("https://www.cloudworldmodel.ai", "your_api_key_here")
	ctx := context.Background()

	sim, _ := client.CreateSimulation(ctx, map[string]interface{}{
		"name":      "rl-training",
		"resources": []map[string]interface{}{
			{"id": "web", "type": "compute", "name": "Web Server", "provider": "aws"},
		},
	})

	env, err := client.CreateRLEnvironment(ctx, sim.ID, &cwm.RlEpisodeConfig{
		MaxSteps:       100,
		InitialTraffic: 1000,
	})
	if err != nil {
		log.Fatal(err)
	}
	envID := env.Environment.ID

	for episode := 1; episode <= 5; episode++ {
		if episode > 1 {
			client.RLReset(ctx, envID)
		}
		var totalReward float64
		for step := 0; step < 100; step++ {
			res, err := client.RLStep(ctx, envID, cwm.RlAction{Type: "scale_out"})
			if err != nil {
				log.Fatal(err)
			}
			totalReward += res.Reward.Total
			if res.Done {
				break
			}
		}
		fmt.Printf("Episode %d  total_reward=%.3f\n", episode, totalReward)
	}
	client.DeleteSimulation(ctx, sim.ID)
}

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"os"

	// Install: go get github.com/coinbase/x402-go
	x402 "github.com/coinbase/x402-go/pkg/httpclient"
)

func main() {
	// Wrap the stdlib http.Client — any 402 response triggers automatic
	// USDC payment on Base mainnet and transparent retry. No API key needed.
	client, err := x402.New(os.Getenv("AGENT_WALLET_PRIVATE_KEY"),
		x402.WithFacilitator("https://x402.org/facilitator"),
	)
	if err != nil {
		log.Fatal(err)
	}

	body, _ := json.Marshal(map[string]any{"trafficRPS": 1000})
	resp, err := client.Post(
		"https://www.cloudworldmodel.ai/api/simulations/<id>/step-hybrid",
		"application/json",
		bytes.NewReader(body),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var result map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	m := result["metrics"].(map[string]any)
	fmt.Printf("CPU: %.1f%%  P95: %.1fms  Cost: $%.4f/hr\n",
		m["cpuUsage"].(float64)*100,
		m["latencyP95"].(float64),
		m["costPerHour"].(float64),
	)
}

# Install globally from GitHub
npm install -g "github:canvascloudai/cwm-cli"

# Verify
cwm --help

Usage: cwm <command> [options]

Commands:
  config      Manage CLI configuration (set, show)
  simulate    Simulation management (create, get, list, step)
  rl          RL environment interactions (create, step, reset)
  chaos       Chaos engineering (scenarios, run, status, results)
  multicloud  Strategy exploration (explore, status, results)
  keys        API key management (create, list, revoke)

Options:
  --base-url <url>   CWM server URL (overrides config)
  --api-key <key>    API key (overrides config)
  --output <format>  Output format: text | json
  -h, --help         Display help for a command

# 0. Save your key once; the CLI reads it automatically from ~/.cwm/config.json.
cwm config set --api-key your_api_key_here

# 1. Create an RL environment linked to a simulation that already contains
#    at least one AWS database resource (the engine clones it for the episode).
ENV_ID=$(cwm rl create <sim-id> --max-steps 40 --output json | jq -r '.environment.id')

# 2. add_resource action — adds an Aurora Serverless v2 database to the sim.
#    cwm rl step passes no action parameters, so use curl for this parameterized step.
#    The engine models a 2-4 step ACU scale-out delay for aurora-serverless targets.
curl -s -X POST https://www.cloudworldmodel.ai/api/rl/environments/$ENV_ID/step \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":{"type":"add_resource","parameters":{"resourceType":"database","provider":"aws"}}}' \
  | jq '{obs: .obs, reward: .reward, done: .done}'
# Response keys: obs {cpu_util, rps, instances, traffic, currentTime},
#                reward (total scalar), reward_components {performance,cost,stability,sla,connection_pressure?},
#                metrics {cost_usd_hr, latency_p95, error_rate}, done

# 3. Ramp window (steps 1-4): ACU warming up — obs.cpu_util == 0, cost at minCapacity floor.
#    Only cost + stability reward components are meaningful during ACU ramp-up.
for i in 1 2 3 4; do
  cwm rl step $ENV_ID adjust_threshold --output json \
    | jq '{cpu_util: .obs.cpu_util, adj_reward: (.reward_components.cost + .reward_components.stability)}'
done

# 4. Steady-state training loop — all reward components are now meaningful. With a database
#    resource present this is five (performance, cost, stability, sla, connection_pressure).
#    Loop until the episode is done (done == true in the JSON response).
while true; do
  RESULT=$(cwm rl step $ENV_ID adjust_threshold --output json)
  echo "$RESULT" | jq '{cpu_util: .obs.cpu_util, cost_usd_hr: .metrics.cost_usd_hr, reward: .reward}'
  DONE=$(echo "$RESULT" | jq -r '.done')
  [ "$DONE" = "true" ] && break
done

# 5. Reset for the next episode.
cwm rl reset $ENV_ID