Project Configuration

Telbase stores project configuration in .telbase/config.json. This file is created automatically on your first deploy and tracks project identity, service mappings, and change detection hashes.

File Location

The config file lives at .telbase/config.json in your project root. It is created automatically when you run telbase deploy or telbase init for the first time.

Add to .gitignore

The .telbase/ directory contains deploy-specific state (project IDs, hashes) that is local to your machine. Add it to your .gitignore:

bash

# .gitignore
.telbase/

Config Schema

The config file is a JSON object with the following fields:

json

{
  "project_id": "proj_abc123",
  "project_slug": "my-app",
  "org_id": "org_xyz789",
  "services": [
    {
      "service_id": "svc_001",
      "name": "frontend",
      "path": "apps/web",
      "service_role": "frontend",
      "framework": "nextjs",
      "provider": "vercel",
      "last_deploy_hash": "a1b2c3d4..."
    }
  ],
  "schedule": "0 * * * *",
  "schedule_timezone": "America/New_York"
}

Top-level fields

project_id — unique project identifier assigned by Telbase
project_slug — URL slug used in your .telbase.ai subdomain
org_id — your organization identifier
services — array of service configurations (present in multi-service projects)
schedule — cron expression for scheduled jobs (set via --schedule flag, persisted for redeploys)
schedule_timezone — IANA timezone for the schedule (default: UTC)

Multi-Service Config

For projects with multiple services (monorepos, full-stack apps), the services array tracks each service independently.

Service fields

service_id — unique service identifier
name — display name (e.g., “frontend”, “api”)
path — relative path from project root to the service directory
service_role — frontend, backend, or worker
framework — detected framework (e.g., nextjs, fastapi, vite)
provider — compute provider (vercel or gcp)
last_deploy_hash — content hash from the last successful deploy (used for change detection)

Change Detection

Telbase uses content hashing to skip unchanged services during multi-service deploys. After each successful deploy, a hash of the service directory is stored in last_deploy_hash.

On the next deploy, Telbase compares the current directory hash against the stored hash. If they match, the service is skipped.

bash

# Default: deploy from current directory
telbase deploy

# Deploy a specific service by name
telbase deploy --service api

Hash scope

Content hashing covers all files in the service directory, excluding node_modules, .git, and build output directories. Changing any source file, config file, or dependency lock file triggers a redeploy on GitHub push.

Subdirectory Deploys

When you deploy from a subdirectory (e.g., apps/web/), Telbase walks up the directory tree to find the nearest .telbase/config.json. This means you can run telbase deploy from any service directory in a monorepo without navigating to the project root.

bash

# These are equivalent in a monorepo:
cd my-monorepo && telbase deploy
cd my-monorepo/apps/web && telbase deploy

CLI Flag Overrides

CLI flags override config values for a single deploy. These overrides are ephemeral and are not written back to the config file.

bash

# Override compute provider for this deploy
telbase deploy --provider gcp

# Override database provisioning
telbase deploy --database postgresql

# Use pre-built static deploy (skips remote build)
telbase deploy --prebuilt

# Skip pre-built even if auto-detected
telbase deploy --no-prebuilt

Examples

Single-service Next.js app

json

{
  "project_id": "proj_abc123",
  "project_slug": "my-dashboard",
  "org_id": "org_xyz789"
}

Multi-service monorepo (Vite + FastAPI)

json

{
  "project_id": "proj_def456",
  "project_slug": "valuation-model",
  "org_id": "org_xyz789",
  "services": [
    {
      "service_id": "svc_001",
      "name": "frontend",
      "path": "frontend",
      "service_role": "frontend",
      "framework": "vite",
      "provider": "vercel",
      "last_deploy_hash": "e5f6a7b8c9d0..."
    },
    {
      "service_id": "svc_002",
      "name": "api",
      "path": "backend",
      "service_role": "backend",
      "framework": "fastapi",
      "provider": "gcp",
      "last_deploy_hash": "1a2b3c4d5e6f..."
    }
  ]
}

Next Steps

Full-Stack & Monorepos — deploying multi-service projects
CLI Reference — all deploy flags and options
Supported Frameworks — auto-detected frameworks and routing