# RepoCloud

> Deploy and manage Ubuntu 24.04 VPS instances programmatically. Provision a bare server with root SSH access, install anything, configure SSL on the provided domain, and tear down when done. Works via MCP protocol or direct REST API.

Authentication uses Bearer tokens. Obtain an API key (prefixed `rcmcp_`) from https://repocloud.io/mcp after making a minimum $1 deposit. Pass the key as `Authorization: Bearer <key>` on every request.

Account balance must exceed $3 to deploy. Billing is hourly from provision time. Stopped instances bill at a reduced rate. Billing stops when an instance is destroyed.

## Documentation

- [API Reference](https://docs.repocloud.io/api/introduction): Full REST API documentation with examples
- [OpenAPI Spec](https://repocloud.io/api/v1/openapi.json): Machine-readable OpenAPI 3.1.0 specification
- [User Guide](https://docs.repocloud.io/user-guide/introduction): Platform overview and getting started

## API

- [POST /api/v1/instances](https://repocloud.io/api/v1/openapi.json): Deploy a new Ubuntu VPS. Body: `{"project_name": "my-app", "flavor": "s-2vcpu-2gb"}`
- [GET /api/v1/instances](https://repocloud.io/api/v1/openapi.json): List all API-created instances with status, IP, and credentials
- [GET /api/v1/instances/{id}](https://repocloud.io/api/v1/openapi.json): Get instance details including SSH credentials when active
- [POST /api/v1/instances/{id}/actions](https://repocloud.io/api/v1/openapi.json): Power on, power off, reboot, or resize. Body: `{"action": "power_on"}`
- [DELETE /api/v1/instances/{id}](https://repocloud.io/api/v1/openapi.json): Permanently destroy an instance and release all resources

Base URL: `https://repocloud.io/api/v1`

## MCP

- [MCP Server](https://mcp.repocloud.io/mcp): Streamable HTTP transport, auto-discoverable tools

### Tools

| Tool | Purpose |
|------|---------|
| `provision_ubuntu_vps` | Create a fresh Ubuntu 24.04 VPS. Args: `project_name` (required), `flavor` (default s-2vcpu-2gb), `ssh_public_key` (optional) |
| `get_instance_status` | Poll status and retrieve credentials when active. Args: `instance_id` |
| `list_instances` | List all API-created instances (no args) |
| `manage_instance` | Power on/off, reboot, resize. Args: `instance_id`, `action`, `flavor` (for resize only) |
| `destroy_instance` | Permanently delete an instance. Args: `instance_id`, `confirm` (must be true) |

### Connection Examples

Cursor (`.cursor/mcp.json`):
```json
{"mcpServers": {"repocloud": {"url": "https://mcp.repocloud.io/mcp", "headers": {"Authorization": "Bearer YOUR_KEY"}}}}
```

Claude Code:
```
claude mcp add repocloud --transport streamable-http --header "Authorization: Bearer YOUR_KEY" https://mcp.repocloud.io/mcp
```

## Deployment Workflow

1. Provision: call `provision_ubuntu_vps(project_name, flavor)` or `POST /api/v1/instances`
2. Poll: call `get_instance_status(instance_id)` or `GET /api/v1/instances/{id}` until status is `active` (typically 20-40 seconds)
3. Connect: SSH as root using the returned `ipv4` and `root_password` (or your SSH key)
4. Deploy: install your application — the VPS is clean Ubuntu 24.04 with Python 3.12 pre-installed
5. SSL: use certbot with the provided domain (`*.vps.rcld.dev`, A record pre-configured)
6. Destroy: call `destroy_instance(instance_id, confirm=true)` or `DELETE /api/v1/instances/{id}`

## Available Tiers

| Flavor | vCPU | RAM | Disk | Hourly | ~Monthly |
|--------|------|-----|------|--------|----------|
| s-1vcpu-2gb | 1 | 2 GB | 30 GB | $0.0083 | $6 |
| s-2vcpu-2gb | 2 | 2 GB | 40 GB | $0.0125 | $9 |
| s-2vcpu-4gb | 2 | 4 GB | 40 GB | $0.0167 | $12 |
| s-4vcpu-8gb | 4 | 8 GB | 80 GB | $0.0333 | $24 |
| s-8vcpu-16gb | 8 | 16 GB | 160 GB | $0.0667 | $49 |
| s-16vcpu-32gb | 16 | 32 GB | 320 GB | $0.1333 | $97 |

RAM guidance: packages with large dependency trees (Flowise, Supabase, n8n) require at least s-4vcpu-8gb (8 GB RAM). The s-2vcpu-4gb tier may OOM during heavy npm installs.

## Status Values

| Status | Meaning | Action |
|--------|---------|--------|
| `pending` | Queued, waiting to be scheduled | Wait |
| `provisioning` | VM is being created | Wait |
| `active` | Running, SSH available | Connect and deploy |
| `stopped` | Powered off | `manage_instance(action="power_on")` |
| `failed` | Terminal failure | Destroy and recreate |

## Important Notes

- Resize only scales UP (disk cannot shrink)
- Only API-created instances appear in `list_instances`
- Each VPS receives a domain like `vps-XXXXXXXX.vps.rcld.dev` with a pre-configured A record
- SSH keys are auto-generated if no `ssh_public_key` is provided
- The `manage_instance` action field accepts: `power_on`, `power_off`, `reboot`, `resize`

## Optional

- [Agent Skill File](https://mcp.repocloud.io/SKILL.md): Portable prompt file for agents without MCP support
- [Platform Status](https://status.repocloud.io): Service availability and incidents
- [Pricing](https://repocloud.io/pricing): Full pricing page with tier comparison