mirror of
https://github.com/OpenRouterTeam/spawn.git
synced 2026-05-04 06:40:21 +00:00
793dee20ae
CloudSigma UX fixes: - Use log_error consistently for remediation hints (was log_warn) - Add "Common issues" block to create_server failure - Add actionable hints to server timeout error - Extract API error message instead of dumping raw response - Fix README: VNC password is random, not hardcoded RamNode README: - Update implemented agents list from 9 to all 15 Agent: ux-engineer Co-authored-by: A <6723574+louisgv@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# CloudSigma
|
|
|
|
Run AI agents on CloudSigma's flexible cloud infrastructure.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install spawn CLI
|
|
curl -fsSL https://spawn.sh | bash
|
|
|
|
# Run Claude Code on CloudSigma
|
|
spawn run cloudsigma/claude
|
|
|
|
# Or via direct script (one-liner)
|
|
bash <(curl -fsSL https://raw.githubusercontent.com/OpenRouterTeam/spawn/main/cloudsigma/claude.sh)
|
|
```
|
|
|
|
## Authentication
|
|
|
|
CloudSigma uses HTTP Basic Auth with email + password. The scripts will prompt you for credentials, or you can set them via environment variables:
|
|
|
|
```bash
|
|
export CLOUDSIGMA_EMAIL="your@email.com"
|
|
export CLOUDSIGMA_PASSWORD="your-password"
|
|
```
|
|
|
|
Credentials are saved to `~/.config/spawn/cloudsigma.json` for future use.
|
|
|
|
Get your credentials at: [CloudSigma Cloud Portal](https://zrh.cloudsigma.com/) (or wdc.cloudsigma.com / lvs.cloudsigma.com depending on region)
|
|
|
|
## Available Agents
|
|
|
|
- `cloudsigma/claude` — Claude Code (Anthropic's CLI agent)
|
|
- `cloudsigma/aider` — Aider (AI pair programming)
|
|
|
|
More coming soon! See `manifest.json` for the full matrix.
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
- `CLOUDSIGMA_EMAIL` — Your CloudSigma account email (required)
|
|
- `CLOUDSIGMA_PASSWORD` — Your CloudSigma account password (required)
|
|
- `CLOUDSIGMA_REGION` — Region code (default: `zrh`)
|
|
- `zrh` — Zurich, Switzerland
|
|
- `wdc` — Washington DC, USA
|
|
- `lvs` — Las Vegas, USA
|
|
- `CLOUDSIGMA_CPU_MHZ` — CPU allocation in MHz (default: `1000` = 1 GHz)
|
|
- `CLOUDSIGMA_MEMORY_GB` — Memory in GB (default: `2`)
|
|
- `CLOUDSIGMA_DISK_SIZE_GB` — Disk size in GB (default: `20`)
|
|
- `CLOUDSIGMA_SERVER_NAME` — Custom server name (default: prompts interactively)
|
|
- `OPENROUTER_API_KEY` — OpenRouter API key (prompts via OAuth if not set)
|
|
|
|
### Example: Custom Configuration
|
|
|
|
```bash
|
|
# Create a larger instance in Washington DC
|
|
export CLOUDSIGMA_REGION="wdc"
|
|
export CLOUDSIGMA_CPU_MHZ="2000"
|
|
export CLOUDSIGMA_MEMORY_GB="4"
|
|
export CLOUDSIGMA_DISK_SIZE_GB="40"
|
|
|
|
spawn run cloudsigma/claude
|
|
```
|
|
|
|
## Pricing
|
|
|
|
CloudSigma uses pay-as-you-go pricing with granular resource control. You only pay for the CPU, memory, and disk you allocate.
|
|
|
|
Example costs (as of 2026):
|
|
- Small instance (1 GHz CPU, 2GB RAM, 20GB SSD): ~$14/month
|
|
- Pricing varies by region and resource allocation
|
|
|
|
See [CloudSigma Pricing](https://www.cloudsigma.com/pricing/) for current rates.
|
|
|
|
## Architecture
|
|
|
|
CloudSigma is an API-first cloud platform with:
|
|
- **Granular resource control** — Configure CPU, RAM, and disk independently
|
|
- **Multiple regions** — ZRH (Zurich), WDC (Washington DC), LVS (Las Vegas)
|
|
- **API v2.0** — RESTful API with HTTP Basic Auth
|
|
- **Ubuntu 24.04** — Cloned from CloudSigma's public library images
|
|
- **SSH access** — Uses `cloudsigma` user (automatically configured via SSH key injection)
|
|
|
|
## How It Works
|
|
|
|
1. **Authentication** — Validates CloudSigma credentials via `/balance/` endpoint
|
|
2. **SSH key registration** — Uploads your `~/.ssh/id_ed25519.pub` to CloudSigma keypairs
|
|
3. **Drive creation** — Clones Ubuntu 24.04 from public library drives
|
|
4. **Server creation** — Creates a KVM server with specified CPU/RAM, attaches the drive
|
|
5. **Server start** — Powers on the server and waits for IP assignment
|
|
6. **Cloud-init** — Waits for Ubuntu's cloud-init to complete
|
|
7. **Agent installation** — Installs the selected agent (Claude Code, Aider, etc.)
|
|
8. **OpenRouter injection** — Configures API keys via environment variables
|
|
9. **Interactive session** — Drops you into SSH with the agent running
|
|
|
|
## Troubleshooting
|
|
|
|
### "Could not find Ubuntu 24.04 image"
|
|
CloudSigma library drives are region-specific. Ensure you're using a region where Ubuntu 24.04 is available (zrh, wdc, lvs all have it).
|
|
|
|
### "Authentication failed"
|
|
- Verify email/password at your region's portal (e.g., https://zrh.cloudsigma.com/)
|
|
- Check that your account is active and not suspended
|
|
- Ensure you're using the correct region (`CLOUDSIGMA_REGION`)
|
|
|
|
### "Server did not become ready"
|
|
CloudSigma servers typically start in 30-60 seconds. If timeout occurs:
|
|
- Check your account balance (insufficient funds can prevent server start)
|
|
- Try a different region
|
|
- Verify resource quotas in your CloudSigma dashboard
|
|
|
|
## Implementation Notes
|
|
|
|
- **User**: CloudSigma uses the `cloudsigma` user for SSH (not `root` or `ubuntu`)
|
|
- **API Version**: v2.0 (`https://{region}.cloudsigma.com/api/2.0/`)
|
|
- **Auth**: HTTP Basic Auth (Base64-encoded `email:password`)
|
|
- **Drive cloning**: Each server gets a fresh Ubuntu 24.04 clone (not shared)
|
|
- **Networking**: DHCP-based IPv4 with virtio NIC model
|
|
- **VNC**: Available via CloudSigma portal (random password generated per server)
|
|
|
|
## Resources
|
|
|
|
- [CloudSigma API Docs](https://docs.cloudsigma.com/)
|
|
- [CloudSigma Pricing](https://www.cloudsigma.com/pricing/)
|
|
- [CloudSigma Regions](https://www.cloudsigma.com/cloud-locations/)
|
|
- [Spawn Repository](https://github.com/OpenRouterTeam/spawn)
|