Setup

Prerequisites

Rust ≥ 1.84 (2024 edition) with the wasm32-wasip2 target. Stable 1.84+ ships a wasm-component-ld that links wit-bindgen 0.50 output; older versions do not.
Node.js ≥ 20 and npm (for frontend builds; Vite 8 requires Node.js 20+)
Docker (optional, for local Turso/libSQL database)

Monorepo contributors: the monorepo itself pins its Rust toolchain in rust-toolchain.toml (currently 1.97.1). rustup picks this up automatically when you run any Cargo command inside the repo — no manual installation step needed beyond having rustup installed.

Install Rust target

rustup target add wasm32-wasip2

Install forte CLI

Option A — cargo binstall (downloads a pre-built binary):

# Install cargo-binstall if not already installed
cargo install cargo-binstall

cargo binstall forte-cli

Option B — build from source (requires the monorepo):

cargo install --path forte/cli

Pre-built binaries for aarch64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu are published to GitHub Releases on every version tag and picked up automatically by cargo binstall.

Install fn0 CLI (optional, for raw fn0 projects without Forte)

cargo binstall fn0-cli
# or from source:
cargo install --path fn0/cli

Install forte-test-runner (optional, for backend unit tests in Forte projects)

Forte project backends compile to wasm32-wasip2 and require a custom test runner to execute tests. The runner is not on crates.io — install it from the fn0 monorepo:

git clone https://github.com/NamseEnt/fn0.git
cd fn0
cargo install --path forte/test-runner

You can wait until you need it — forte dev does not require it. See forte/testing.md for how to configure the runner and write backend tests. Reinstall whenever you pull monorepo changes — a runner older than the WIT bindings in the checkout fails at link time.

Local Database (Turso/libSQL)

The doc-db crate connects to Turso/libSQL.

Forte projects: forte dev downloads and starts sqld automatically — no manual setup needed. The database file is stored in .forte/data/ inside your project directory. Normal application code should use doc_db::database(), which is routed through the local semantic doc-db service. TURSO_URL and TURSO_AUTH_TOKEN remain injected for legacy/direct Turso users and do not need to be set for local development.

Raw fn0 projects: fn0 local supports doc_db::database() through a semantic service backed by one in-memory database for the process lifetime. Restarting the local server loses that state. It does not configure legacy/direct Turso access.

Running doc-db tests directly (outside of forte dev) requires a separately running libSQL server:

docker compose up -d libsql-test   # starts libsql-test on port 18123
cargo test -p fn0-doc-db

Environment variables for direct doc-db test usage:

Variable	Default	Description
`DOC_DB_TEST_URL`	`http://127.0.0.1:18123`	libSQL URL for tests (overrides default)

For production, fn0 injects the semantic FN0_DOC_DB_URL endpoint and routes it through DocDbHijack. TURSO_URL and TURSO_AUTH_TOKEN are also injected for legacy/direct Turso users.

Environment Variables

Variable	Required	Description
`COOKIE_SECRET`	Yes (if using `cookie_sign`)	HMAC secret for signed cookies
`FN0_DOC_DB_URL`	No	Semantic document DB endpoint; injected automatically by fn0
`TURSO_URL`	No	Database URL; injected automatically by `forte dev`
`TURSO_AUTH_TOKEN`	No	Database auth token; injected automatically by `forte dev`
`FN0_QUEUE_URL`	No	Queue endpoint; injected automatically by `forte dev`; required in production if using queue tasks
`FN0_OBJECT_STORAGE_URL`	No	Object storage endpoint; injected automatically by `forte dev`; required in production if using object storage
`OTEL_SERVICE_NAME`	No	Service name in OpenTelemetry traces and metrics (defaults to `"forte-app"`)

Creating a Forte Project

forte init my-app
cd my-app
forte dev

forte init scaffolds the project, installs npm packages, and prints next steps.

On the first forte dev run, two tools are downloaded automatically and cached in ~/.forte/bin/:

sqld (libSQL server) — for the local database
forte-rs-to-ts — Rust→TypeScript type generator

Subsequent runs use the cached binaries. See forte/cli.md#local-tool-cache for cache paths and how to clear them.

Deploying to fn0 Cloud

Deploying requires three steps the first time:

1. Authenticate with fn0 Cloud:

forte login

Prints a PKCE authorization URL, accepts a one-time authorization code copied from the browser, and saves credentials locally. The browser and CLI can run on different computers, so this also works over SSH.

2. Connect your Cloudflare account:

forte cloud login --zone example.com

The first time, this asks for a Cloudflare setup token and installs the account-level broker. The token needs only User → API Tokens → Edit and is stored in your Cloudflare account's Secrets Store, not locally.

Then initialize the project:

forte cloud init \
  --project . \
  --project-name my-app \
  --zone example.com

cloud init does not ask for a Cloudflare token. It reuses the broker created by cloud login and prepares the project-specific resources.

Registers the project with fn0 Cloud, enables WebSockets for the selected zone, provisions three R2 buckets in your Cloudflare account, and writes the proxied CNAME your app answers on into your zone. Requires forte login to have run first.

See Bring Your Own Cloudflare for token setup and what gets created in your account.

This step is idempotent — re-running it on an existing project reuses the existing resources.

3. Deploy:

forte deploy

Builds, uploads, and activates the project. A project that has not completed forte cloud init is refused at this step.

On subsequent deploys, only step 3 is needed.

See forte/overview.md for project layout and forte/cli.md for all CLI commands.