> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canvas-protocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run the Canvas agent server locally in a few minutes.

Canvas is a Node/TypeScript service: a grammY Telegram bot behind an Express server, Postgres for state, viem for Base, and Kimi for scoring. This guide gets it running locally.

## Prerequisites

* **Node 21+** (the project targets `>=21 <24`)
* **PostgreSQL** — any local instance; the schema self-applies on boot
* **A test Telegram bot token** from [@BotFather](https://t.me/BotFather)
* **A public HTTPS URL** for the webhook (e.g. an [ngrok](https://ngrok.com) tunnel) — the bot runs webhook-only
* **Foundry** (optional) — only to run the contract tests

<Warning>
  Never boot with the **production** bot token locally — the app registers its own webhook on startup and would steal the production webhook. Always use a separate test bot.
</Warning>

## Steps

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/rosarkar/canvas-ai.git && cd canvas-ai
    npm install
    ```
  </Step>

  <Step title="Configure environment">
    ```bash theme={null}
    cp .env.example .env
    ```

    Fill in the four required variables (the app fails to boot without them):

    | Variable                  | Value                                                 |
    | ------------------------- | ----------------------------------------------------- |
    | `DATABASE_URL`            | `postgresql://user:password@localhost:5432/canvas_ai` |
    | `TELEGRAM_BOT_TOKEN`      | Your **test** bot token from BotFather                |
    | `TELEGRAM_WEBHOOK_URL`    | Your public HTTPS URL (e.g. the ngrok URL)            |
    | `TELEGRAM_WEBHOOK_SECRET` | Any random string                                     |

    Everything else has a default or is optional — see [Environment variables](/developers/environment).
  </Step>

  <Step title="Run">
    ```bash theme={null}
    npm run dev
    ```

    The server binds `/health`, applies the Postgres schema, and registers the Telegram webhook on boot.
  </Step>
</Steps>

## Useful scripts

| Command             | Purpose                               |
| ------------------- | ------------------------------------- |
| `npm run dev`       | Watch mode (`tsx watch src/index.ts`) |
| `npm run typecheck` | `tsc --noEmit`                        |
| `npm test`          | Vitest unit tests                     |
| `npm run build`     | Compile to `dist/`                    |
| `npm run smoke`     | End-to-end smoke script               |

## Contracts

```bash theme={null}
git submodule update --init   # forge-std
forge test                    # requires Foundry
```

The escrow contract is `contracts/CanvasEscrowV0.sol` (see [Smart contract](/architecture/smart-contract)).

## Next

* [Environment variables](/developers/environment) — the full configuration reference
* [API reference](/developers/api-reference) — the read and deposit endpoints
* [System overview](/architecture/system-overview) — how the pieces fit together