Skip to main content
The Tinybird TypeScript SDK supports local development mode using a Docker container, allowing you to develop and test without affecting your cloud workspace.

​
Overview

Local development mode uses the tinybird-local Docker container to run a full Tinybird instance on your machine. This provides:
  • Offline development - Work without internet connection
  • Isolated testing - No impact on cloud workspace
  • Faster iteration - No network latency
  • Branch isolation - Automatic workspace per git branch
  • Zero configuration - Tokens automatically managed

​
Quick Start

​
1. Start the Container

Run the Tinybird local container: 
docker run -d -p 7181:7181 --name tinybird-local tinybirdco/tinybird-local:latest
This starts a Tinybird instance on http://localhost:7181.

​
2. Configure Local Mode

Set devMode to "local" in your config:
tinybird.config.json
{
  "include": ["src/tinybird/datasources.ts", "src/tinybird/pipes.ts"],
  "token": "${TINYBIRD_TOKEN}",
  "baseUrl": "https://api.tinybird.co",
  "devMode": "local"
}

​
3. Start Development

Run the dev command: 
npx tinybird dev
Or use the --local flag to override config: 
npx tinybird dev --local

​
How Local Mode Works

When devMode: "local" is configured:
  1. Automatic tokens - The SDK obtains tokens from the local container (no cloud auth needed)
  2. Branch workspaces - A workspace is created per git branch automatically
  3. Local URL - Requests go to http://localhost:7181 instead of cloud API
  4. Full features - All Tinybird features work locally
Local mode requires Docker to be installed and running on your machine.

​
Development Workflow

​
Watch Mode

Use dev to watch for changes and sync automatically: 
npx tinybird dev --local
This:
  • Watches your resource files for changes
  • Automatically syncs to local container
  • Validates schemas and SQL
  • Reports errors in real-time

​
Build Mode

Build and push resources once: 
npx tinybird build --local
Add --dry-run to preview without pushing: 
npx tinybird build --local --dry-run

​
Branch Isolation

Local mode creates a separate workspace for each git branch: 
# On branch: feature/new-dashboard
npx tinybird dev --local
# Creates workspace: feature_new_dashboard

# Switch branch
git checkout main
npx tinybird dev --local
# Uses workspace: main
This allows you to:
  • Test different features simultaneously
  • Isolate experimental changes
  • Avoid conflicts between branches

​
Switching Between Local and Cloud

You can switch between local and cloud mode using CLI flags: 
# Use local container
npx tinybird dev --local

# Use cloud with branches
npx tinybird dev --branch
The CLI flag overrides the devMode setting in your config file.

​
Container Management

​
Check Container Status

docker ps
Look for tinybird-local in the output.

​
Stop Container

docker stop tinybird-local

​
Start Existing Container

docker start tinybird-local

​
Remove Container

docker rm -f tinybird-local

​
View Container Logs

docker logs tinybird-local

​
Access Container Shell

docker exec -it tinybird-local /bin/bash

​
Querying Local Data

Your application code works with local mode without changes: 
import { tinybird } from "@tinybird/client";

// Queries local container when devMode is "local"
const result = await tinybird.topPages.query({
  start_date: "2024-01-01 00:00:00",
  end_date: "2024-01-31 23:59:59",
});
The SDK automatically uses http://localhost:7181 when in local mode.

​
Inspecting Local Workspace

Use the info command to see local workspace details: 
npx tinybird info
Output includes:
  • Local container status
  • Workspace name
  • Token information
  • Branch details
{
  "workspace": {
    "name": "feature_new_dashboard",
    "id": "...",
    "apiHost": "http://localhost:7181"
  },
  "local": {
    "available": true,
    "url": "http://localhost:7181",
    "workspace": "feature_new_dashboard"
  },
  "project": {
    "configPath": "/path/to/tinybird.config.json",
    "devMode": "local"
  }
}

​
Comparing with Cloud Mode

FeatureLocal ModeCloud Mode
Internet requiredNoYes
AuthenticationAutomaticRequired (token)
Branch workspacesAutomaticManual branches
PerformanceFast (local)Network latency
Data persistenceContainer lifetimePermanent
CollaborationNoYes
Production deployNot supportedtinybird deploy

​
When to Use Local Mode

Local development mode is ideal for:

Rapid prototyping

Quick iteration without cloud sync delays

Offline work

Develop without internet connection

Testing

Isolated environment for experiments

CI/CD

Local testing in pipelines

​
Limitations

Local mode has some limitations:
  • No persistence - Data is lost when container stops (unless using volumes)
  • Single machine - Can’t share with team members
  • No production deploy - Must use cloud mode for production
  • Resource limits - Constrained by local machine resources
Local mode is for development only. Always use cloud mode with tinybird deploy for production deployments.

​
Troubleshooting

​
Container Not Starting

Check if port 7181 is already in use: 
lsof -i :7181
Use a different port if needed: 
docker run -d -p 8181:7181 --name tinybird-local tinybirdco/tinybird-local:latest

​
Connection Errors

Verify the container is running: 
docker ps | grep tinybird-local
Check container logs: 
docker logs tinybird-local

​
Workspace Not Found

Ensure you’re in a git repository with a valid branch: 
git branch --show-current
Local mode creates workspaces based on git branch names.

​
Next.js Integration

Run both Next.js and Tinybird in local mode:
package.json
{
  "scripts": {
    "dev": "concurrently -n next,tinybird \"next dev\" \"tinybird dev --local\""
  }
}
This starts both servers together, with Tinybird using the local container.

​
Transitioning to Production

When ready to deploy:
  1. Switch to branch mode: 
    {
  "devMode": "branch"
}
  2. Test on a cloud branch: 
    git checkout -b staging
npx tinybird build
  3. Deploy to production: 
    git checkout main
npx tinybird deploy
Your TypeScript definitions work identically in both modes.

Build docs developers (and LLMs) love

Get started for freeTalk to us