Installation

Forst ships as a native compiler with an optional npm wrapper for Node/TypeScript workflows. Pick the path that matches how you deploy and develop: npm, Debian package, native binary, or Docker.

npm (`@forst/cli`)

Best for teams already on Node.js, npm scripts, or monorepos with TypeScript clients. Install the package:

npm install -D @forst/cli

After install, invoke the compiler via:

npx forst version
npx forst run path/to/file.ft
npx forst generate path/to/project

On first use, @forst/cli downloads the native forst binary for your platform from GitHub Releases and caches it locally.

CI and offline environments

Set FORST_BINARY to a pre-installed executable path to skip the download step:

export FORST_BINARY=/usr/local/bin/forst
npx forst version

Other useful variables:

Variable	Purpose
`FORST_BINARY`	Path to a pre-installed `forst` executable
`FORST_CACHE_DIR`	Override binary cache location
`FORST_CLI_VERIFY`	Control checksum verification on download

Full details: @forst/cli README.

Generated TypeScript client

When a Node app imports @forst/gen, install the CLI, add a lifecycle script, then generate:

npm install @forst/cli

{
  "scripts": {
    "postinstall": "forst generate ."
  }
}

npx forst generate .

The postinstall line is required. The client lives under .forst/client (gitignored) and is linked into node_modules. A fresh npm ci removes that link. Without postinstall, imports of @forst/gen fail until someone runs generate by hand. Optional scripts for local workflows:

{
  "scripts": {
    "postinstall": "forst generate .",
    "predev": "forst generate .",
    "prebuild": "forst generate ."
  }
}

Import shape, subpaths, and layout: Generate a TypeScript client. Calling functions at runtime: Call Forst over HTTP. Monorepos: put postinstall on the workspace package that owns ftconfig.json, not the repo root unless that root is the boundary. See Generate a TypeScript client § Monorepos.

Native binary

Download the release artifact for your OS/arch from GitHub Releases, extract it, and add it to your PATH. Verify the install:

forst version
forst run examples/in/basic.ft

Use this path when you do not need npm integration, for example pure Go modules or system wide installs.

Debian / Ubuntu (.deb)

Best for system-wide installs on Debian or Ubuntu without npm. Installs forst to /usr/bin. Pick amd64 or arm64 from GitHub Releases when a compiler v* release ships.

wget https://github.com/forst-lang/forst/releases/download/v0.x.y/forst_0.x.y-1_amd64.deb
sudo apt install ./forst_0.x.y-1_amd64.deb
forst version

Docker (GHCR)

Official multi-arch images are published on GitHub Container Registry when a compiler v* release ships.

Image	Use when
`ghcr.io/forst-lang/forst`	Default — `forst` plus the Go toolchain (`run`, `test`, `generate`, `dev`, …)
`ghcr.io/forst-lang/forst-minimal`	Compiler only — smaller image when you do not need `go run` / `go test`

Pin the image tag to the compiler release (for example v0.1.0). latest tracks the latest stable compiler release. Generate TypeScript types in CI:

docker run --rm -v "$PWD:/workspace" -w /workspace \
  ghcr.io/forst-lang/forst:v0.x.y generate ./my-service

Run Forst tests:

docker run --rm -v "$PWD:/workspace" -w /workspace \
  ghcr.io/forst-lang/forst:v0.x.y test ./...

Dev server:

docker run --rm -p 8080:8080 -v "$PWD:/workspace" -w /workspace \
  ghcr.io/forst-lang/forst:v0.x.y dev --port 8080 --root .

The default image includes Go for transpile-and-run workflows. Use forst-minimal only when you will exec a prebuilt invoke binary and do not need forst run or forst test. Production Node + Forst (multi-stage):

# build stage
FROM ghcr.io/forst-lang/forst:v0.x.y AS forst-build
WORKDIR /app
COPY . .
RUN forst generate . \
 && forst build -root . -o .forst/build --goos=$TARGETOS --goarch=$TARGETARCH -- ./app/main.ft

# runtime stage
FROM node:22-bookworm-slim
WORKDIR /app
COPY --from=forst-build /app/.forst/client /app/.forst/client
COPY --from=forst-build /app/.forst/build /app/.forst/build
ENV FORST_ROOT=/app
CMD ["/app/.forst/build/bin/main"]

Adjust paths for your layout. Read manifest.json binary for the linked executable name. Invoke-only / no JS imports: The runtime image needs only the linked binary and FORST_ROOT. You do not need Node in the image when the program does not import TypeScript and you are not using bridge.hostMode. bridge.hostMode: Copy the Node host entry files referenced in bridge.args, install production dependencies (tsx, @forst/runtime), and run the linked binary as the parent process. @forst/gen is a build-time TypeScript artifact from forst generate. It is not a runtime Node requirement for the Go binary alone when Node is not spawned.

Editor support

For diagnostics, hover, go-to-definition, and formatting in VS Code, install the Forst extension and run the language server. See Editor workflow.

Verify your install

Confirm the compiler is on your PATH:

forst version
forst run --help

You should see version output and subcommand help. If the npm wrapper fails to download, check network access to github.com or set FORST_BINARY.

Quickstart

Write and run your first validated handler.

Generate a TypeScript client

Import from @forst/gen after install and generate.

Overview

Getting started

Data validation

Behavior

Interoperability

Workflow

Installation

npm (`@forst/cli`)

CI and offline environments

Generated TypeScript client

Native binary

Debian / Ubuntu (.deb)

Docker (GHCR)

Editor support

Verify your install

Next

Quickstart

Generate a TypeScript client

​npm (@forst/cli)

​CI and offline environments

​Generated TypeScript client

​Native binary

​Debian / Ubuntu (.deb)

​Docker (GHCR)

​Editor support

​Verify your install

​Next

Quickstart

Generate a TypeScript client

npm (`@forst/cli`)

CI and offline environments

Generated TypeScript client

Native binary

Debian / Ubuntu (.deb)

Docker (GHCR)

Editor support

Verify your install

Next