⚡ Quick Start

Alpaca Cloud is an open-source backend platform — your own Supabase, on your own infrastructure. Get a full Postgres database, REST API, auth, storage, edge functions, and realtime in seconds.

1. Create an account

Sign up at app.alpaca-cloud.com.

2. Choose your project type

• Backend — Postgres database with Auth, Storage, Edge Functions, Realtime. Choose Shared (instant) or Dedicated VM.
• Frontend — Static site / SPA hosting. Connect GitHub, deploy on every push.
• Apps — Persistent Docker containers. Any language, any framework.

3. Get your credentials (Backend projects)

Open your project → Easy Connect:

• Project URL — e.g. https://my-project.alpaca-cloud.com
• Anon key — safe for frontend code
• Service role key — admin access, server-side only

4. Query your database

npm install @alpacacloud/js

import { createClient } from '@alpacacloud/js'

const alp = createClient(
  'https://my-project.alpaca-cloud.com',
  'your-anon-key'
)

const { data, error } = await alp
  .from('posts')
  .select('id, title, author')
  .eq('published', true)
  .order('created_at', { ascending: false })
  .limit(10)

🗂️ Project Types

Alpaca Cloud has three distinct project types, each for a different workload:

🗄️ Backend — Shared Cluster

Instant provisioning. Your Postgres database runs on a shared, managed cluster. Best for development, small apps, and getting started quickly.

• Ready in seconds — no VM to spin up
• Full Postgres 16, PostgREST REST API, Auth, Storage, Edge Functions, Realtime
• Subdomain: yourproject.alpaca-cloud.com
• Starts free; upgrade for more storage and connections

// Create via API
POST /projects
{ "name": "my-app", "backend_type": "shared" }

🖥️ Backend — Dedicated VM

Your own Hetzner cloud server. Complete isolation — no shared resources, no noisy neighbours. Best for production workloads requiring guaranteed performance or data residency.

• Takes 3–8 minutes to provision (spins up a real VM)
• Full Postgres on your own server with root-level access available
• Same services: Auth, Storage, Edge Functions, Realtime
• Choose your server size (cpx11 → cpx41)
• Higher cost — you pay for the VM

POST /projects
{ "name": "prod-db", "backend_type": "dedicated", "plan": "pro" }

🌐 Frontend Hosting

Static site and SPA hosting with GitHub auto-deploy. Like Vercel or Netlify, on Alpaca Cloud infrastructure.

• Connect a GitHub repo → deploys automatically on every push
• Works with React, Vue, Next.js (static export), Svelte, Astro, plain HTML
• Subdomain: yoursite.alpaca-cloud.com
• Auto-SSL, instant global delivery

POST /projects
{ "name": "my-site", "backend_type": "frontend" }

🚀 App Hosting (Docker containers)

Persistent Docker containers for any language or framework. Like Fly.io, on Alpaca Cloud infrastructure.

• Add a Dockerfile to your project — any language works
• Your app must read process.env.PORT — Alpaca assigns the port
• Subdomain: yourapp.alpaca-cloud.com
• Auto-SSL, live logs, env vars, health checks
• Shared compute tier: 0.5 vCPU, 512MB RAM

POST /projects
{ "name": "my-api", "backend_type": "app" }

🔑 Authentication

All Management API requests require a Bearer token. Project API keys (anon/service_role) are separate — used to access the PostgREST database REST API directly.

User JWT (session token)

POST https://app.alpaca-cloud.com/auth/login
Content-Type: application/json

{ "email": "you@example.com", "password": "yourpassword" }

→ { "token": "eyJ...", "user": { ... } }

Authorization: Bearer eyJ...

Personal Access Token (PAT)

Go to Dashboard → Settings → API Tokens → create a token. PATs don't expire — good for CI/CD and scripts.

Authorization: Bearer pat_...

Project API Keys (anon / service_role)

Each backend project has two keys for accessing its PostgREST API:

• anon key — respects Row Level Security. Safe for frontend.
• service_role key — bypasses RLS. Server-side only — never expose to clients.

📦 JavaScript SDK

npm install @alpacacloud/js

Initialize

import { createClient } from '@alpacacloud/js'
const alp = createClient('https://your-project.alpaca-cloud.com', 'your-anon-key')

Database

const { data } = await alp.from('users').select('*').eq('active', true)
await alp.from('posts').insert({ title: 'Hello', body: '...' })
await alp.from('posts').update({ published: true }).eq('id', 42)
await alp.from('posts').delete().eq('id', 42)
// Filters: eq, neq, gt, gte, lt, lte, like, ilike, in, is, not

Auth

const { user } = await alp.auth.signUp({ email, password })
const { user, token } = await alp.auth.signIn({ email, password })
await alp.auth.signOut()
const user = alp.auth.user()

Storage

await alp.storage.from('avatars').upload('user.png', file, { contentType: 'image/png' })
const url = alp.storage.from('avatars').getPublicUrl('user.png')
const { data } = await alp.storage.from('avatars').download('user.png')

Realtime

const channel = alp.realtime.channel('room:chat')
  .on('broadcast', { event: 'message' }, ({ payload }) => console.log(payload))
  .subscribe()
channel.send({ type: 'broadcast', event: 'message', payload: { text: 'hello' } })

Edge Functions

const { data } = await alp.functions.invoke('my-function', { body: { name: 'world' } })

Python SDK

pip install alpaca-cloud
from alpaca_cloud import create_client
alp = create_client("https://your-project.alpaca-cloud.com", "your-anon-key")
response = alp.table('posts').select('id, title').eq('published', True).execute()

Flutter SDK

flutter pub add alpaca_cloud_flutter
import 'package:alpaca_cloud_flutter/alpaca_cloud.dart';
AlpacaCloud.initialize(url: 'https://your-project.alpaca-cloud.com', anonKey: 'your-anon-key');
final data = await AlpacaCloud.instance.client.from('posts').select('id, title').eq('published', true);

🌐 Frontend Hosting

Deploy static sites and single-page apps (SPAs) with GitHub auto-deploy. Every push to your main branch goes live automatically.

Supported Frameworks

• React — build command: npm run build, output: dist/
• Vue — build command: npm run build, output: dist/
• Next.js — static export only (next export), output: out/
• Svelte / SvelteKit — adapter-static, output: build/
• Astro — output: dist/
• Plain HTML / Vanilla JS — no build step needed

Setup

1. Create a Frontend project in the dashboard (Frontend tab → New Project)
2. Connect your GitHub repo via the Integrations tab
3. Set your build command (e.g. npm run build) and output directory (e.g. dist)
4. Every push to your production branch triggers an automatic build and deploy

Build Flow

git push origin main
  → Alpaca clones your repo
  → runs install_command (e.g. npm install)
  → runs build_command (e.g. npm run build)
  → deploys output_dir (e.g. dist/) to static hosting
  → live at yoursite.alpaca-cloud.com

Manual Deploy (via API)

POST /projects/:id/frontend/deploy
Content-Type: application/json
{ "branch": "main" }

Custom Domains

Your site is always available at yoursite.alpaca-cloud.com. Custom domain support is on the roadmap.

🚀 App Hosting (Docker containers)

Run any Dockerized application as a persistent container with a public HTTPS URL. Node.js, Python, Go, Ruby, anything — if it has a Dockerfile, it deploys.

Requirements

• A Dockerfile in your project root
• Your app must listen on the port from process.env.PORT (Alpaca assigns this — do not hardcode a port)

Quick Start

1. Create an App project in the dashboard (Apps tab → New App)
2. Open the project → click Deploy
3. Your app is live at yourapp.alpaca-cloud.com

Dockerfile Example

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 8080
CMD ["node", "server.js"]

// Your server must read PORT from the environment:
const port = process.env.PORT || 8080;
app.listen(port);

Environment Variables

Set env vars in the project dashboard → Settings tab. They're injected at container start.

Resource Limits (Shared Tier)

• CPU: 0.5 vCPU
• Memory: 512 MB RAM
• Public URL: yourapp.alpaca-cloud.com
• Auto-SSL, live logs, health checks included

🔄 GitHub Auto-Deploy

Both Frontend and App Hosting projects support GitHub auto-deploy — connect your repo once and every push triggers a deploy.

Setup

1. Connect your GitHub account: Dashboard → Integrations tab → GitHub
2. Open your project → Overview → GitHub tab
3. Enter your repository URL and production branch
4. Click Connect & enable auto-deploy

App Hosting Webhook URL (manual)

https://api.alpaca-cloud.com/projects/YOUR_PROJECT_ID/compute/github-webhook
Events: push, ping | Content-Type: application/json

Deploy Flow (App Hosting)

git push origin main
  → GitHub webhook fires
  → Alpaca pulls latest code on compute VM
  → docker build (fresh image)
  → docker run --restart unless-stopped
  → nginx updated → app is live

📡 Realtime

Subscribe to live database changes and broadcast messages to connected clients via WebSocket. Powered by Postgres logical replication — no polling required.

Use cases

• Live dashboards and analytics
• Collaborative editing (multiple users, one document)
• Chat and messaging
• Presence (who is online right now)
• Real-time notifications

JavaScript SDK

import { createClient } from '@alpacacloud/js'
const alp = createClient(url, anonKey)

// Subscribe to broadcast messages
const channel = alp.realtime.channel('room:chat')
  .on('broadcast', { event: 'message' }, ({ payload }) => {
    console.log('New message:', payload)
  })
  .subscribe()

// Send a message
channel.send({ type: 'broadcast', event: 'message', payload: { text: 'hello' } })

// Presence — see who is online
channel.on('presence', { event: 'join' }, ({ newPresences }) => {
  console.log('joined:', newPresences)
})

WebSocket endpoint

wss://your-project.alpaca-cloud.com/realtime/v1/websocket?apikey=YOUR_ANON_KEY

⚡ Edge Functions

Serverless functions that run alongside your database on your project. Write server-side logic, webhooks, scheduled tasks, and APIs — deployed in seconds from the dashboard or CLI.

Runtime

• Deno runtime — TypeScript and JavaScript natively
• NPM-compatible (npm: specifiers)
• Secrets injected via environment variables (set in dashboard → Vault)

Write a function

// functions/hello/index.ts
Deno.serve(async (req) => {
  const { name } = await req.json()
  return Response.json({ hello: name })
})

Deploy from dashboard

Dashboard → your project → Edge Functions tab → paste code → Deploy.

Invoke via SDK

const { data, error } = await alp.functions.invoke('hello', {
  body: { name: 'world' }
})
// → { hello: 'world' }

Invoke via HTTP

POST https://your-project.alpaca-cloud.com/functions/v1/hello
Authorization: Bearer <anon-key>
Content-Type: application/json

{ "name": "world" }

Secrets / Environment Variables

Add secrets in Dashboard → Vault tab. Access them in functions with Deno.env.get('KEY').

🔌 Plugin Marketplace

One-click integrations with popular services. Install a plugin on a project and it injects the API keys / config as environment variables — available in your edge functions and server-side code.

Available Plugins

• Resend — transactional email API
• Stripe — payments and subscriptions
• OpenAI — GPT, embeddings, and vision APIs
• Upstash Redis — serverless Redis (rate limiting, caching, queues)
• Cloudflare Turnstile — bot detection and CAPTCHA
• Loops — marketing email automation
• Sentry — error monitoring and alerting
• Trigger.dev — background jobs and workflows

Installing a plugin

1. Open your project → Plugins tab
2. Browse the marketplace and click Install
3. Enter your API key for the service
4. The key is stored in your project Vault and injected into edge functions automatically

Developer OAuth — build your own plugin

Third-party developers can build Alpaca Cloud plugins using OAuth:

1. Register your app at Dashboard → Developers tab
2. Get a client_id and client_secret
3. Users authorize your app via a consent screen at /plugins/authorize
4. Exchange the code for a token and use the Plugin API to manage env vars and keys

🤖 MCP / AI Connect

Every Alpaca Cloud backend project includes a built-in MCP (Model Context Protocol) server — letting AI assistants like Claude, Cursor, or any MCP-compatible tool interact with your database directly.

What the MCP server can do

• Run SQL queries against your database
• List tables and get schema information
• List, create, and delete auth users
• Get project info (URL, keys, status)

Claude Desktop config

// Get the config from your project → Easy Connect → MCP tab
// It will look like:
{
  "mcpServers": {
    "my-project": {
      "command": "npx",
      "args": ["-y", "@alpacacloud/mcp"],
      "env": {
        "ALPACA_PROJECT_URL": "https://my-project.alpaca-cloud.com",
        "ALPACA_SERVICE_KEY": "your-service-role-key"
      }
    }
  }
}

Easy Connect (any AI assistant)

Dashboard → your project → Easy Connect tab. Copy the prompt — it includes your project URL, keys, and a description of your schema. Paste it into any AI assistant's system prompt and it can query, insert, and manage your database immediately.

MCP endpoint

GET  /projects/:id/mcp   → returns endpoint info and Claude config
POST /projects/:id/mcp   → JSON-RPC 2.0 endpoint
     Tools: run_sql, list_tables, get_table_schema,
            list_auth_users, create_auth_user, delete_auth_user,
            get_project_info

API Reference

Manage AlpacaBase projects, databases, auth, storage, and edge functions. Authenticate with: Authorization: Bearer <token> Get a token: POST /auth/login → use the token → or POST /tokens to create a PAT. Quick start: 1. POST /auth/login to get a token 2. POST /projects to create a project (backend_type: shared = instant) 3. Poll GET /projects/:id/status until status is healthy 4. Use postgrest_url from the project for your database REST API

Base URL: https://app.alpaca-cloud.com  ·  Version: 1.4.0

Download OpenAPI JSON ↗