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 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.

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.

{
  "dev_mode": "local",
  "include": [
    "tinybird"
  ]
}

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:

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.

» 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:

tb local start --daemon

If Tinybird Local becomes unhealthy, restart it:

tb local restart

Build the project¶

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

tb build

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

tb --local build

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

» 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.

[API] POST /v1/build 200 67.1ms

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

Test local resources¶

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

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

You can also run SQL against Tinybird Local:

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

For test files and fixtures, see 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.

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:

tb --cloud deploy --check

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

tb --cloud deploy

See Manual deployment and CI/CD.