Deploy Instances - RepoCloud Documentation

Deploy a New Instance

The API deploys Ubuntu VPS instances only. For other VPS templates (Coolify, Dokploy, etc.), use AI Deploy or the web dashboard.

POST /api/v1/instances

Request Body

Field	Type	Required	Description
`project_name`	string	Yes	A name for your instance (max 64 characters)
`flavor`	string	Yes	The server size flavor ID (see Available Flavors)
`ssh_public_key`	string	No	Your SSH public key. If omitted, a key pair is generated and the private key is returned in the response.

Example Request

curl -X POST https://repocloud.io/api/v1/instances \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-dev-server",
    "flavor": "s-2vcpu-4gb",
    "ssh_public_key": "ssh-ed25519 AAAA... user@host"
  }'

Response (202 Accepted)

The instance is created asynchronously. The response includes connection credentials and a status field that starts as pending.

{
  "instance_id": 456,
  "vps_id": "inst-abc123",
  "status": "pending",
  "ipv4": "203.0.113.42",
  "domain": "abcd1234.rpcld.co",
  "custom_domain": null,
  "root_user": "root",
  "root_password": "generated-password-here",
  "ssh_port": 22,
  "ssh_key": {
    "name": "mcp-key-456",
    "fingerprint": "SHA256:xxxx...",
    "public_key": "ssh-ed25519 AAAA...",
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
  },
  "plan": {
    "flavor": "s-2vcpu-4gb",
    "vcpu": 2,
    "ram_mb": 4096,
    "disk_gb": 40,
    "hourly_price": 0.0167
  },
  "created_at": "2026-07-15T10:30:00"
}

The ssh_key.private_key field is only included when you do not provide your own ssh_public_key. Store it securely — it is not retrievable later.

Polling for Readiness

After deploying, poll the instance detail endpoint until status changes from pending/Deploying to Online:

curl https://repocloud.io/api/v1/instances/456 \
  -H "Authorization: Bearer rcmcp_your_key_here"

Typical provisioning takes 2–5 minutes. Once status is Online and ipv4 is populated, the server is ready for SSH connections.

Available Flavors

Flavor ID	vCPU	RAM	SSD	Hourly	Monthly
`s-1vcpu-2gb`	1	2 GB	30 GB	$0.0083	$6.00
`s-2vcpu-2gb`	2	2 GB	40 GB	$0.0125	$9.00
`s-2vcpu-4gb`	2	4 GB	40 GB	$0.0167	$12.00
`s-4vcpu-8gb`	4	8 GB	80 GB	$0.0333	$24.00
`s-8vcpu-16gb`	8	16 GB	160 GB	$0.0667	$48.00
`s-16vcpu-32gb`	16	32 GB	320 GB	$0.1333	$96.00

The s-1vcpu-1gb flavor ($3/month) is not available for VPS instances. It is reserved for Container Apps only.

Error Responses

Status	Error	Cause
400	`project_name is required`	Missing or empty `project_name`
400	`project_name must be 64 characters or fewer`	Name exceeds 64 characters
400	`flavor is required`	Missing or empty `flavor`
400	`Invalid flavor: xxx`	Unrecognized flavor ID, or elastic/premium flavor
400	`Flavor xxx is permanently unavailable for Ubuntu VPS`	The `s-1vcpu-1gb` flavor cannot be used for VPS
402	`Insufficient balance`	Account balance is $3 or less. Deposit at /billing.
503	`VPS capacity exhausted`	No IPv4 addresses are currently available
503	`Tier capacity exhausted`	The selected flavor has no available capacity
502	`Upstream error`	The VPS control plane returned an error — retry after a few seconds

Connecting to Your Instance

Once the instance status is Online:

ssh root@203.0.113.42

Use the root password from the deploy response, or the SSH key you provided/received.

​Deploy a New Instance

​Request Body

​Example Request

​Response (202 Accepted)

​Polling for Readiness

​Available Flavors

​Error Responses

​Connecting to Your Instance

Deploy a New Instance

Request Body

Example Request

Response (202 Accepted)

Polling for Readiness

Available Flavors

Error Responses

Connecting to Your Instance