---
title: Tinybird Local
meta:
  description: Run Tinybird on your machine for local development, testing, and CI.
---

# Tinybird Local

Tinybird Local is a containerized Tinybird runtime for development, testing, and CI. It runs on your machine and gives you the same project model you use in Tinybird Cloud: Data Sources, Pipes, Endpoints, Tokens, APIs, and local services.

Use Tinybird Local when you want a fast, isolated environment with fixture data. Use [Cloud Branches](/forward/development-workflow/using-cloud-branches) when you need a shared Cloud environment, production-like data, or connector validation before deployment.

## Prerequisites

To install and run Tinybird Local, you need:

- A [Tinybird account](https://cloud.tinybird.co).
- Linux or macOS.
- A container runtime, such as Docker or OrbStack.

OrbStack containers do not require extra configuration. Docker users should check the following settings:

- **Apple Silicon**: Enable Rosetta in **Docker Desktop > Settings > General > Use Rosetta for x86/amd64 emulation on Apple Silicon**. Without Rosetta, Docker falls back to QEMU emulation, which can be slower and less stable.
- **Memory**: Set Docker memory to at least 8 GB in **Docker Desktop > Settings > Advanced > Memory**.

## Install Tinybird

Install the Tinybird CLI and Tinybird Local:

{% snippet title="install-tinybird-forward" /%}

Authenticate with Tinybird Cloud:

```shell
tb login
```

This opens a browser window where you can sign in to Tinybird Cloud. If you need a specific region, see [Regions and endpoints](/api-reference#regions-and-endpoints) and pass the host to `tb login`.

## Start Tinybird Local

Start Tinybird Local with the CLI:

```shell
tb local start
```

Run it in the background with `--daemon`:

```shell
tb local start --daemon
```

The CLI waits until the local services are ready. Do not start building your project until you see `Tinybird Local is ready!`.

Stop Tinybird Local with `Ctrl+C` if it is running in the foreground, or with:

```shell
tb local stop
```

If Tinybird Local becomes unhealthy, restart it:

```shell
tb local restart
```

## Services

Tinybird Local starts the services needed to run a Tinybird project locally:

- ClickHouse: Stores data and runs queries.
- Redis: Stores user and Workspace metadata.
- Kafka consumer: Ingests data from Kafka topics into Data Sources.
- Events API server: Ingests HTTP events into Data Sources.
- Tinybird server: Exposes Tinybird APIs, such as authentication and Endpoints.
- Project server: Exposes your project to Tinybird UI.
- MCP server: Exposes your Workspace as tools for agents.

The local API base URL is:

```text
http://localhost:7181/v0/
```

For example, you can write to a local Events API Data Source:

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

## Persist local data

By default, local state is tied to the Tinybird Local container. To persist data between development sessions, pass a custom volume path:

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

`tb local stop` does not remove local data. `tb local restart` recreates the local runtime. To return to an earlier local state, restart with a previous volume path:

```shell
tb local restart --volumes-path ./tb_previous_snapshot
```

## Run with Docker directly

The CLI is the recommended way to start Tinybird Local. If you need to run the container directly, use Docker:

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

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

```json
{
  "name": "<your_workspace_name>"
}
```

## Run with Docker Compose

Use Docker Compose when you want explicit volume mounts for ClickHouse and metadata storage:

```yaml {% title="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
```

Start it:

```shell
docker compose up -d
```

The `./data/data` directory stores ClickHouse data. The `./data/metadata` directory stores internal metadata.

## Local Tokens

Tinybird Local can generate default user and Workspace Tokens for development and tests:

```shell
tb local generate-tokens
```

Pass generated Token values when starting Tinybird Local:

```shell
tb local start --user-token=<USER_TOKEN> --workspace-token=<WORKSPACE_TOKEN>
```

See [Tinybird Local Tokens](/forward/core-concepts/static-tokens#tinybird-local-tokens).

## Next steps


- [Local development](/forward/development-workflow/local-development)
- [Cloud Branches](/forward/development-workflow/using-cloud-branches)
- [Test your project](/forward/guides/test-your-project)
- [Tinybird CLI commands](/forward/dev-reference/commands)