---
title: Local development
meta:
  description: Develop your Tinybird project locally. Make changes and test them before deploying to Tinybird Cloud.
---

# Local development

Use Tinybird Local to build and test your project on your machine before deploying to Tinybird Cloud. The workflow is the same one used in the quickstarts: configure the project, build, test the Endpoint, then deploy.

Use Tinybird Local when fixture data is enough and you want a fast loop on your machine. Use [Cloud Branches](/forward/development-workflow/using-cloud-branches) when you need production-like data, connector validation, shared preview URLs, or pull request review.

For installation, Docker settings, local services, API URLs, persistence, and local Tokens, see [Tinybird Local](/forward/core-concepts/tinybird-local).

## Check your project config

Your project config defines which files Tinybird builds and which development environment commands use by default.

Use `include` to point at your datafiles or SDK resource definitions. Set `dev_mode` or `devMode` to `local` when you want `build` to target Tinybird Local by default. You can still override the target with `--local` or `--branch` on the command line.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```json {% title="tinybird.config.json" %}
{
  "dev_mode": "local",
  "include": [
    "tinybird"
  ]
}
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```json {% title="tinybird.config.json" %}
{
  "include": [
    "lib/tinybird.ts"
  ],
  "token": "${TINYBIRD_TOKEN}",
  "baseUrl": "${TINYBIRD_URL}",
  "devMode": "local"
}
```

{% /tab %}

{% tab label="Python SDK" %}

```json {% title="tinybird.config.json" %}
{
  "include": [
    "src/tinybird"
  ],
  "token": "${TINYBIRD_TOKEN}",
  "baseUrl": "${TINYBIRD_URL}",
  "devMode": "local"
}
```

{% /tab %}
{% /tabs %}

## Typical local workflow

1. Set the development environment to Local in `tinybird.config.json`.
2. Start Tinybird Local.
3. Check out a git branch.
4. Build the project with fixture data.
5. Edit Data Sources, Pipes, Endpoints, Tokens, or Connections.
6. Rebuild and query local resources or call local Endpoints.
7. Run a deployment check against Tinybird Cloud.
8. Merge and deploy ideally via CI/CD.

## Start Tinybird Local

Start Tinybird Local before you build or test local resources:

```shell
tb local start
```

The CLI logs the status of the container and services. Do not build the project until you see the `Tinybird Local is ready!` message.

```shell
» Starting Tinybird Local...
* Tinybird Local container status: healthy
» Checking services...
✓ Tinybird Local container
✓ Clickhouse
✓ Redis
✓ Server
✓ Events
✓ Tinybird Local authentication
✓ Tinybird Local is ready!
```

Run Tinybird Local in the background with `--daemon`:

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

If Tinybird Local becomes unhealthy, restart it:

```shell
tb local restart
```

## Build the project

Run a build before testing changes. It validates resource definitions, resolves dependencies, and loads matching fixture files.

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```shell
tb build
```

{% /tab %}
{% tab label="TypeScript SDK" %}

```shell
npx tinybird build
```

{% /tab %}
{% tab label="Python SDK" %}

```shell
uv run tinybird build
```

{% /tab %}
{% /tabs %}

If your config does not default to Local, pass the flag explicitly:

```shell
tb --local build
```

For SDK projects, use the matching SDK command, such as `npx tinybird build --local`.

```shell
» Building project...
✓ datasources/user_actions.datasource created
✓ endpoints/user_actions_line_chart.pipe created
✓ Build completed in 0.2s
```

In the `tb local start` logs, you can see whether the request is successful.

```shell
[API] POST /v1/build 200 67.1ms
```

When you edit project files, run build again to apply the changes to Tinybird Local.

{% callout type="tip" %}
If you want automatic rebuilds while editing local files, run `tb dev`. The examples use explicit `tb build` because it is the same command you run in CI and branch workflows.
{% /callout %}

## Test local resources

Call local Endpoints with the local API host and a local Token:

```shell
curl -H "Authorization: Bearer <local-token>" \
  "http://localhost:7181/v0/pipes/user_actions_line_chart.json"
```

You can also run SQL against Tinybird Local:

```shell
tb --local sql "SELECT count() FROM user_actions"
```

For test files and fixtures, see [Test your project](/forward/guides/test-your-project).

## Open Tinybird UI

You can also use Tinybird UI to inspect your project. Run the following command to open the Tinybird UI pointing to your local environment.

```shell
tb open
```

The URL is `https://cloud.tinybird.co/<cloud-provider>/<region>/<workspace-name>~local~<branch-name>`

## Deploy after validation

When the local checks pass, validate the deployment against Tinybird Cloud before merging or releasing:

```shell
tb --cloud deploy --check
```

Then deploy manually or let CI/CD deploy from the main branch:

```shell
tb --cloud deploy
```

See [Manual deployment](/forward/development-workflow/manual-deployment) and [CI/CD](/forward/development-workflow/cicd).