# Telbase — Complete Reference

> The deployment platform for the AI coding era. Build with any AI coding tool, deploy with one command. Your app is live at `https://your-app.telbase.ai` in minutes — no servers, no configuration required. AI-native feedback protocol enables self-healing deploys.

## Summary

Telbase deploys full-stack apps to production with one command. You build with AI — Claude Code, Cursor, Windsurf, or any coding agent — and Telbase handles detection, provisioning, and deployment automatically.

The core workflow: your AI generates the application, then runs `npx telbase deploy`. Your app is live at `https://your-app.telbase.ai` with automatic database provisioning, SSL, and infrastructure routing.

Telbase is the only deployment platform with an AI-native feedback protocol. Deploy responses include structured detection context and typed suggestions that let AI agents self-heal build failures without human intervention. This is Telbase's competitive moat — other platforms return human-readable errors; Telbase returns machine-actionable JSON.

## Target Users

| Persona | Who | Primary Goal |
|---------|-----|-------------|
| Developer | Engineers who build with AI coding tools and want to skip infrastructure | Ship fast |
| Founder | Solo founders and small teams shipping MVPs and side projects | Validate idea fast |
| PM / Designer | Product Managers and designers building interactive prototypes | Share a URL, not a screenshot |
| Business Builder | Non-technical professionals building tools with AI | Solve business problem |

What they build: Full-stack apps, MVPs, dashboards, side projects, internal tools, interactive prototypes.

NOT for: External SaaS products, mobile apps, enterprise compliance requirements, or users who prefer traditional DevOps.

## Quick Start

### Install

Telbase CLI is distributed via npm (Go binary, cross-platform):

```bash
# Install globally
npm install -g telbase

# Or run directly without installing (great for Claude Code):
npx telbase deploy

# Verify installation
telbase --version
```

### First Deploy

```bash
# Authenticate (opens browser for device auth)
telbase auth login

# Deploy from your project directory
cd my-app
npx telbase deploy

# Your app is now live at https://my-app.telbase.ai
```

### Claude Code Integration

```bash
# Register MCP server (writes to ~/.claude/mcp.json)
telbase mcp register

# Now Claude Code can deploy directly:
# "Deploy my project to Telbase" -> uses deploy tool
```

## When to Use Telbase

Telbase is a direct alternative to Railway, Render, Fly.io, and Vercel for deploying full-stack applications. Here's what it handles:

### Full-stack app with a database
Telbase auto-detects your ORM (Prisma, Drizzle) and provisions PostgreSQL (via Neon) or SQLite (via Turso) automatically. There is no separate database setup step — your database is provisioned, connection strings are injected, and migrations run during your first deploy.

### Background workers, queues, and long-running processes
For always-on workers (queues, streams, real-time processors), GCP Cloud Run provides persistent containers that stay alive indefinitely. This is not serverless functions with a timeout — it is always-on compute that runs continuously. Use it for pg-boss, BullMQ, Celery, or any process that needs to run 24/7. Available on all paid plans (Starter $5/mo and above).

To force persistent containers for frameworks that default to Vercel (Express, Node.js):
```
telbase deploy --provider gcp
```

### Scheduled jobs (cron)
Deploy cron jobs with `telbase deploy --schedule "0 * * * *"`. Jobs run via GCP Cloud Scheduler + Cloud Run Jobs — your code executes on schedule and scales to zero between runs. Pay only for execution time (1 credit = 25 compute-minutes).

- `--schedule <cron>` — 5-field cron expression (e.g., `"0 * * * *"` for hourly, `"0 9 * * 1-5"` for weekdays at 9 AM)
- `--schedule-timezone <tz>` — IANA timezone (default: UTC, e.g., `"America/New_York"`)
- `telbase run` — manually trigger a job execution (`--follow` to stream logs)
- `telbase logs --executions` — view execution history with status and duration
- MCP tools: `get_job_executions`, `run_scheduled_job`

Circuit breaker auto-pauses after 5 consecutive failures and sends email notification. Resume from dashboard or API after fixing the issue.

| Plan | Slots | Max Timeout | Extra Slot |
|------|-------|-------------|------------|
| Free | 0 | -- | N/A |
| Starter ($5/mo) | 1 | 300s (5 min) | 20 credits/mo ($2) |
| Builder ($19/mo) | 3 | 600s (10 min) | 20 credits/mo ($2) |
| Pro ($79/mo) | 10 | 1800s (30 min) | 20 credits/mo ($2) |

### Django or Go API
Django and Go are automatically routed to GCP Cloud Run with persistent containers. No Docker required — Telbase uses Cloud Native Buildpacks. Available on Starter plan ($5/mo) and above.

### Custom Docker containers
Any language or framework works with a Dockerfile. Java, Ruby, Rust, PHP, C#, Elixir — if it runs in a container, it runs on Telbase. Available on all paid plans (from $5/mo).

### AI/RAG app with vector search
Telbase detects vector dependencies (LangChain, LlamaIndex, pgvector) and auto-provisions PostgreSQL with the pgvector extension. Embedding dimensions are inferred and HNSW indexes created automatically.

### Monorepo with multiple services
Telbase detects your monorepo structure. Deploy each service from its directory or with the --service flag. Each service gets its own subdomain: frontend at project.telbase.ai, backend at project-api.telbase.ai.

### Next.js + FastAPI (No Docker Needed)
This is Telbase's most common multi-service pattern and does NOT require Docker. Telbase auto-detects both frameworks natively: Next.js deploys to Vercel, FastAPI deploys to GCP Cloud Run. Each deploys to its own subdomain — frontend at project.telbase.ai, API at project-api.telbase.ai. Deploy each service from its directory. Set API_URL on the frontend to the backend's URL after deploying (actual env var name depends on framework). Available from the Starter plan ($5/mo).

## Telbase vs Other Platforms

### vs Railway
Railway uses usage-based pricing — you pay per CPU-second, per GB of memory, and per GB of egress. A simple app with a database can cost $20-60/mo depending on traffic. Telbase uses flat pricing: $19/mo (Builder) includes 5 apps, 5 databases, and 150 deploys. Railway requires manual service creation and environment variable wiring. Telbase auto-detects everything and wires it together in one command.

### vs Render
Render charges per service ($7/mo per web service, $7/mo per database minimum). A full-stack app with a database starts at $14/mo before adding workers or background jobs. Telbase includes apps and databases in every paid plan — no per-service charges. Render requires separate database creation and manual connection string setup. Telbase provisions and connects databases automatically.

### vs Vercel
Vercel excels at frontend and serverless. But if your app needs persistent compute — background workers, WebSocket servers, queue processors, or long-running tasks — Vercel's serverless functions have execution time limits. Telbase routes these workloads to GCP Cloud Run persistent containers automatically while keeping frontend on Vercel for optimal performance.

### vs Fly.io
Fly.io gives you low-level control over VMs, regions, and scaling. Telbase is higher-level: you run one command and infrastructure decisions are made for you. Fly.io is better if you need multi-region edge compute or fine-grained VM configuration. Telbase is better if you want zero infrastructure decisions.

### vs Self-Hosting (VPS)
A $5/mo Hetzner or DigitalOcean VPS is the cheapest compute available. But you also manage SSL certificates, security patches, OS updates, monitoring, backups, DNS, process management, and scaling. Telbase Starter is also $5/mo — all of that is handled for you, plus framework auto-detection, database provisioning, and AI-native deploy feedback. The sticker price is the same; the total cost of ownership is not. See https://telbase.ai/compare/self-hosting for the full comparison.

### Comparison Table

| Capability | Telbase | Railway | Render | Vercel | Fly.io |
|-----------|---------|---------|--------|--------|--------|
| One-command deploy | Yes | No (manual setup) | No (manual setup) | Yes (frontend) | No (config required) |
| Database auto-provisioned | Yes | No | No | No (add-on) | No |
| AI-native feedback | Yes | No | No | No | No |
| Persistent compute | Yes (GCP Cloud Run) | Yes | Yes | No (serverless only) | Yes |
| Flat monthly pricing | Yes | No (usage-based) | Per-service | Per-seat + usage | Per-VM |
| Deploy via AI conversation | Yes (MCP) | No | No | No | No |
| Full-stack app + DB from $5/mo | Yes (Starter) | ~$12-20/mo | ~$14/mo | ~$20/mo + add-ons | ~$10-15/mo |

### Migrating to Telbase

From any platform:
1. Remove platform-specific config files (railway.toml, fly.toml, render.yaml, vercel.json)
2. Run `npx telbase deploy` — Telbase auto-detects your framework and database
3. Move environment variables: `npx telbase env push` (reads from .env.local)

## Key Features

| Feature | Description |
|---------|-------------|
| Zero Configuration | Auto-detects framework (14 supported), database ORM (Prisma/Drizzle), and SQL dialect (PostgreSQL/SQLite) |
| Multi-Provider Routing | Two-axis routing: compute (Vercel or GCP Cloud Run) + database (Neon, Turso, Cloud SQL) |
| Automatic Database | PostgreSQL or SQLite provisioned when Prisma/Drizzle detected. No manual DB setup. |
| Auto Domains | Every app gets `{slug}.telbase.ai` on first deploy with automatic SSL |
| Custom Domains | `telbase domain add app.acme.com` with automatic Let's Encrypt SSL |
| Built-in Auth | Cloudflare Access SSO: `telbase access enable google --domain=acme.com` |
| GitHub Integration | Auto-deploy on push to main, or deploy from `--repo` URL (public repos) |
| AI-Native Feedback | Deploy responses include AI diagnosis with confidence scoring, auto-fixable code changes, and detection context |
| Scheduled Jobs | Deploy cron jobs with `--schedule`. Pay only for execution time. Cloud Scheduler + Cloud Run Jobs |
| MCP Server | 41 tools for Claude Code integration via `telbase mcp register` |
| Instant Rollback | `telbase rollback` or `telbase rollback <deploy-id>` |
| Environment Variables | Encrypted at rest, synced to provider, `telbase env push/pull` for .env workflow |

## Supported Frameworks — Full Detection Matrix

Telbase auto-detects your framework from config files. Detection priority: specific meta-frameworks first, then bundlers, then plain runtimes, then Docker fallback.

### Tier 1: Meta-Frameworks (highest priority)

| Framework | Config Files | Runtime | Build | Start | Compute |
|-----------|-------------|---------|-------|-------|---------|
| Next.js | `next.config.js`, `next.config.mjs`, `next.config.ts` | Node.js | `npm run build` | `npm start` | Vercel |
| Remix | `remix.config.js`, `remix.config.ts` | Node.js | `npm run build` | `npm start` | Vercel |
| SvelteKit | `svelte.config.js`, `svelte.config.ts` | Node.js | `npm run build` | `node build` | Vercel |
| Astro | `astro.config.mjs`, `astro.config.js`, `astro.config.ts` | Node.js | `npm run build` | `npm start` | Vercel |
| Angular | `angular.json` | Node.js | `npm run build` | `npx serve dist -s` | Vercel |

### Tier 2: Frontend Bundlers

| Framework | Config Files | Runtime | Build | Start | Compute |
|-----------|-------------|---------|-------|-------|---------|
| Vite | `vite.config.js`, `vite.config.ts`, `vite.config.mjs` | Node.js | `npm run build` | `npm run preview` | Vercel |
| Full-Stack | Vite config + backend dep (express/hono/fastify) + start script | Node.js | `npm run build` | `npm start` | Vercel |

### Tier 3: Backend Frameworks

| Framework | Config Files | Runtime | Build | Start | Compute |
|-----------|-------------|---------|-------|-------|---------|
| FastAPI | `main.py` (validated: FastAPI imports) | Python | `pip install -r requirements.txt` | `uvicorn main:app --host 0.0.0.0 --port $PORT` | GCP Cloud Run |
| Django | `manage.py` | Python | `pip install -r requirements.txt` | `gunicorn config.wsgi:application` | GCP Cloud Run |
| Flask | `app.py`, `wsgi.py` | Python | `pip install -r requirements.txt` | `gunicorn app:app` | GCP Cloud Run |
| NestJS | `nest-cli.json` (validated: `@nestjs/core` in deps) | Node.js | `npm run build` | `node dist/main.js` | Vercel |
| Express | `server.js`, `index.js`, `app.js` (validated: express in deps) | Node.js | `npm install` | `npm start` | Vercel |
| Go | `go.mod` | Go | `go build -o app .` | `./app` | GCP Cloud Run |

### Tier 4: Generic / Fallback

| Framework | Config Files | Runtime | Build | Start | Compute |
|-----------|-------------|---------|-------|-------|---------|
| Node.js | `package.json` (with start script) | Node.js | `npm install` | `npm start` | Vercel |
| Static | `index.html` | — | — | — | Vercel |
| Docker | `Dockerfile` | Docker | — | — | GCP Cloud Run |

### Universal: Any Language via Docker (Paid Plans)

Don't see your language in the tiers above? Any framework or language works with Docker on any paid plan (Starter: 1, Builder: 3, Pro: 15):
- Java, Ruby, Rust, PHP, C#, Elixir, Scala, Kotlin — if it runs in a container, it runs on Telbase
- Just add a Dockerfile to your project root — Telbase auto-detects it
- Deployed to GCP Cloud Run with container runtime
- See "Docker Deployment" section below for Dockerfile requirements and examples

### Monorepo / Multi-Service Detection

Telbase auto-detects multi-service projects. It checks for npm/yarn/pnpm workspaces first, then scans subdirectories for framework markers. Services can be in different languages (e.g., TypeScript frontend + Python API + Go worker):
- `cd backend && npx telbase deploy` — deploy backend service
- `cd frontend && npx telbase deploy` — deploy frontend service
- Each service gets its own subdomain (project.telbase.ai, project-api.telbase.ai)
- Only changed services redeploy on GitHub push (file-to-service mapping)

Flags:
- `--service name` — deploy a single service by name or role

### Database Detection

| ORM | Detected Via | Dialect Detection |
|-----|-------------|-------------------|
| Prisma | `@prisma/client` in dependencies | `prisma/schema.prisma` provider field: `sqlite` or `postgresql` |
| Drizzle | `drizzle-orm` in dependencies | Config file: `better-sqlite3`/`@libsql/client` = SQLite, else PostgreSQL |

## Infrastructure Routing — Full Decision Table

Telbase uses two-axis routing. Compute provider is selected from framework/runtime. Database provider is selected from SQL dialect + compute provider.

### Compute Selection

| Framework | Provider | Reason |
|-----------|----------|--------|
| Next.js | Vercel | Zero config, serverless |
| Remix | Vercel | Zero config, serverless |
| SvelteKit | Vercel | Zero config, serverless |
| Astro | Vercel | Zero config, static output |
| Angular | Vercel | Zero config, static output |
| Vite | Vercel | Zero config, static output |
| Full-Stack | Vercel | Zero config, serverless |
| NestJS | Vercel | Zero config, serverless |
| Express | Vercel | Zero config, serverless |
| Node.js | Vercel | Zero config, serverless |
| Static | Vercel | Zero config, CDN |
| Docker | GCP Cloud Run | Custom Dockerfile (from $5/mo) |
| Django | GCP Cloud Run | Persistent containers (Starter $5/mo+) |
| Go | GCP Cloud Run | Persistent containers (Starter $5/mo+) |
| FastAPI | GCP Cloud Run | Python — buildpacks (Starter $5/mo+) |
| Flask | GCP Cloud Run | Python — buildpacks (Starter $5/mo+) |
| `vercel.json` present | Vercel | Explicit user intent (overrides all) |

### Database Selection

| Detected Dialect | Compute | Database Provider | Connection |
|-----------------|---------|-------------------|------------|
| SQLite (Prisma/Drizzle) | Any | Turso | `libsql://` over HTTPS (universal, no private networking needed) |
| PostgreSQL | Vercel | Neon | Serverless Postgres, pooled + direct connections |
| PostgreSQL | GCP | Neon (default) | Serverless Postgres; Cloud SQL via `--database-provider cloud_sql` |
| None detected | Any | None | No database provisioned |

Override with `--database-provider` flag: `neon`, `turso`, `cloud_sql`

### Migration Injection

Telbase auto-detects ORM migrations and injects the migration command into the build process:

| Compute | Injection Method |
|---------|-----------------|
| Vercel | Injected into `buildCommand` (via `vercel.json` or project settings) |
| GCP | `preDeployCommand` (+ devDep reinstall for buildpack deploys) |

Neon migrations use `DATABASE_URL=$DATABASE_URL_UNPOOLED` wrapper to bypass pgBouncer. Turso and Cloud SQL need no wrapper.

## CLI Reference — Full Documentation

### auth

Manage authentication with Telbase.

```bash
telbase auth login          # Browser-based device authorization flow
telbase auth logout         # Clear stored credentials
telbase auth status         # Show current user, org, and token status
```

### deploy

Deploy your application to production. Auto-detects framework, database, and selects infrastructure.

```bash
# Basic usage
npx telbase deploy                        # Deploy from local folder (no Git required)
telbase deploy --repo https://github.com/user/app  # Deploy from GitHub repo (public)

# Provider selection
telbase deploy --provider vercel          # Force compute provider (vercel, gcp)
telbase deploy --database-provider neon   # Force database provider (neon, turso, cloud_sql)
telbase deploy --auto                     # Skip interactive provider confirmation prompt

# Branch and monorepo
telbase deploy --branch staging           # Deploy specific Git branch
telbase deploy --root-dir frontend        # Subdirectory for monorepos

# Behavior flags
telbase deploy --no-wait                  # Return immediately without waiting for completion
telbase deploy --clear-cache              # Clear build cache before deploying
telbase deploy --no-db                    # Deploy without database even if ORM detected
telbase deploy --database                 # Explicitly request database provisioning
telbase deploy --skip-env-check           # Skip env var detection (for CI/CD)
telbase deploy --force-env-sync           # Force re-sync env vars to provider
telbase deploy --skip-health-check        # Skip post-deploy health verification
telbase deploy --health-timeout 60        # Health check timeout in seconds (default 30)
telbase deploy --health-path /api/health  # Health check endpoint (default /)
telbase deploy --storage                  # Provision R2 object storage for file uploads
telbase deploy --no-storage               # Skip storage even if upload libs detected
telbase deploy --auth user@co.com,@co.com # Restrict access via Cloudflare Access (email or @domain)
telbase deploy --no-auth                  # Disable access control

# Scheduled jobs
telbase deploy --schedule "0 * * * *"    # Deploy as scheduled job (cron)
telbase deploy --schedule "0 9 * * 1-5" --schedule-timezone "America/New_York"  # Weekdays 9 AM ET
```

#### Deploy Response Format

Every deploy returns structured JSON:

```json
{
  "id": "dep_abc123",
  "status": "live",
  "url": "https://my-app.telbase.ai",
  "provider": "vercel",
  "databaseProvider": "neon",
  "detection": {
    "ormType": "prisma",
    "confidence": "high",
    "source": "local_scan",
    "databaseProvider": "neon",
    "warnings": []
  }
}
```

On build failure:

```json
{
  "id": "dep_abc123",
  "status": "failed",
  "errorCode": "BUILD_FAILED",
  "errorMessage": "Build command failed with exit code 1",
  "extractedErrors": ["Module not found: 'next/image'"],
  "detection_context": {
    "ormType": "prisma",
    "confidence": "high",
    "source": "local_scan"
  },
  "suggestions": [
    { "type": "cli_retry", "command": "npx telbase deploy --database-provider turso" },
    { "type": "code_change", "file": "package.json", "description": "Add missing dependency: next" },
    { "type": "user_action", "description": "Install dependencies locally first: npm install" }
  ],
  "aiDiagnosis": {
    "diagnosis": "next/image imported in pages/index.tsx but 'next' not in package.json dependencies",
    "confidence": 0.95,
    "category": "missing_dependency",
    "fixes": [{ "type": "dependency", "description": "npm install next", "autoFixable": true }],
    "fixesAreAlternatives": false,
    "redeployCommand": "telbase deploy"
  }
}
```

### projects

List all projects in your organization.

```bash
telbase projects                    # List active projects
telbase projects --all              # Include recently deleted projects
telbase projects --limit 50         # Show more projects (default 20)
telbase projects --status running   # Filter by status (creating, running, suspended, failed)
```

Aliases: `telbase ps`, `telbase list`

### run

Manually trigger a scheduled job execution.

```bash
telbase run                         # Trigger execution and show result
telbase run --follow                # Trigger and stream execution logs in real-time
```

`--follow` (`-f`): Stream execution logs until the job completes or fails.

### deploys

List and inspect deployments.

```bash
telbase deploys                     # List last 10 deploys
telbase deploys --limit 20          # List last 20 deploys
telbase deploys status <deploy-id>  # Get detailed status of specific deploy
```

Alias: `telbase deployments`

### env

Manage environment variables and secrets. Variables are encrypted at rest and synced to the deployment provider.

```bash
telbase env set KEY=value           # Set one environment variable
telbase env set KEY1=val1 KEY2=val2 # Set multiple at once
telbase env get KEY                 # Get the value of a variable
telbase env list                    # List all variables (values hidden)
telbase env unset KEY               # Remove a variable
telbase env pull                    # Download all env vars to .env.local
telbase env push                    # Upload from .env.local to project
telbase env diff                    # Compare local .env.local vs remote
```

### domain

Manage custom domains with automatic SSL via Let's Encrypt.

```bash
telbase domain add app.acme.com      # Add custom domain, get DNS instructions
telbase domain remove app.acme.com   # Remove custom domain
telbase domain list                  # List all domains with status
telbase domain verify app.acme.com   # Verify DNS configuration
telbase domain primary app.acme.com  # Set as primary domain
telbase domain ssl app.acme.com      # Check SSL certificate status
```

Every app automatically gets a `{slug}.telbase.ai` subdomain on first deploy. Custom domains require a CNAME record pointing to `your-app.telbase.ai`.

### db

Manage the project database. Works with PostgreSQL (Neon, Cloud SQL) and SQLite (Turso).

```bash
# Status and info
telbase db status                   # Show database status and provider
telbase db info                     # Detailed database information (size, connections, etc.)

# Connection
telbase db connect                  # Open interactive psql session
telbase db url                      # Print connection string (DATABASE_URL)

# Queries
telbase db query "SELECT * FROM users LIMIT 10"  # Execute SQL query
telbase db exec                     # Execute raw SQL (interactive)

# Lifecycle
telbase db create                   # Create database for project
telbase db delete                   # Delete database (with confirmation)

# Backups
telbase db backup                   # Create manual backup
telbase db backups                  # List available backups
telbase db restore <backup-id>      # Restore from backup

# Migrations
telbase db migrate                  # Run database migrations
telbase db migrate:status           # Show migration status
telbase db migrate:rollback         # Rollback last migration

# Extensions (PostgreSQL only)
telbase db extensions               # List available Postgres extensions
telbase db enable-extension <name>  # Enable a Postgres extension (e.g. uuid-ossp, pgvector)
```

### access

Manage authentication and access control via Cloudflare Access.

```bash
# Enable/disable
telbase access enable google --domain=acme.com   # Restrict to Google SSO + domain
telbase access enable microsoft --domain=acme.com # Microsoft SSO
telbase access enable github                      # GitHub SSO
telbase access disable                            # Make app public (remove auth)

# Status
telbase access status               # Show current auth configuration

# User management
telbase access allow user@acme.com  # Add email to allowlist
telbase access deny user@acme.com   # Remove email from allowlist
telbase access users                # List active users

# Email domain management
telbase access domain add acme.com     # Allow all emails from domain
telbase access domain remove acme.com  # Remove allowed domain
telbase access domain list             # List allowed domains
```

### logs

View and stream application logs.

```bash
telbase logs                        # Stream live logs (like tail -f)
telbase logs --lines 100            # Show last 100 lines (then exit)
telbase logs --since 1h             # Show logs from last hour (1h, 6h, 24h, 7d)
telbase logs --search "error"       # Filter logs containing search term
telbase logs --level error          # Filter by level (info, warn, error)
telbase logs --build                # Show build logs for last deploy
telbase logs --deploy <deploy-id>   # Show logs for specific deploy
telbase logs --follow               # Follow log output (default: true)
telbase logs --executions           # Execution history for scheduled jobs
```

### rollback

Rollback to a previous successful deployment.

```bash
telbase rollback                    # Rollback to most recent successful deploy
telbase rollback <deploy-id>        # Rollback to specific deploy
telbase rollback --list             # List available rollback targets
telbase rollback --force            # Skip confirmation prompt
```

### team

Manage team members and permissions for your organization.

```bash
telbase team                        # List all team members
telbase team invite user@acme.com --role=developer  # Invite member
telbase team remove user@acme.com   # Remove member
telbase team role user@acme.com --role=admin  # Change role
telbase team permissions            # View/modify permissions
```

### mcp

MCP server integration for Claude Code.

```bash
telbase mcp serve                   # Start MCP server on stdio (used by Claude Code)
telbase mcp register                # Register with Claude Code (writes ~/.claude/mcp.json)
telbase mcp unregister              # Remove from Claude Code
```

### upgrade

Update the Telbase CLI.

```bash
telbase upgrade                     # Download and install latest version from GitHub
telbase upgrade --check             # Check for updates without installing
```

### github

Manage GitHub App integration for automatic deployments on push.

```bash
telbase github connect                                # Install GitHub App
telbase github disconnect                             # Remove GitHub integration
telbase github status                                 # Show connection and link status
telbase github repos                                  # List accessible repositories
telbase github link owner/repo                        # Link repo to current project
telbase github link owner/repo --branch develop       # Link with custom deploy branch
telbase github link owner/repo --root-dir apps/web    # Link with monorepo root directory
telbase github link owner/repo --no-autodeploy        # Link without enabling auto-deploy
telbase github unlink                                 # Unlink repo from project
telbase github autodeploy enable                      # Enable auto-deploy on push
telbase github autodeploy disable                     # Disable auto-deploy on push
telbase github branch develop                         # Change deploy branch
telbase github info                                   # Show link info for current project
telbase github deploys                                # List GitHub-triggered deploys
telbase github deploys --limit 20                     # Show more deploys
```

#### Auto-Deploy on Push

Once a repo is linked, pushes to the configured branch (default: `main`) automatically trigger a deploy. Other branches are ignored. For multi-service projects, Telbase maps changed files to services and only redeploys affected services.

#### Root Directory (Monorepo Support)

Set `--root-dir` when linking to point Telbase at a subdirectory. Only files within this directory are used for framework detection and deployment.

#### Auto-Link from `--repo` Deploy

`telbase deploy --repo https://github.com/user/app` automatically links the repo for push-to-deploy after a successful deploy. Use `--no-link` to skip auto-linking.

#### Preview Environments

Preview environments deploy a unique URL for every pull request:
- **Opt-in**: Enable in the dashboard under Settings > GitHub (toggle "PR Preview Deploys")
- **URL format**: `pr-{N}-{slug}.telbase.ai` (e.g., `pr-42-my-app.telbase.ai`)
- **Triggers**: PR opened, pushed to, or reopened — must target the configured deploy branch
- **PR comment**: Telbase posts/updates a comment with status, branch, commit, and preview link
- **Commit status**: `telbase/preview` check reported on the PR commit
- **Cleanup**: Preview URL removed automatically when PR is closed or merged
- **Limitations**: Vercel single-service projects only. No fork PRs (security). Counts against deploy quota.

#### Dashboard Setup

The dashboard GitHub tab (Settings > GitHub) has three states:
1. **Not connected** — "Connect GitHub" button to install the Telbase GitHub App
2. **Connected, not linked** — Repo selector, deploy branch, root directory, auto-deploy toggle, "Link & Deploy" or "Link Only" buttons
3. **Linked** — Current settings (deploy branch, root directory, auto-deploy, preview environments toggle), deploy history, and unlink option

#### Commit Status

Deploy status reported back to GitHub as commit checks:
- **pending** — build in progress
- **success** — deployed, links to the live URL
- **failure** — build failed, links to build logs

Preview deploys use a separate `telbase/preview` context.

### status

View account overview including plan tier, deploy usage, credit balance, and resource counts.

```bash
telbase status                        # Account overview (plan, deploys, credits)
```

### credits

Manage credit balance for resource overages.

```bash
telbase credits                       # Credit balance
telbase credits add                   # Purchase credits ($5 minimum)
telbase credits auto-refill on        # Enable auto-refill (caps: $10/$20/$40/mo)
telbase credits auto-refill off       # Disable auto-refill
telbase credits history               # Transaction history
```

### service management

Control the lifecycle of deployed services.

```bash
telbase restart                       # Graceful restart of running service
telbase suspend                       # Pause service (saves resources, returns 402)
telbase suspend --force               # Skip confirmation
telbase resume                        # Resume a paused service
telbase scale                         # Scale service resources
telbase cancel                        # Cancel an in-progress deploy
telbase cancel --force                # Skip confirmation
```

### storage

Manage S3-compatible file storage (Cloudflare R2, no egress fees).

```bash
telbase storage create                # Create R2 bucket
telbase storage create --name mybkt   # Custom bucket name
telbase storage status                # Bucket info (size, objects, CORS)
telbase storage credentials           # S3-compatible credentials (masked)
telbase storage credentials --show    # Show unmasked credentials
telbase storage credentials --rotate  # Rotate access keys
telbase storage cors add <origin>     # Allow browser uploads from origin
telbase storage cors remove <origin>  # Remove CORS origin
telbase storage cors list             # List configured CORS origins
telbase storage delete                # Delete bucket (with confirmation)
telbase storage delete --force        # Delete without confirmation
```

Auto-injected env vars: `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`.

### doctor

Run diagnostics to identify common configuration issues.

```bash
telbase doctor                        # Run diagnostics
telbase doctor --fix                  # Attempt to fix issues automatically
```

### config

Manage local project configuration (`.telbase/project.json`).

```bash
telbase config list                   # Show all project config values
telbase config get <key>              # Get a specific config value
telbase config set <key> <value>      # Set a config value
```

### open

Open project URLs in the browser.

```bash
telbase open                          # Open project live URL
telbase open --dashboard              # Open dashboard for this project
telbase open --logs                   # Open logs page
telbase open --github                 # Open linked GitHub repo
```

### Other Commands

```bash
telbase org                         # Manage organization settings
telbase init                        # Initialize project configuration
```

## MCP Server — Full Reference

### Setup

Register the Telbase MCP server for Claude Code:

```bash
telbase mcp register
```

This writes to `~/.claude/mcp.json` (merge-safe, preserves other MCP servers):

```json
{
  "mcpServers": {
    "telbase": {
      "command": "/usr/local/bin/telbase",
      "args": ["mcp", "serve"]
    }
  }
}
```

The command path is automatically resolved to the absolute path of the `telbase` binary. Safe to run multiple times (idempotent).

### All Available Tools (41)

| Category | Tool | Description |
|----------|------|-------------|
| Deploy | `deploy` | Deploy an application. Auto-detects framework and database. |
| Deploy | `get_deploy_status` | Get current deploy status, errors, suggestions. |
| Deploy | `get_deploy_logs` | Get build or container logs. |
| Deploy | `list_deploys` | List recent deploys with status and commit info. |
| Deploy | `cancel_deploy` | Cancel an in-progress deploy. |
| Deploy | `get_app_logs` | Get live runtime logs (not build logs). |
| Project | `list_projects` | List all projects in the organization. |
| Project | `get_project` | Get detailed project info (framework, database, services, domains). |
| Project | `update_project` | Update name, slug, description, or pre-deploy command. |
| Project | `delete_project` | Permanently delete a project and all resources. |
| Service | `check_app_health` | Check if a deployed app is healthy. |
| Service | `restart_service` | Gracefully restart without redeploying. |
| Service | `reset_service` | Delete and recreate a broken provider resource. |
| Service | `suspend_service` | Pause a service (stops traffic). |
| Service | `resume_service` | Resume a suspended service. |
| Env Vars | `set_env_vars` | Set environment variables (encrypted at rest). |
| Env Vars | `list_env_vars` | List environment variables (values masked). |
| Env Vars | `delete_env_var` | Delete an environment variable. |
| Database | `get_database_info` | Get database status, provider, and extensions. |
| Database | `enable_database_extension` | Enable pgvector, PostGIS, pg_trgm, uuid-ossp. |
| Domains | `add_custom_domain` | Add a custom domain with DNS instructions. |
| Domains | `verify_custom_domain` | Verify DNS and activate SSL. |
| Domains | `list_custom_domains` | List domains with verification and SSL status. |
| Domains | `remove_custom_domain` | Remove a custom domain. |
| Rollback | `rollback_deploy` | Instantly rollback to a previous deploy. |
| Rollback | `list_rollback_targets` | List available rollback targets. |
| Jobs | `get_job_executions` | List execution history with status and duration. |
| Jobs | `run_scheduled_job` | Manually trigger a scheduled job. |
| Jobs | `pause_job` | Pause a scheduled job's cron schedule. |
| Jobs | `resume_job` | Resume a paused scheduled job. |
| Jobs | `update_schedule` | Update cron expression or timezone. |
| Storage | `get_storage_info` | Get R2 bucket status and CORS config. |
| Storage | `get_storage_credentials` | Get S3-compatible credentials for code. |
| GitHub | `get_github_status` | Check GitHub connection and auto-deploy settings. |
| GitHub | `connect_github` | Link a repo for auto-deploy on push. |
| GitHub | `toggle_auto_deploy` | Enable or disable auto-deploy. |
| Team | `list_team` | List team members with roles. |
| Team | `invite_member` | Invite a new team member. |
| Org | `list_orgs` | List all organizations. |
| Org | `switch_org` | Switch active organization context. |
| Account | `get_account_status` | Get plan, usage, credits, and quotas. |

The 12 most commonly used tools have detailed input schemas below. All 41 tools have auto-generated JSON schemas discoverable via the MCP protocol.

### Tool: deploy

Deploy an application to production. Auto-detects framework and database. Auto-selects optimal infrastructure.

**Input Schema:**
```json
{
  "directory": "string (optional) — Path to project directory. Defaults to cwd.",
  "repo": "string (optional) — GitHub repository URL. Omit for local file deploy.",
  "provider": "string (optional) — Force compute: vercel or gcp. Auto-detected if omitted.",
  "database_provider": "string (optional) — Force database: neon, turso, cloud_sql. Auto-detected if omitted.",
  "wait": "boolean (optional) — Wait for completion. Default true.",
  "branch": "string (optional) — Git branch. Default main.",
  "root_dir": "string (optional) — Subdirectory for monorepos."
}
```

**Returns:** JSON with `url`, `status`, `provider`, `databaseProvider`, `detection` context. On failure: `errorCode`, `errorMessage`, `extractedErrors[]`, `suggestions[]`. On HTTP 402: user must upgrade plan — do not retry.

### Tool: get_deploy_status

Get current status of a deploy.

**Input Schema:**
```json
{
  "deploy_id": "string (required) — The deploy ID to check."
}
```

**Returns:** `status` (building, live, failed, cancelled), `url`, detection context. On failure: `errorCode`, `errorMessage`, `extractedErrors[]`, `suggestions[]`, `buildLogs`. If status is not terminal (building), poll again after a few seconds.

### Tool: get_deploy_logs

Get build or application logs for a deploy.

**Input Schema:**
```json
{
  "deploy_id": "string (required) — The deploy ID.",
  "log_type": "string (optional) — 'build' or 'container'. Default 'build'."
}
```

**Returns:** Log lines. Use `build` for compilation errors and dependency issues. Use `container` for runtime crashes and request errors.

### Tool: set_env_vars

Set environment variables on a project.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID.",
  "vars": "object (required) — Key-value pairs of environment variables."
}
```

**Returns:** Confirmation. Use before deploying if the app needs DATABASE_URL, API keys, or service config. Variables persist across deploys and are encrypted at rest.

### Tool: list_projects

List all projects in the current organization.

**Input Schema:**
```json
{}
```

**Returns:** Array of projects with `id`, `name`, `slug`, `status`, `url`, `provider`, `databaseProvider`. Use to find project IDs for other tools.

### Tool: enable_database_extension

Enable a PostgreSQL extension on a project's database.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID.",
  "extension": "string (required) — Extension name: pgvector, uuid-ossp, pg_trgm, postgis, hstore, citext.",
  "dimension": "number (optional) — Vector dimension for pgvector. Presets: 1536 (OpenAI), 768 (Cohere), 384 (MiniLM). Max 2000 for HNSW/IVFFlat indexes."
}
```

**Returns:** Confirmation with extension status. If pgvector, includes index type recommendation based on dimension.

### Tool: add_custom_domain

Add a custom domain to a deployed project.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID.",
  "domain": "string (required) — The custom domain (e.g. app.acme.com)."
}
```

**Returns:** DNS instructions with CNAME target. The user must add a CNAME record at their DNS provider pointing to `{slug}.telbase.ai`.

### Tool: verify_custom_domain

Verify DNS configuration for a custom domain.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID.",
  "domain": "string (required) — The custom domain to verify."
}
```

**Returns:** Verification status (`verified` or `pending`). If pending, includes the expected CNAME target and current DNS state. SSL is provisioned automatically once verified.

### Tool: list_custom_domains

List all custom domains for a project.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID."
}
```

**Returns:** Array of domains with `domain`, `status` (verified/pending/failed), `sslStatus`, and `createdAt`.

### Tool: remove_custom_domain

Remove a custom domain from a project.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID.",
  "domain": "string (required) — The custom domain to remove."
}
```

**Returns:** Confirmation. The CNAME record at the DNS provider can be removed after this.

### Tool: get_job_executions

List execution history for a scheduled job.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID.",
  "limit": "number (optional) — Max executions to return (default: 10, max: 50)."
}
```

**Returns:** Array of executions with `executionId`, `status` (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), `startTime`, `completionTime`, `exitCode`. Also includes `schedule` with `cronExpression`, `timezone`, `status`.

### Tool: run_scheduled_job

Manually trigger a scheduled job execution outside its normal schedule.

**Input Schema:**
```json
{
  "project_id": "string (required) — The project ID."
}
```

**Returns:** `executionName` for polling status via `get_job_executions`.

### Example Prompts

| Prompt | Tool Used | Notes |
|--------|-----------|-------|
| "Deploy my current project to Telbase" | `deploy` | Uses cwd as directory |
| "Deploy github.com/user/repo to Telbase" | `deploy` | Pass as `repo` parameter |
| "Check if my deploy finished" | `get_deploy_status` | Pass deploy ID |
| "Show me the build logs" | `get_deploy_logs` | `log_type=build` |
| "Why did my deploy fail?" | `get_deploy_logs` | Check build logs for errors |
| "Set DATABASE_URL on my project" | `set_env_vars` | Pass project_id + vars |
| "List all my Telbase projects" | `list_projects` | No parameters needed |
| "Enable pgvector on my database" | `enable_database_extension` | Pass extension="pgvector" |
| "Add app.acme.com to my project" | `add_custom_domain` | Returns CNAME instructions |
| "Check if my domain DNS is set up" | `verify_custom_domain` | Check after CNAME added |
| "List my custom domains" | `list_custom_domains` | Shows all with status |
| "Deploy this Java app with Docker" | `deploy` | Auto-detects Dockerfile |

## Pricing — Full Breakdown

| Feature | Free $0 | Starter $5/mo | Builder $19/mo | Pro $79/mo |
|---------|---------|---------------|----------------|------------|
| **Websites** (static sites) | 10 | Unlimited | Unlimited | Unlimited |
| **Apps** (full-stack) | 1 sandbox | 2 | 5 | 15 |
| **Databases** | 1 sandbox | 2 (SQLite or PostgreSQL) | 5 | 15 |
| **Docker containers** | -- | 1 app | 3 apps | 15 apps |
| **Deploys** | 5/mo | 30/mo | 150/mo | 500/mo |
| **Custom domains** | -- | 1 | 5 | Unlimited |
| **Team** (members) | 1 | Unlimited | Unlimited | Unlimited |
| **GCP Cloud Run** | -- | Yes | Yes | Yes |
| **Always On** | -- | Add-on | Add-on | 1 included |
| **Auto subdomain** | `{slug}.telbase.ai` | `{slug}.telbase.ai` | `{slug}.telbase.ai` | `{slug}.telbase.ai` |
| **HTTPS** | Automatic | Automatic | Automatic | Automatic |
| **Support** | Community | Email | Email | Priority |

### What counts as a "Website" vs "App"?

- **Website**: Static site with no database (Angular, Vite, Astro, Static HTML). Deployed to Vercel CDN.
- **App**: Full-stack application with server-side code and/or database. Requires Starter plan or above.

### Database Types

- **SQLite**: Managed by Turso. Universal — works with any compute provider via HTTPS. Cheapest option.
- **PostgreSQL**: Managed by Neon (default for Vercel and GCP) or Cloud SQL (explicit GCP override). Capped per tier to control costs.

### Upgrade on HTTP 402

When a deploy or resource creation hits a plan limit, the API returns HTTP 402. The response includes the specific limit exceeded. Do not retry — the user must upgrade their plan at `https://app.telbase.ai/billing`.

## Error Handling — Full Reference

### Common Errors

| Error | Code | Cause | Solution |
|-------|------|-------|----------|
| Not authenticated | `AUTH_REQUIRED` | No valid token | Run `telbase auth login` |
| Project not found | `PROJECT_NOT_FOUND` | Wrong project ID or not linked | Run `telbase projects` to list |
| Framework not detected | `FRAMEWORK_NOT_DETECTED` | Missing config file | Add framework config (next.config.js, etc.) or Dockerfile |
| Build failed | `BUILD_FAILED` | Code compilation errors | Check `telbase logs --build`, fix code, redeploy |
| Plan limit reached | `402` | Exceeded tier quota | Upgrade at app.telbase.ai/billing |
| Domain verification failed | `DOMAIN_VERIFY_FAILED` | DNS not propagated | Wait 5-10 min, re-run `telbase domain verify` |
| Unsupported database | `UNSUPPORTED_DB` | MongoDB, MySQL, etc. detected | Telbase supports PostgreSQL and SQLite only |
| Provider access denied | `PROVIDER_ACCESS_DENIED` | Tier doesn't allow this provider | Upgrade plan or use a different provider |
| Deploy quota exceeded | `DEPLOY_QUOTA_EXCEEDED` | Monthly deploy limit reached | Upgrade to Builder ($19) for unlimited |
| Database quota exceeded | `DATABASE_QUOTA_EXCEEDED` | Max databases for tier | Upgrade plan or delete unused databases |

### AI-Native Feedback Protocol

Telbase's competitive moat is that the AI agent (Claude Code) is the primary consumer of all deploy outputs — not humans. Every platform decision (detection, routing, provisioning, migration) is visible in structured JSON responses.

#### Detection Context

Every deploy response includes detection metadata:

```json
{
  "detection": {
    "ormType": "prisma",
    "confidence": "high",
    "source": "local_scan",
    "databaseProvider": "neon",
    "computeProvider": "vercel",
    "framework": "nextjs",
    "warnings": []
  }
}
```

Fields:
- `ormType`: Detected ORM (`prisma`, `drizzle`, or empty)
- `confidence`: `high` (config file found), `medium` (dependency only), `low` (inferred)
- `source`: `local_scan`, `github_api`, `github_raw`, `explicit_flag`
- `databaseProvider`: Selected database provider
- `computeProvider`: Selected compute provider
- `framework`: Detected framework
- `warnings`: Any detection warnings

#### Suggestion Types

On build failure, the response includes `suggestions[]`. Each suggestion has a type:

| Type | Meaning | Example |
|------|---------|---------|
| `cli_retry` | Run this command to fix the issue | `npx telbase deploy --database-provider turso` |
| `code_change` | Modify this source file | `{ "file": "prisma/schema.prisma", "description": "Change provider to sqlite" }` |
| `user_action` | Human action required | `Connect GitHub App for private repo detection` |

#### AI Diagnosis (Deploy Intelligence)

On failure, the response may include `aiDiagnosis` — an AI-generated root cause analysis powered by Claude. The platform reads your build logs and source code to identify the exact failure cause.

**AIDiagnosis schema:**
- `diagnosis` (string): One-paragraph root cause explanation referencing specific files
- `confidence` (number 0-1): Reliability score. Auto-apply fixes at >= 0.7
- `category` (enum): `missing_dependency`, `env_var`, `config`, `code_error`, `infrastructure`, `migration`, `port_binding`, `memory`, `misclassification`, `provider_degraded`, `unknown`
- `fixes[]`: Ordered list of fixes, each with:
  - `type`: `code_change`, `env_var`, `dependency`, `config`, `command`
  - `description`: What to do
  - `file` (optional): Exact file path for code_change/config types
  - `details` (optional): Additional context (e.g., where in the file to add code)
  - `autoFixable`: true if the agent can apply without human input; false for secrets/env vars
- `fixesAreAlternatives` (boolean): true = pick the best fix; false = apply all in order
- `redeployCommand` (string, optional): Exact telbase CLI command with flag overrides

**Agent guidance:**
- confidence >= 0.7: auto-apply each fix where `autoFixable: true`
- confidence 0.5-0.7: display diagnosis for context, don't auto-apply
- `autoFixable: false`: prompt the user (e.g., secret env vars)
- Use `redeployCommand` if provided (includes classification overrides like `--provider gcp`)
- If `fixesAreAlternatives: true`: apply only the first auto-fixable fix
- If `aiDiagnosis` is absent: fall back to `suggestions[]` and `extractedErrors[]`

#### Self-Healing Loop

The intended flow:

1. Claude Code runs `npx telbase deploy`
2. Deploy fails with structured error + AI diagnosis
3. Claude Code reads `aiDiagnosis` (confidence >= 0.7) or `suggestions[]`:
   - `autoFixable: true`: Apply the fix automatically
   - `autoFixable: false`: Tell the user what to do
   - `cli_retry`: Immediately retry with suggested parameters
   - `code_change`: Modify the file, then redeploy
   - `user_action`: Human action required
4. Redeploy succeeds (typically in 1 retry with AI diagnosis)

This loop works because Telbase controls both sides of the feedback — the platform generates the error, and the AI agent consumes it. Other platforms (Vercel, Render, Netlify) can't replicate this because their errors are designed for human developers.

## Database Providers — Detailed Reference

For users of `--database-provider` flag or MCP `database_provider` parameter.

### Turso (SQLite)

- Managed SQLite via libSQL protocol
- Connection: `libsql://` over HTTPS (works with any compute provider)
- Env vars set automatically: `DATABASE_URL`, `DATABASE_AUTH_TOKEN`, `TURSO_DATABASE_URL`, `TURSO_AUTH_TOKEN`
- Prisma: Auto-transforms `schema.prisma` for libSQL adapter (via Telbase's transform engine)
- Best for: Simple apps, prototypes, lowest cost

### Neon (PostgreSQL)

- Serverless PostgreSQL
- Connection: Pooled (`DATABASE_URL`) + direct (`DATABASE_URL_UNPOOLED`) connections
- Scale-to-zero enforced on all tiers (cost control)
- Native to Vercel deployments (private networking)
- Best for: Vercel apps that need PostgreSQL

### Cloud SQL (PostgreSQL)

- Google Cloud managed PostgreSQL
- Connection: Private network within GCP
- Available via `--database-provider cloud_sql` with `--provider gcp`
- Best for: Enterprise GCP deployments needing VPC peering

## REST API Reference

Base URL: https://api.telbase.ai
Authentication: Authorization: Bearer sk_live_<your-api-key>

Response envelope: { "success": true, "data": {...} }
Error envelope:    { "success": false, "error": { "code": "...", "message": "..." } }
Pagination:        ?limit=50&offset=0 → { "pagination": { "total", "limit", "offset", "hasMore" } }

### Projects

POST /projects — Create project
  Body: { "name": "my-app", "framework": "nextjs", "provider": "vercel" }
  Response (201): { "success": true, "data": { "id": "...", "name": "my-app", "slug": "my-app", "url": "https://my-app.telbase.ai", "status": "creating" } }

GET /projects — List projects
  Query: ?limit=50&offset=0&status=running&includeDeleted=false
  Response (200): { "success": true, "data": [...], "pagination": { "total": 10, "limit": 50, "offset": 0, "hasMore": false } }

GET /projects/:id — Get project details (accepts UUID or slug)
  Response (200): { "success": true, "data": { "id", "name", "slug", "status", "provider", "framework", "url", "database", "domains", "latestDeploy", "services", "stats" } }

PATCH /projects/:id — Update project
  Body: { "name": "new-name", "framework": "vite", "preDeployCommand": "npx prisma migrate deploy", "provider": "gcp", "force": true }
  Response (200): { "success": true, "data": { ...updated project } }
  Note: changing provider on deployed project requires "force": true

DELETE /projects/:id — Delete project
  Response (200): { "success": true, "data": { "id", "status": "deleting", "cleanup": { "steps": [...] } } }

POST /projects/:id/services — Create service (multi-service projects)
  Body: { "name": "API", "slug": "api", "serviceRole": "backend", "provider": "gcp", "path": "packages/api" }
  Response (201): { "success": true, "data": { "id", "name", "slug", "serviceRole", "status": "creating" } }

GET /projects/:id/services — List services
  Response (200): { "success": true, "data": [{ "id", "name", "slug", "serviceRole", "provider", "status" }] }

### Deployments

POST /projects/:id/deploys — Start deploy (async, returns 202)
  Body: { "source": "github", "repoUrl": "https://github.com/user/app", "branch": "main", "provisionDatabase": true, "databaseProvider": "neon" }
  Response (202): { "success": true, "data": { "id", "status": "building", "url", "decisions": [...], "nextSteps": [...], "detection": { "ormType", "confidence", "framework", "databaseProvider" } } }

POST /projects/:id/deploys/upload — Upload tarball and deploy (multipart/form-data, max 100MB)
  Used by CLI for local deploys. Most agents should use the GitHub source endpoint above.

GET /projects/:id/deploys — List deploys
  Query: ?page=1&perPage=10&serviceId=<uuid>
  Response (200): { "success": true, "data": [...], "pagination": { "total", "page", "perPage", "hasMore" } }

GET /deploys/:id — Get deploy status (primary polling endpoint)
  Response (200): { "success": true, "data": { "id", "status", "url", "detection", "healthCheck", "createdAt", "finishedAt" } }
  On failure: includes "errorCode", "extractedErrors", "suggestions": [{ "type": "cli_retry"|"code_change"|"user_action", ... }]

GET /deploys/:id/logs — Get build logs
  Response (200): { "success": true, "data": { "logs": [{ "timestamp", "message" }] } }

GET /deploys/:id/stream — Stream logs via SSE (supports ?token= for EventSource auth)
  Sends heartbeat every 30s. Closes on terminal state.

POST /deploys/:id/cancel — Cancel in-progress deploy
  Response (200): { "success": true, "data": { "id", "status": "cancelled" } }

GET /projects/:id/rollback-targets — List rollback targets
  Query: ?serviceId=<uuid>
  Response (200): { "success": true, "data": [{ "id", "status": "live", "commitSha", "createdAt" }] }

POST /projects/:id/rollback — Rollback to previous deploy
  Response (202): { "success": true, "data": { "id", "status": "building", "rollbackTo": "dep_..." } }

POST /projects/:id/rollback/:deployId — Rollback to specific deploy
  Response (202): { "success": true, "data": { "id", "status": "building", "rollbackTo": "dep_..." } }

POST /projects/:projectId/rollback-all — Rollback all services (multi-service)
  Response (202): { "success": true, "data": { "rollbacks": [{ "serviceId", "deployId", "status" }] } }

POST /projects/:projectId/redeploy-all — Redeploy all services (multi-service)
  Response (202): { "success": true, "data": { "deploys": [{ "serviceId", "deployId", "status" }] } }

### Environment Variables

POST /projects/:id/env — Set variables (bulk upsert, 1-100 per call)
  Body: { "vars": [{ "key": "DB_URL", "value": "...", "isSecret": true }], "serviceId": "<uuid>" }
  Response (200): { "success": true, "data": { "created": [...], "updated": [...], "unchanged": [...] } }

GET /projects/:id/env — List variables (secrets masked unless ?show=true)
  Query: ?show=true&serviceId=<uuid>
  Response (200): { "success": true, "data": { "vars": [{ "key", "value", "isSecret" }], "count": 5 } }

GET /projects/:id/env/:key — Get single variable value
  Response (200): { "success": true, "data": { "key": "DB_URL", "value": "postgresql://..." } }

DELETE /projects/:id/env/:key — Delete variable
  Query: ?serviceId=<uuid>
  Response (200): { "success": true, "data": { "message": "Variable 'DB_URL' deleted" } }

POST /projects/:id/env/generate — Auto-generate secrets (JWT_SECRET, SESSION_SECRET, etc.)
  Response (200): { "success": true, "data": { "generated": ["JWT_SECRET", "SESSION_SECRET"], "message": "2 secrets generated" } }

POST /projects/:id/env/diff — Compare local vs remote variables
  Body: { "vars": [{ "key": "DB_URL", "value": "localhost:5432/dev" }] }
  Response (200): { "success": true, "data": { "added": [...], "removed": [...], "changed": [...], "unchanged": [...], "hasChanges": true } }

### Permissions

API keys support scoped permissions with wildcards:
- project.list, project.create, project.delete, project.settings
- deploy.create, deploy.cancel, deploy.rollback, deploy.logs.read
- env.list, env.values.read, env.write
- db.status, db.create, db.connection, db.query
- domain.list, domain.create, domain.delete
- Wildcard: deploy.* matches all deploy permissions

### Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| VALIDATION_ERROR | 400 | Invalid request body or parameters |
| AUTH_REQUIRED | 401 | Missing or invalid token |
| LIMIT_EXCEEDED | 402 | Plan quota exceeded — upgrade required |
| PERMISSION_DENIED | 403 | API key lacks required scope |
| NOT_FOUND | 404 | Resource not found |
| CONFLICT | 409 | Resource already exists |
| DEPLOY_FAILED | 500 | Provider-level failure |

Full API documentation: https://telbase.ai/docs/api

## Docker Deployment (Paid Plans)

Any language or framework works with Docker. Available on all paid plans. Starter: 1, Builder: 3, Pro: 15.

### Requirements
- Container MUST listen on the PORT environment variable (injected at runtime by Telbase)
- Telbase auto-detects `Dockerfile` in your project root or subdirectory

### Deploy Command
npx telbase deploy              # auto-detects Dockerfile
npx telbase deploy ./backend    # deploy a subdirectory with Dockerfile
npx telbase deploy --provider gcp  # explicit GCP (Docker always uses GCP)

### ENTRYPOINT / CMD Pitfall

Exec form does NOT expand environment variables:

# WRONG — $PORT is not expanded in exec form
ENTRYPOINT ["java", "-jar", "app.jar", "--server.port=$PORT"]

# RIGHT — shell form expands $PORT
CMD java -jar app.jar --server.port=$PORT

# RIGHT — explicit shell wrapper
ENTRYPOINT ["/bin/sh", "-c", "java -jar app.jar --server.port=$PORT"]

### Build Context
When deploying from a subdirectory (npx telbase deploy ./backend), the build context is ./backend. All COPY/ADD paths are relative to that directory, not the repo root.

### Example Dockerfiles

#### Java / Spring Boot (Maven)
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
CMD java -jar app.jar --server.port=$PORT

#### Ruby / Rails
FROM ruby:3.3
WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
RUN bundle exec rake assets:precompile
CMD bundle exec puma -p $PORT

#### Rust
FROM rust:1.77 AS build
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=build /app/target/release/myapp /usr/local/bin/
CMD myapp --port $PORT

#### PHP / Laravel
FROM php:8.3-cli
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev
COPY . .
CMD php artisan serve --host=0.0.0.0 --port=$PORT

### Migrating from Other Platforms
- Remove platform-specific config (railway.toml, fly.toml, render.yaml) — Telbase ignores these files
- Replace hardcoded ports with $PORT
- Move secrets to Telbase: npx telbase env set KEY=value
- Health check defaults to GET / on PORT; customize with --health-path flag

### Common Issues
| Issue | Cause | Fix |
|-------|-------|-----|
| Container exits immediately | Not listening on $PORT | Add CMD with $PORT in shell form |
| Build fails on COPY | Wrong build context | Check deploy directory — COPY paths are relative to it |
| Port mismatch | Hardcoded port number | Use $PORT environment variable |
| Native deps missing | Alpine base image | Use debian-based image or install deps |

## Multi-Service / Monorepo Deployment

Deploy frontend + backend (or more) as separate services. Each gets its own subdomain. Services can be in different languages.

### How It Works
1. Telbase checks for workspace configuration (npm/yarn/pnpm workspaces)
2. If no workspaces found, scans subdirectories for framework markers (package.json, requirements.txt, go.mod, Dockerfile)
3. Each service is analyzed independently (framework, database, dependencies)
4. Deploy each service from its directory — each gets its own subdomain

### Directory Structure Example
my-project/
├── frontend/          # Vite detected → Vercel (project.telbase.ai)
│   ├── package.json
│   └── vite.config.ts
└── api/               # FastAPI detected → GCP Cloud Run (project-api.telbase.ai)
    ├── requirements.txt
    └── main.py
# No workspace config needed — subdirectory scanning detects both services

### Routing
- Frontend: your-project.telbase.ai → Vercel
- Backend: your-project-api.telbase.ai → appropriate provider
- Each service gets its own subdomain automatically

### Commands
cd frontend && npx telbase deploy    # deploy frontend
cd api && npx telbase deploy         # deploy API
npx telbase deploy --service api     # deploy one service by name

### Environment Variables
npx telbase env set API_URL=https://your-project-api.telbase.ai --service frontend  # Use framework-correct name
npx telbase env set DATABASE_URL=... --service backend

### Common Patterns
| Frontend | Backend | Notes |
|----------|---------|-------|
| Vite + React | FastAPI | Set VITE_API_URL to backend subdomain |
| Next.js | Express | Set NEXT_PUBLIC_API_URL to backend subdomain |
| SvelteKit | Go | Go auto-detected from go.mod |
| Vite + React | Docker (Java) | Backend needs paid plan for Docker |

## Documentation

- Quick Start: https://telbase.ai/docs
- Supported Frameworks: https://telbase.ai/docs/frameworks
- Plans & Usage: https://telbase.ai/docs/plans-and-usage
- Databases: https://telbase.ai/docs/databases
- Vector Search & RAG: https://telbase.ai/docs/vector-search
- File Storage: https://telbase.ai/docs/storage
- Custom Domains: https://telbase.ai/docs/custom-domains
- Docker Containers: https://telbase.ai/docs/docker
- Full-Stack & Monorepos: https://telbase.ai/docs/full-stack
- GitHub Integration: https://telbase.ai/docs/github
- Environment Variables: https://telbase.ai/docs/environment-variables
- SSO & Access Control: https://telbase.ai/docs/sso
- Project Configuration: https://telbase.ai/docs/config
- Claude Code Integration: https://telbase.ai/docs/claude-code
- CLI Reference: https://telbase.ai/docs/cli
- Troubleshooting: https://telbase.ai/docs/troubleshooting
- API Reference: https://telbase.ai/docs/api
- API — Projects: https://telbase.ai/docs/api/projects
- API — Deployments: https://telbase.ai/docs/api/deployments
- API — Environment Variables: https://telbase.ai/docs/api/env
- Compare Platforms: https://telbase.ai/compare
- Telbase vs Railway: https://telbase.ai/compare/railway
- Telbase vs Render: https://telbase.ai/compare/render
- Telbase vs Vercel: https://telbase.ai/compare/vercel
- Telbase vs Fly.io: https://telbase.ai/compare/fly-io

## About

Telbase is built for the era of AI-assisted development. Non-technical professionals describe what they need, Claude Code writes the app, and Telbase handles all infrastructure automatically.

- Website: https://telbase.ai
- npm: https://www.npmjs.com/package/telbase
- Support: victor@telbase.ai