1. How to use this file

Download vibecloud_guide.md from the VibeCloud UI and place it in the root of your application repository.

Before asking Claude (or any AI agent) to deploy, tell it to read vibecloud_guide.md first. This file explains everything an agent needs: authenticate, list packages, create a VPS or database, poll the provisioning job, use the returned credentials to deploy, manage services, and recover from common gotchas.

Recommended repository layout:

my-application/
  vibecloud_guide.md
  .env_vibecloud
  package.json
  src/
Copy

Use .env_vibecloud to store the VibeCloud API URL and API token. Do not commit .env_vibecloud to git.

Hosts (important):

• UI / web app: https://vibecloud.vn — humans log in, manage services, top up balance, generate tokens.
• API: https://api.vibecloud.vn — every POST /api/... / GET /api/... call in this guide goes here. The UI host does not serve /api.

2. Get an API token

Open the VibeCloud UI at https://vibecloud.vn, sign in with your email, then go to API Keys and create a key for agent automation. The key has the prefix vc_live_.

You can also use the helper script (point it at the API host):

./scripts/vibecloud-auth.sh https://api.vibecloud.vn
Copy

On Windows PowerShell:

.\scripts\vibecloud-auth.ps1 -ApiUrl https://api.vibecloud.vn
Copy

The command writes .env_vibecloud in the current directory:

VIBECLOUD_API_URL=https://api.vibecloud.vn
VIBECLOUD_API_TOKEN=vc_live_xxx
Copy

Authenticate every request with the standard bearer header:

curl -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" ...
Copy

3. What vc_live_* tokens can and can't do

vc_live_* automation tokens are scoped for infrastructure work. Endpoint matrix:

If an agent needs to check the balance, the human should top up via the UI and tell the agent "you have enough budget". The agent will see HTTP 402 Insufficient credit if it tries to provision beyond the available balance — see §11.

4. List available packages (optional but recommended)

curl "$VIBECLOUD_API_URL/api/packages"
Copy

Returns the list of preset packages with slug, name, cpu, ram_gb, disk_gb. Pick a slug like standard-2 to use in §5/§6.

5. Create an LXC VPS

VibeCloud accepts two sizing shapes. Pick whichever fits:

• A. Named package — package_slug resolves server-side to a preset cpu/ram_gb/disk_gb.
• B. Custom sizing — pass cpu, ram_gb, disk_gb directly.

Mixing the two (slug + dims at the same time) returns HTTP 422.

Using a package

curl -X POST "$VIBECLOUD_API_URL/api/lxc" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"my-app","package_slug":"standard-2"}'
Copy

Using custom sizing

curl -X POST "$VIBECLOUD_API_URL/api/lxc" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"my-app","cpu":2,"ram_gb":2,"disk_gb":30}'
Copy

The response is a job, not a finished VPS:

{
  "id": "65f00000000000000000000a",
  "type": "create_lxc",
  "status": "pending",
  "result": null,
  "error": null,
  "attempts": 0,
  "max_attempts": 3,
  "created_at": "...",
  "updated_at": "..."
}
Copy

Provisioning takes 60–180 s. Poll the job (see §7).

6. Create a database instance

Same two shapes. engine is required and must be one of mongodb, postgresql, mysql.

Using a package

curl -X POST "$VIBECLOUD_API_URL/api/databases" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"my-app","engine":"mongodb","package_slug":"standard-2"}'
Copy

Using custom sizing

curl -X POST "$VIBECLOUD_API_URL/api/databases" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"my-app","engine":"postgresql","cpu":2,"ram_gb":2,"disk_gb":30}'
Copy

Returns a job, same shape as the LXC job above.

7. Poll the job until it finishes

curl "$VIBECLOUD_API_URL/api/jobs/<job_id>" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"
Copy

status transitions through one of these terminal states:

Recommended polling pattern (bash):

JOB_ID="...id from create call..."
for i in {1..60}; do
  RESP=$(curl -s "$VIBECLOUD_API_URL/api/jobs/$JOB_ID" \
    -H "Authorization: Bearer $VIBECLOUD_API_TOKEN")
  STATUS=$(echo "$RESP" | python3 -c 'import json,sys; print(json.load(sys.stdin)["status"])')
  if [ "$STATUS" = "succeeded" ]; then
    echo "$RESP" | python3 -m json.tool
    break
  fi
  if [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
    echo "$RESP" >&2
    exit 1
  fi
  sleep 5
done
Copy

When status=succeeded, result is the full service object: id, kind, status, name, ip_address, cpu/ram_gb/disk_gb, power_state, hourly_rate_vnd, credentials (LXC) or databases[] (database service), created_at, etc.

8. Use the credentials

LXC — SSH in and deploy

result.credentials contains root_password, ssh_private_key (PEM), ssh_public_key. result.ip_address is the public IP.

The PEM is returned as a standard JSON string with \n-escaped newlines (use any standard JSON parser — json.loads works fine, no special flags). Save it and chmod 600:

mkdir -p ~/.ssh
python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["result"]["credentials"]["ssh_private_key"])' job.json > ~/.ssh/vibecloud_my_app
chmod 600 ~/.ssh/vibecloud_my_app
ssh -i ~/.ssh/vibecloud_my_app root@<ip_address>
Copy

The image is a fresh Ubuntu 24.04 LXC. It ships minimal — curl and ca-certificates are NOT preinstalled. Always run this once before downloading anything:

ssh -i ~/.ssh/vibecloud_my_app root@<ip_address> \
  'DEBIAN_FRONTEND=noninteractive apt-get update -q && apt-get install -yq curl ca-certificates'
Copy

Database — connect via the returned connection string

result.databases[0] contains engine, host, port, database, username, password, connection_string. The connection string is ready to drop into your app's env var:

# example for mongodb
export DATABASE_URL=$(jq -r '.result.databases[0].connection_string' job.json)
Copy

For multiple logical databases on the same instance, see §10.

9. Manage running services

# List your services
curl "$VIBECLOUD_API_URL/api/services" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"

# Get one service (includes credentials)
curl "$VIBECLOUD_API_URL/api/services/<service_id>" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"

# Stop / start (you keep paying while stopped — destroy if you don't need it)
curl -X POST "$VIBECLOUD_API_URL/api/services/<service_id>/stop"   -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"
curl -X POST "$VIBECLOUD_API_URL/api/services/<service_id>/start"  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"

# Delete permanently (frees the IP after a 3h cooldown for ARP cache safety)
curl -X DELETE "$VIBECLOUD_API_URL/api/services/<service_id>" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"
Copy

LXC-specific:

# Resize CPU / RAM / disk (disk can only grow). Body matches LxcResizeRequest:
curl -X POST "$VIBECLOUD_API_URL/api/lxc/<service_id>/resize" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cpu":4,"ram_gb":8,"disk_gb":60}'

# Rebuild — destroys and recreates the LXC with the SAME ip + credentials.
# Returns a job, poll it like §7.
curl -X POST "$VIBECLOUD_API_URL/api/services/<service_id>/rebuild" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"
Copy

Database-specific:

# Add another logical database to an existing instance (same VPS, separate DB):
curl -X POST "$VIBECLOUD_API_URL/api/databases/<service_id>/databases" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"another-app"}'

# Rotate a database's password:
curl -X POST "$VIBECLOUD_API_URL/api/databases/<service_id>/databases/<db_name>/change-password" \
  -H "Authorization: Bearer $VIBECLOUD_API_TOKEN"
Copy

10. Operational gotchas

Reused IP triggers SSH "REMOTE HOST IDENTIFICATION HAS CHANGED" When you delete an LXC and a new one later gets the same IP (after the 3-hour cooldown), the new host has a different SSH host key. Your ~/.ssh/known_hosts still has the old one. Clear it:

ssh-keygen -R <ip_address>
# then ssh normally; accept the new fingerprint
Copy

Outbound SMTP (ports 25/465/587) is blocked A firewall security group named block-smtp is attached to every new LXC to prevent abuse. If your app legitimately needs to send mail, use an HTTP-API mail provider (SendGrid, Mailgun, Resend, AWS SES).

Stopped services still bill stop only powers the container off — it still occupies disk and an IP, so you keep paying the hourly rate. To stop paying, DELETE the service.

Provisioning vs power state Service status=active means VibeCloud finished provisioning. power_state=running means the LXC kernel is up. After a stop, status stays active but power_state becomes stopped.

11. Billing

• Every active service is billed hourly. Each tick debits the service's hourly_rate_vnd from your balance.
• Stopped services keep billing (see gotcha above).
• Destroyed services do not bill.
• When your balance hits zero, the service is suspended (powered off). It stays in suspended for the configured grace period (default 7 days). After the grace period it's destroyed automatically and the IP is freed.
• LXC resize uses "Option D" billing: the container is resized immediately but the new hourly rate kicks in at the next hourly tick. The in-progress hour is charged at the old rate. pending_hourly_rate_vnd shows the queued rate.

12. Common error responses

Service quotas and network cap

Every account starts with a small service cap:

• Free tier (never paid) — 2 VPS + 2 database
• Paid tier (paid at least once) — 10 VPS + 10 database

Customers can request higher limits via the UI; an admin approves or denies, and the new cap is in effect immediately for subsequent agent calls. Trying to exceed the cap returns the 409 above.

Every VPS NIC is bandwidth-capped at 200 Mbps (25 MB/s). If you benchmark with iperf3 -c … and see ~190–200 Mbps, that's the provisioned cap, not a transient throttle.