Agent Tooling

Deploy Application

Provision a VM, run a setup script, and optionally add CDN and DNS — all in one call.

Compute Sizes

Simplified size names that map to specific resource allocations:

Size	vCPU	RAM	Disk	Use Case
nano	1	1 GB	20 GB	Testing, small scripts
small	1	2 GB	40 GB	Simple apps, APIs
medium	2	4 GB	80 GB	Production apps
large	4	8 GB	160 GB	High-traffic apps
xlarge	8	16 GB	320 GB	Databases, heavy workloads

Request

POST /agent/deploy/app
Authorization: Bearer ea_live_...

{
  "project": "my-saas-app",
  "compute": {
    "os": "ubuntu-24.04",
    "size": "small",
    "region": "london",
    "setup_script": "#!/bin/bash\napt update && apt install -y docker.io\ndocker run -d -p 8080:8080 myapp:latest",
    "ssh_key": "ssh-ed25519 AAAA..."
  },
  "networking": {
    "firewall_rules": [
      { "port": 80, "protocol": "tcp" },
      { "port": 443, "protocol": "tcp" },
      { "port": 22, "protocol": "tcp", "source": "203.0.113.0/24" }
    ]
  },
  "domain": "app.example.com",
  "cdn": {
    "enabled": true
  }
}

Parameters

Field	Required	Description
project	Yes	Project name
compute.size	Yes	nano, small, medium, large, or xlarge
compute.os	No	Operating system. Default: ubuntu-24.04
compute.region	No	Deployment region. Default: london
compute.setup_script	No	Bash script to run on first boot via cloud-init
compute.ssh_key	No	SSH public key for access. Automatically created and attached to the VM.
networking.firewall_rules[]	No	Inbound firewall rules for the VM
networking.firewall_rules[].port	Yes (in rule)	Port number (e.g. 80, 443, 8080)
networking.firewall_rules[].protocol	No	tcp (default) or udp
networking.firewall_rules[].source	No	Source CIDR, default 0.0.0.0/0 (anywhere)
domain	No	Domain for the app
cdn.enabled	No	Place CDN in front of the VM

Firewall Rules

Firewall rules in the deploy request create a security group that is automatically attached to the VM. Each rule defines an inbound port, protocol, and optional source CIDR.

Agents can also manage security groups independently via the /agent/compute/firewall endpoints — create groups, attach them to VMs, or detach them as needed.

Available Endpoints

All compute endpoints available to agents:

Method	Endpoint	Description
GET	/agent/compute/vms	List VMs
GET	/agent/compute/vms/{id}	VM details with live metrics
GET	/agent/compute/os-templates	Available operating systems
GET	/agent/compute/regions	Available deployment regions
GET	/agent/compute/firewall	List security groups
GET	/agent/compute/firewall/{id}	Security group details
POST	/agent/compute/firewall	Create security group
POST	/agent/compute/vms/{id}/firewall/{groupId}	Attach security group
DELETE	/agent/compute/vms/{id}/firewall/{groupId}	Detach security group

Response

{
  "status": "provisioning",
  "project_id": "proj_b2c3d4e5f6a7",
  "vm": {
    "id": "vm_xyz789",
    "name": "my-saas-app",
    "status": "provisioning",
    "ip": "64.34.86.100",
    "specs": "1 vCPU, 2 GB RAM, 40 GB disk"
  },
  "resources_created": [
    { "type": "compute_vm", "id": "vm_xyz789", "name": "my-saas-app", "size": "small" },
    { "type": "cdn_deployment", "id": "dep_abc123" }
  ],
  "tell_user": "VM \"my-saas-app\" is being provisioned (small: 1 vCPU, 2GB RAM). IP: 64.34.86.100. Your setup script will run on first boot."
}

The VM starts in provisioning status. It typically takes 30-60 seconds to become running. Use the health check endpoint to monitor.

Health Check

Check the status of all resources in a project:

GET /agent/projects/proj_b2c3d4e5f6a7/health
Authorization: Bearer ea_live_...

# Response:
{
  "project": "my-saas-app",
  "overall_status": "healthy",
  "resources": [
    {
      "type": "compute",
      "id": "vm_xyz789",
      "name": "my-saas-app",
      "status": "running",
      "metrics": {
        "cpu_percent": 42,
        "ram_percent": 61,
        "disk_percent": 28
      }
    },
    {
      "type": "cdn",
      "id": "dep_abc123",
      "name": "my-saas-app-cdn",
      "status": "active",
      "domains": 1
    }
  ],
  "summary": { "total": 2, "healthy": 2, "issues": 0 },
  "tell_user": "Project \"my-saas-app\" is healthy. All 2 resources are running normally."
}

Scaling

Scale compute resources up or down:

POST /agent/projects/proj_b2c3d4e5f6a7/scale
Authorization: Bearer ea_live_...

{
  "compute": { "size": "medium" },
  "reason": "Traffic increased 3x this week, CPU consistently above 80%"
}

# Response:
{
  "project": "my-saas-app",
  "scaled": [
    { "resource": "vm_xyz789", "name": "my-saas-app", "scaled_to": "medium",
      "specs": { "vcpu": 2, "ram": 4, "disk": 80 } }
  ],
  "reason": "Traffic increased 3x this week, CPU consistently above 80%",
  "tell_user": "Scaled 1 resource in \"my-saas-app\" to medium."
}