Tinybird Local container

You can run your own Tinybird instance locally using the tinybird-local container.

The Tinybird Local container is useful in CI/CD pipelines. See CI/CD for more information. You can also deploy it on your own cloud infrastructure.

Prerequisites

To get started, you need a container runtime, like Docker or OrbStack. OrbStack containers do not require any additional configuration to run Tinybird Local. Docker users need to make the following adjustments:

  • Enable Rosetta: To run Tinybird Local on Docker with Apple Silicon, you must enable Rosetta. Without it, Docker falls back to QEMU emulation, which can cause poor performance and unstable container behavior. Docker Desktop users need to enable Rosetta manually. Find the setting in Docker Desktop > Settings > General > Use Rosetta for x86/amd64 emulation on Apple Silicon.

  • Increase Memory: Change the default memory to 8 GB in Docker Desktop > Settings > Advanced > Memory.

Run the Tinybird Local container

To run Tinybird locally, run the following command:

docker run --platform linux/amd64 -p 7181:7181 --name tinybird-local -d tinybirdco/tinybird-local:latest

By default, Tinybird Local runs on port 7181, although you can expose it locally using any other port.

API endpoints

By default, the Tinybird Local container exposes the following API endpoint:

  • http://localhost:7181/v0/

You can call all the existing Tinybird API endpoints locally. For example:

```shell
curl \
      -X POST 'http://localhost:7181/v0/events?name=<your_datasource>' \
      -H "Authorization: Bearer <your_token>" \
      -d $'<your_data>'

Persist data between sessions

To persist your data between development sessions, you can specify a custom path for storing your data volumes with the --volumes-path flag:

tb local start --volumes-path <your/path>

This ensures your data persists between restarts, making local development more efficient and reliable.

Remember that tb local stop does not remove the data. tb local restart does, so to get to an earlier state you can do tb local restart --volumes-path ./tb_previous_snapshot

Docker Compose

If you run the Tinybird Local container using Docker Compose instead of the tb CLI, you can persist data by mounting volumes for ClickHouse and metadata storage.

Create a docker-compose.yaml file in your project directory:

docker-compose.yaml
version: "3.8"
services:
  tinybird-local:
    image: tinybirdco/tinybird-local:latest
    container_name: tinybird-local
    platform: linux/amd64
    ports:
      - "7181:7181"
    volumes:
      - ./data/data:/var/lib/clickhouse
      - ./data/metadata:/redis-data
    restart: unless-stopped

Then start the container:

docker compose up -d

The ./data/data directory stores your ClickHouse data, and the ./data/metadata directory stores internal metadata, ensuring both persist across container restarts.

To connect the tb CLI to the running container, create a .tinyb file in your project directory:

{
    "name": "<your_workspace_name>"
}

Next steps

Updated