Installation

TrueCourse is one server that also serves the web app, with Postgres behind it. The server is told how it runs with TRUECOURSE_MODE:

Mode	For	Sign-in
`local`	One developer’s machine. There is one implicit person in one implicit workspace, and folders on the machine can be connected as repositories.	None
`hosted`	A deployment for a team. This is the default.	WorkOS AuthKit

Leave TRUECOURSE_MODE unset for hosted. Any value other than local or hosted stops the server at boot.

Requirements

Requirement	Notes
Node.js 22 or later	The container image uses Node.js 22.
pnpm 9	The repository pins its pnpm version.
Postgres 16	`docker compose up -d` starts one on `127.0.0.1:5432`. The server applies its migrations at boot.
git	Runs clone repositories.
Playwright’s Chromium	Only for flows with web steps. Install it with `pnpm --filter @truecourse/guard-runner exec playwright-core install chromium`. A run never downloads a browser.

Run it locally

git clone https://github.com/truecourse-ai/truecourse.git
cd truecourse
pnpm install
cp .env.example .env
docker compose up -d
TRUECOURSE_MODE=local pnpm dev

pnpm dev serves the web app on http://localhost:3000 and the server on port 3001. The server reads the .env file at the root of the checkout. Local mode needs two variables:

Variable	What it does
`DATABASE_URL`	The Postgres connection string. The value in `.env.example` matches the compose database.
`TRUECOURSE_SECRET_KEY`	A secret of at least 32 characters. It encrypts each workspace’s provider key and each repository’s registered dependency values. The server refuses to boot without it.

Generate a secret with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

In local mode the server never reads the WorkOS variables and offers no invitations. Local folder appears as a repository provider. A folder has no webhook, so its documentation syncs again when you press Sync now or when a file in the folder changes.

Deploy for a team

Hosted mode needs DATABASE_URL and TRUECOURSE_SECRET_KEY, plus WorkOS:

Variable	Required	What it does
`WORKOS_API_KEY`	Yes	The WorkOS API key.
`WORKOS_CLIENT_ID`	Yes	The WorkOS client id.
`WORKOS_COOKIE_PASSWORD`	Yes	Seals the session cookie. At least 32 characters.
`WORKOS_REDIRECT_URI`	No	Where WorkOS sends the browser after login. Defaults to `http://localhost:3001/api/auth/callback`.
`WORKOS_APP_URL`	No	The web app origin the callback lands on. Defaults to `http://localhost:3000`.

A workspace is the signed-in session’s WorkOS organization. The server refuses any request that has no session. Invite people from Settings › Members.

Connect GitHub

Repositories come in through a GitHub App. Set all four variables:

Variable	What it does
`GITHUB_APP_ID`	The App’s id.
`GITHUB_APP_PRIVATE_KEY`	The App’s private key: a raw PEM, a PEM with escaped newlines, or a base64-encoded PEM.
`GITHUB_APP_WEBHOOK_SECRET`	Verifies the App’s webhook deliveries.
`GITHUB_APP_SLUG`	The slug in the App’s public URL, used for the install link.

Without them the server still boots, and its GitHub routes answer 503 with the names of the missing variables. On the App’s settings page, point the webhook URL at /api/github/webhook on a public address, and the setup URL at /api/github/setup. The App acts on installation, installation_repositories and push events. A push to a repository’s default branch syncs the Repository source that reads it. Connect accounts from Settings › Repositories, then connect repositories from Code. GitLab is listed there as coming soon.

The container image

The Dockerfile builds the server and the web app into one image. The server serves the web app and listens on PORT, which is 3001 in the image. Its runtime directory is /data. Postgres stays outside the image.

Optional variables

Variable	What it does
`PORT`	The server’s port. Defaults to 3001.
`TRUECOURSE_RUNTIME_DIR`	Where runs keep their scratch. Defaults to `~/.truecourse-runtime`. See Storage.
`TRUECOURSE_LOG_DIR`	Where the server log goes. Defaults to `logs/` in the runtime directory.
`TRUECOURSE_LLM_TRANSPORT`	Set to `claude-code` for operator mode. See LLM transport.

Model, concurrency and timeout variables are on Models & environment.

Editions

The open edition is everything except three enterprise features: document Connections, repository providers beyond GitHub and GitLab, and more than one workspace. They live in the ee/ directory under their own license. A build decides its edition when it is built: when the build includes ee/, the container image starts the enterprise edition.

Getting Started

Workspace

Context

Code

Flows

Settings

Configuration

Enterprise

Requirements

Run it locally

Deploy for a team

Connect GitHub

The container image

Optional variables

Editions

Next steps

Quickstart

Storage

​Requirements

​Run it locally

​Deploy for a team

​Connect GitHub

​The container image

​Optional variables

​Editions

​Next steps

Quickstart

Storage

Requirements

Run it locally

Deploy for a team

Connect GitHub

The container image

Optional variables

Editions

Next steps