Operator Quickstart

Register an account, create an OAuth app, install the Buddo CLI, and deploy your first container to buddocloud hosting. This guide takes about 15 minutes.

Step 1: Register an account

Create a new Buddo account by posting your email, username, and password to /api/auth/register.

Request

curl -X POST https://api.buddo.xyz/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "username": "myoperator",
    "password": "a-strong-password"
  }'

Response 201

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "you@example.com",
    "username": "myoperator",
    "tier": "free",
    "points": 0,
    "referral_code": "ABC123",
    "email_verified": false,
    "registration_number": 42
  }
}

Check your inbox for a verification email and confirm your address before proceeding. Registration is limited to 5 requests per hour per IP.

Step 2: Log in and get a JWT

Authenticate with your credentials to receive a JWT. Pass it as a Bearer token in the Authorization header for all authenticated requests.

Request

curl -X POST https://api.buddo.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-strong-password"
  }'

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "you@example.com",
    "username": "myoperator",
    "tier": "free",
    "is_admin": false,
    "email_verified": true,
    "totp_enabled": false
  }
}

Save the token value. The examples below use JWT as a placeholder — substitute your actual token.

Step 3: Create an OAuth app

Deploy endpoints require an OAuth access token with the deploy:manage scope. The first step is registering an OAuth app so the platform can issue tokens for your application.

Endpoint

POST /api/oauth/apps — requires JWT authentication

Request

curl -X POST https://api.buddo.xyz/api/oauth/apps \
  -H "Authorization: Bearer JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "My Deploy App",
    "redirect_uris": ["http://localhost:9876/callback"],
    "requested_scopes": ["deploy:manage"]
  }'

Response 201

{
  "app": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "client_id": "client_abc123",
    "client_secret": "secret_xyz789",
    "app_name": "My Deploy App",
    "redirect_uris": ["http://localhost:9876/callback"],
    "approved_scopes": ["deploy:manage"]
  }
}

Store your client_id and client_secret securely. The secret is only shown once. The deploy:manage scope gives your app permission to create, stop, restart, and destroy deployments on your account.

Step 4: Install the Buddo CLI

The Buddo CLI (buddo) is the fastest way to deploy and manage applications from your terminal. Download the binary for your platform:

Linux / macOS install

# Download (replace PLATFORM with linux-amd64 or darwin-arm64)
curl -Lo buddo https://releases.buddocloud.com/cli/latest/buddo-PLATFORM
chmod +x buddo
sudo mv buddo /usr/local/bin/

Verify

buddo --version
# buddo v0.1.0

Step 5: Log in via CLI

Authenticate the CLI with your Buddo credentials. The CLI stores a JWT locally and uses it for subsequent commands.

buddo login

You will be prompted for your email and password:

Email: you@example.com
Password: ••••••••••••
Logged in as myoperator

Step 6: Deploy your first app

Create a new container deployment with a single command. The CLI calls POST /api/deploy/apps on your behalf.

buddo deploy \
  --name my-app \
  --image docker.io/library/nginx:latest \
  --port 80

The CLI will prompt you to choose a deploy tier if one is not specified. For this quickstart, select the default Buddo starter tier.

What the CLI does

1. Calls GET /api/deploy/tiers to list available tiers.
2. Calls POST /api/deploy/apps with your name as the subdomain, your image, the selected tier, and the port.
3. Polls GET /api/deploy/apps/{id}/status until the deployment reaches running.
4. Prints the live URL.

Output

Creating deployment "my-app"...
Deployment ID: 550e8400-e29b-41d4-a716-446655440000
Status: pending → deploying → running
Live at: https://my-app.buddocloud.com

Equivalent API call

curl -X POST https://api.buddo.xyz/api/deploy/apps \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "my-app",
    "image": "docker.io/library/nginx:latest",
    "tier": "buddo-starter",
    "port": 80
  }'

Step 7: Check status

Poll your deployment's status to confirm it is running and passing health checks.

buddo status my-app

Output

Deployment: my-app (550e8400-e29b-41d4-a716-446655440000)
Status:      running
Health:      healthy
Last check:  2026-05-21T10:05:00Z
URL:         https://my-app.buddocloud.com

Equivalent API call

curl https://api.buddo.xyz/api/deploy/apps/DEPLOYMENT_ID/status \
  -H "Authorization: Bearer OAUTH_TOKEN"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "subdomain": "my-app",
  "health_status": "healthy",
  "last_health_check": "2026-05-21T10:05:00Z"
}

Deployment statuses

Step 8: View logs

The deploy audit log records every action performed on a deployment: create, deploy, stop, restart, and destroy. Each entry includes the initiating user, timestamp, and completion status.

buddo deploy logs DEPLOYMENT_ID

Output

Action     Status     Initiated by   Time
------     ------     ------------   ----
create     completed  myoperator     2026-05-21T10:00:00Z
deploy     completed  platform       2026-05-21T10:00:05Z

Equivalent API call

curl https://api.buddo.xyz/api/deploy/apps/DEPLOYMENT_ID/logs \
  -H "Authorization: Bearer OAUTH_TOKEN"

Response

{
  "logs": [
    {
      "id": "...",
      "action": "create",
      "status": "completed",
      "initiated_by": "550e8400-e29b-41d4-a716-446655440000",
      "inserted_at": "2026-05-21T10:00:00Z",
      "details": null
    },
    {
      "id": "...",
      "action": "deploy",
      "status": "completed",
      "initiated_by": null,
      "inserted_at": "2026-05-21T10:00:05Z",
      "details": null
    }
  ]
}

Step 9: Stop and destroy

When you no longer need a deployment, stop it to pause the container (billing pauses but the subdomain reservation is kept) or destroy it to permanently remove everything.

Stop

buddo deploy stop DEPLOYMENT_ID

The container halts. Status transitions to stopped. You can restart it later with buddo deploy restart DEPLOYMENT_ID.

Equivalent API call

curl -X POST https://api.buddo.xyz/api/deploy/apps/DEPLOYMENT_ID/stop \
  -H "Authorization: Bearer OAUTH_TOKEN"

Destroy

buddo deploy destroy DEPLOYMENT_ID

Permanently removes the deployment, its container, and all associated configuration. This action cannot be undone. Status transitions to destroyed.

Equivalent API call

curl -X DELETE https://api.buddo.xyz/api/deploy/apps/DEPLOYMENT_ID \
  -H "Authorization: Bearer OAUTH_TOKEN"

Response

{
  "message": "Deployment destroyed",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

CLI Command Reference

Summary of all CLI commands used in this guide:

API Quick Reference

All deploy endpoints require an OAuth token with deploy:manage scope. For full schemas see the Deploy API Reference.

What's next