--- title: "Deploy Application" description: "Deploy a VM-based application with one API call. Provisions compute, runs setup scripts, and optionally configures CDN and DNS." url: https://edge.network/docs/agent/deploy-app/ --- # Deploy Application 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 string (e.g. `ssh-ed25519 AAAA...`). Auto-creates a key on the account and attaches it. Connect afterwards with `ssh root@ `. | | compute.ssh_key_ids | No | IDs of existing SSH keys (from `/agent/compute/ssh-keys`) to attach. | | 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. New VMs have no firewall by default — all ports are open. If you attach a custom security group, make sure it includes an inbound rule for **tcp/22** or you will lock yourself out of SSH. ## SSH Access Every Edge VM uses `root` as the default SSH user (regardless of OS). Connect with `ssh root@ ` using a private key whose public counterpart is attached to the VM. ### At creation time (preferred) Pass the user's public key as `compute.ssh_key`, or attach pre-saved keys via `compute.ssh_key_ids`. The key is baked in via cloud-init at first boot. ### After creation If the VM already exists, **do not recreate it**. Save the key on the account, then attach it to the running VM — Edge pushes the key into `authorized_keys` via the guest agent within ~10 seconds. ``` # 1. Save the user's public key on the account POST /agent/compute/ssh-keys Authorization: Bearer ea_live_... { "name": "alice-laptop", "public_key": "ssh-ed25519 AAAA... alice@laptop" } # Response: { "ssh_key": { "id": "key_abc123", "name": "alice-laptop", "fingerprint": "SHA256:..." }, "next_steps": [ "Pass this key ID in compute.ssh_key_ids when creating a VM, OR", "Attach to an existing VM with: POST /agent/compute/vms/{vmId}/ssh-keys/key_abc123" ] } # 2. Attach the key to the existing VM (no need to recreate it) POST /agent/compute/vms/vm_xyz789/ssh-keys/key_abc123 Authorization: Bearer ea_live_... # Response: { "attached": true, "vm_id": "vm_xyz789", "ssh_key_id": "key_abc123", "ssh": { "user": "root", "host": "64.34.86.100", "command": "ssh root@64.34.86.100", "note": "Wait ~10s for guest-agent push, then connect with your matching private key." }, "tell_user": "SSH key attached to VM \"my-saas-app\". Key is being pushed to the running VM via the guest agent (typically <10s). Connect with: ssh root@64.34.86.100" } ``` ### Connection timing - VM provisioning: ~30-60 seconds until `vm.status === "running"` - Key propagation on first boot: an additional ~30-90 seconds - Key push to a running VM (guest-agent path): ~10 seconds - Poll `GET /agent/compute/vms/{id}` — the response includes a ready-to-use `ssh.command` field once the VM is connectable ### If the user has no SSH key yet Have them generate one locally — the private key never leaves their machine: ``` ssh-keygen -t ed25519 -C "edge-network" cat ~/.ssh/id_ed25519.pub # paste this into ssh_key ``` ### SSH endpoints | Method | Endpoint | Description | | GET | /agent/compute/ssh-keys | List SSH keys on the account | | POST | /agent/compute/ssh-keys | Save a public key on the account (returns keyId) | | DELETE | /agent/compute/ssh-keys/{id} | Delete a key from the account (must be detached first) | | GET | /agent/compute/vms/{id}/ssh-keys | List keys attached to a specific VM | | POST | /agent/compute/vms/{id}/ssh-keys/{keyId} | Attach an existing key to a VM (works on running VMs) | | DELETE | /agent/compute/vms/{id}/ssh-keys/{keyId} | Detach a key (removes from authorized_keys on running VMs) | ## 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/ssh-keys | List SSH keys | | POST | /agent/compute/ssh-keys | Save an SSH public key | | POST | /agent/compute/vms/{id}/ssh-keys/{keyId} | Attach SSH key to existing VM | | DELETE | /agent/compute/vms/{id}/ssh-keys/{keyId} | Detach SSH key from VM | | 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" }, "ssh": { "user": "root", "host": "64.34.86.100", "command": "ssh root@64.34.86.100", "ready": false, "note": "Wait until vm.status is \"running\" (~30-60s) and key propagation completes (~30-90s on first boot)." }, "next_steps": [ "Poll: GET /agent/compute/vms/vm_xyz789 until vm.status === \"running\"", "Then connect: ssh root@64.34.86.100" ], "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. SSH ready once status is \"running\". Connect: ssh root@64.34.86.100." } ``` 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." } ``` ## See Also [Deploy Static Site Deploy a static website in one call](https://edge.network/docs/agent/deploy-static-site) [Projects Health checks, scaling, and teardown](https://edge.network/docs/agent/projects) [Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)