---
last_updated: "2026-09-11T23:22:55.000Z"
title: Config files
meta:
  description: Tinybird project configuration files, including tinybird.config.json and .tinyb.
---

# Config files

Tinybird projects use configuration files for two different jobs:

- `tinybird.config.json` defines project settings, such as which files to include and whether development runs in Cloud Branches or Tinybird Local.
- `.tinyb` stores local authentication and Workspace context created by `tb login`.

Commit `tinybird.config.json` to version control. Don't commit `.tinyb` because it can contain authentication tokens.

## tinybird.config.json

Use `tinybird.config.json` to tell Tinybird where your project resources live. The development mode controls the default build target. Use `branch` for Cloud Branches or `local` for Tinybird Local.

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

```json {% title="tinybird.config.json" %}
{
  "dev_mode": "branch",
  "branch_data_mode": "last_partition",
  "folder": "tinybird",
  "include": [
    "tinybird"
  ]
}
```

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

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

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

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

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

### Config keys

{% table %}
  * Key
  * Description
  ---
  * `include`
  * Paths to datafiles or SDK resource definitions that Tinybird builds and deploys.
  ---
  * `folder`
  * Project folder for datafiles. `tb init` writes this value to `tinybird.config.json`. When omitted, Tinybird infers the folder from `include`.
  ---
  * `dev_mode` / `devMode`
  * Default build target: `branch` for Cloud Branches, `local` for Tinybird Local, or `manual` to require explicit `--cloud`, `--local`, or `--branch` flags.
  ---
  * `branch_data_mode`
  * Data to attach when a Cloud Branch is created with `dev_mode=branch`, by `tb build` or by `npx tinybird preview`. Only `last_partition` is supported. **The default differs by tool**: `tb` attaches `last_partition` when the key is omitted, while the TypeScript SDK creates the branch with no data. Set the key explicitly to get production data in an SDK branch. The TypeScript SDK reads this key only in snake_case, unlike its other camelCase config keys. The legacy key `branch_data_on_create` is no longer supported.
  ---
  * `token` / `baseUrl`
  * SDK-only. Authentication token and API host, often loaded from environment variables.
{% /table %}

For development mode setup, see [Local development](/forward/development-workflow/local-development) and [Using Cloud Branches](/forward/development-workflow/using-cloud-branches).

## .tinyb

The `.tinyb` file contains the Tinybird project configuration, including the authentication token obtained by running `tb login`.

Running commands requires a valid `.tinyb` file in the root of your project. If you don't have one, create one by running [tb login](/forward/dev-reference/commands/tb-login).

### Location

You can place the `.tinyb` file in the root of your app repository or keep it together with your Tinybird datafiles. Tinybird looks for the `.tinyb` file in all parent folders until it reaches the home directory.

If your Tinybird files and folders are located in a subdirectory, such as `tinybird/`, add a `cwd` field to specify the relative path to that directory.

### File structure

The following is a sample `.tinyb` file:

```json {% title=".tinyb" %}
{
  "host": "<tinybird-host>",
  "id": "<workspace-id>",
  "name": "<workspace-name>",
  "scope": "user",
  "token": "<authentication-token>",
  "tokens": {
    "<tinybird-host>": "<authentication-token>",
    "<another-tinybird-host>": "<authentication-token>"
  },
  "cwd": "<optional-path-to-your-tinybird-folder>",
  "user_email": "<user-email>",
  "user_id": "<user-id>",
  "user_token": "<authentication-token>",
  "version": "<tinybird-version>"
}
```