---
title: Development Guide
description: Setup and development workflow for Teak
---

**Prerequisites:** Git plus Bun and Node.js at the versions pinned in `package.json` (`packageManager` and `engines.node`). Setup validates both and refuses to run on the wrong toolchain.

## Quick Start (local)

1. **Clone the repository**

    ```bash
    git clone https://github.com/praveenjuge/teak.git
    ```

2. **Move into the project**

    ```bash
    cd teak
    ```

3. **Provision the local stack**

    ```bash
    bun run setup
    ```

    Setup installs dependencies, provisions an isolated Convex development deployment, and derives the local env files. It needs no production credentials. For another surface, pass `--target` (see below).

4. **Verify readiness**

    ```bash
    bun run doctor
    ```

5. **Start the stack**

    ```bash
    bun run dev
    ```

    The web app and documentation open in your default browser once both are ready.

## Access Points

- Web app: http://localhost:3000
- Docs (proxies local `/api` and `/mcp`): http://localhost:3001
- Mobile: Expo Go or a simulator; Safari extension: Xcode

See the repository README for the monorepo layout.

## Core Commands

```bash
bun run setup            # First run: install deps + provision Convex + write local env
bun run setup --target desktop --convex local --json  # Per-target setup with a machine-readable report
bun run doctor           # Validate the environment (--json --target --profile for agents)
bun run dev              # Web + Convex backend (bun run dev --help for targets)
bun run dev web --headless  # Non-interactive output for agents and CI
bun run dev --all        # All services
bun run smoke:web        # End-to-end local session check (needs the stack running)
bun run audit:env        # Environment contract + local dotenv audit

bun run dev convex       # Convex backend only
bun run dev web          # Next.js web
bun run dev mobile       # Expo mobile
bun run dev desktop      # Electron desktop
bun run dev extension    # Chrome extension
open apps/safari-extension/teak-safari.xcodeproj # Safari extension
bun run dev raycast      # Raycast extension
bun run dev docs         # Docs site

bun run build            # Production build (all)
bun run build:extension  # Package Chrome extension
bun run build:raycast    # Build Raycast extension

bun run lint && bun run typecheck
bun run test             # Unit tests (turbo; test:unit / test:edge for Convex splits)
bun run verify           # typecheck + lint + test (affected)

bun run check            # Quality report (Ultracite)
bun run fix              # Auto-fix issues

bun run pre-commit       # Pre-commit checks
bun run publish:raycast  # Publish to Raycast store
bun run clean            # Clear Turborepo caches
```

## Supported Targets and Limitations

`bun run setup --target <name>` provisions one surface. Every target except `e2e`
works with zero copied credentials.

| Target | Needs | Limitations |
| --- | --- | --- |
| `web` | Convex deployment | None; the default path |
| `docs`, `cli` | Nothing beyond install | No Convex provisioning |
| `desktop`, `extension` | Convex deployment | Env files derive `VITE_*` aliases automatically |
| `mobile-simulator` | Convex deployment | iOS simulator uses loopback; Android emulators need `10.0.2.2` instead of `localhost` |
| `mobile-device` | Convex deployment, LAN | The host must be LAN-reachable; doctor reports the address or an actionable diagnostic |
| `files-worker` | `bun run sync:cloudflare-dev` afterwards | Worker secrets are owned by the sync command, not setup |
| `e2e` | Production credentials | Not provisioned by setup; see `packages/tests/README.md` |

Linked git worktrees get deterministic ports and a namespace; pair them with
`--convex cloud` for an isolated cloud development deployment so two
checkouts never collide. iOS simulators, device builds, Xcode, and Safari
stay on macOS.

## Reporting Setup Problems

Paste the redacted JSON report with your issue. It contains check names and
remediations but never secret values:

```bash
bun run doctor --target web --profile local --json
```

## Setup Checklist

### Convex + Better Auth

Follow the [self-hosting quickstart](/docs/self-hosting) for `bun run setup`, `BETTER_AUTH_SECRET`, and `bunx convex dev` — it provisions the same isolated Convex deployment local development uses. Google and Apple sign-in are optional locally: without their credentials, email sign-in works normally and the social buttons report that the provider isn't configured.

### Public API and MCP

The public REST API, MCP endpoint, discovery routes, OpenAPI spec, and SDK live in `packages/convex`. Start Convex to serve the HTTP routes, then use the docs dev proxy for local API and MCP URLs.

Example:

```bash
bun run dev:convex
```

The docs dev server proxies `/api`, `/mcp`, and OAuth protected-resource metadata to the Convex dev deployment. That gives local docs, examples, and smoke tests the same path shape as production: `/api/v1` and `/mcp`.

Native OAuth clients revoke credentials with a form-encoded `POST` to `/api/oauth/revoke` and read the account with `GET /api/oauth/userinfo` on the Convex site origin; both accept OAuth tokens only, never API keys.

### MCP Registry

The repo includes `server.json` for the MCP registry under the `com.teakvault/mcp` namespace. Publishing is manual because the namespace requires DNS verification for `teakvault.com`:

```bash
npm install -g mcp-publisher
mcp-publisher login dns
mcp-publisher publish
```

Follow the CLI prompt to add the DNS TXT record, then publish once verification passes.

### Environment Variables

See **[Self-Hosting → Environment settings](/docs/self-hosting#detailed-environment-reference)** for every env var required across web, mobile, extension, and the Convex backend.

Optional local overrides: `TEAK_DEV_APP_URL` (default: `http://localhost:3000`), `TEAK_DEV_API_URL` (only needed when your Convex dev site differs from the repo default), `TEAK_DEV_DOCS_URL` (default: `http://localhost:3001`).