> ## Documentation Index > Fetch the complete documentation index at: https://docs.heylinger.com/llms.txt > Use this file to discover all available pages before exploring further. # Contribute > Run Linger from source with hot reload, run the checks, and prepare a pull request. To contribute to Linger, run it from source, make your change, and run the checks. Then open a pull request on [GitHub](https://github.com/simplexai-labs/linger). The repository's `CONTRIBUTING.md` is the source for this page. Read the nearest `AGENTS.md` before you change an app. `pnpm dev` runs Web, TeamHub, and the node-services process on your machine. Web and TeamHub reload when you save. node-services does not watch files: restart it, or run `pnpm --filter @linger/node-services dev` for a watching process. `pnpm dev` starts no containers. You run PostgreSQL yourself. To run Linger for daily use, follow [Install with Docker Compose](https://docs.heylinger.com/install/docker-compose.md) instead. Linger needs no model gateway or API key of its own. Agent model calls, including the background work of agent memory and the personal memory, run on the Codex or Claude Code of the user's own computer. Grok Live voice mode calls xAI from the server. ## Check what you need Install these tools before you start: * **Node.js 26.5.x** and **pnpm 11.7.0**. The repository pins the Node version in `.node-version`. * **Go 1.26.5**. * **PostgreSQL 17** with the pgvector extension, running on your machine. * **FFmpeg**, with `ffmpeg` and `ffprobe` on `PATH`, if you work on voice recording. * **Docker** with Docker Compose, only for the Compose setup and the TeamHub integration tests. ## Run Linger from source **1. Clone the repository** ```bash theme={null} git clone https://github.com/simplexai-labs/linger.git cd linger ``` **2. Install the dependencies** ```bash theme={null} pnpm install --frozen-lockfile ``` **3. Create your environment file** ```bash theme={null} cp .env.example .env ``` Set `TEAMHUB_DATABASE_URL` in `.env` to your database. The default matches the `postgres` service of the root `docker-compose.yml`. Only the optional personal keys for Composio and Soniox are empty. **4. Start the database if you use the Compose one** ```bash theme={null} docker compose up --detach --wait postgres ``` Skip this step if you run PostgreSQL yourself. **5. Start Linger** ```bash theme={null} pnpm dev ``` The command migrates the database that `TEAMHUB_DATABASE_URL` names. Then it runs Web, TeamHub, and node-services. **6. Check every service** In a second terminal, run: ```bash theme={null} pnpm dev:check ``` Then open `http://localhost:3000`. `pnpm dev` prepares a local owner account. `OWNER_EMAIL` in `.env` sets its email, and the default is `owner@linger.local`. `pnpm dev:check` calls the health endpoint of each service: | Service | Address | | - | - | | Web | `http://localhost:3000` | | TeamHub | `http://localhost:8080` | | node-services: Agent Service, Memory, LLM Wiki | `http://localhost:4319` | | node-services: Document Runtime | `http://localhost:4321` | For voice, set `SONIOX_API_KEY` or `XAI_API_KEY` in `.env` and put `livekit-server` on your `PATH` (`brew install livekit` on macOS, `curl -sSL https://get.livekit.io | bash` on Linux). `pnpm dev` then runs it on the ports and keys `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` name, and node-services starts the voice workers. Point `LIVEKIT_URL` at another host to use a LiveKit server you run elsewhere. To run everything in containers, voice included, follow [Install with Docker Compose](https://docs.heylinger.com/install/docker-compose.md). To build and test the desktop app, which also carries the installer, see [Build the desktop app](https://docs.heylinger.com/developers/build-desktop-app.md). ## Run the checks before a pull request Run the focused tests for your change first, then the fast checks of every app you touched. None of these checks need a database or containers. | Change | Command | | - | - | | Anything | `make check BASE=origin/` runs every app's fast check in parallel. | | Web | `make check-web` | | TeamHub | `make -C apps/teamhub fmt-check`, then `cd apps/teamhub && go test ./tests/integration/layout -count=1` | | Other apps | The matching `make check-`. | | Contracts | Edit `contracts/openapi/`, then run `pnpm contracts:generate && pnpm contracts:verify`. | | Repository rules | `make check-repository-gate BASE=origin/` | To run a single test: * **Web:** `pnpm --filter @linger/web test ` * **node-services:** `pnpm --filter @linger/node-services exec vitest run ` * **TeamHub package:** `cd apps/teamhub && go test ./internal/` ## Run the TeamHub integration tests Run the integration tests when a change touches database, process, concurrency, or recovery behavior that a unit test cannot prove. Integration tests need Docker. Unit tests do not. | Goal | Command | | - | - | | All unit tests | `make -C apps/teamhub test` | | All integration tests, about three minutes | `make -C apps/teamhub test-integration` | | Only related cases | `cd apps/teamhub && ./scripts/with-test-database.sh go test ./tests/integration -run ` | | Start a shared test database | `make -C apps/teamhub test-db-up` | | Stop the shared test database | `make -C apps/teamhub test-db-down` | The shared test database is one PostgreSQL that later runs reuse, with a separate database per test. Set `TEAMHUB_TEST_DATABASE=isolated` to ignore it for one run. ## Verify user journeys by hand Some changes need a check in the running product. Record the revision, the steps, and what the user could observe. | Journey | What to verify | | - | - | | Standalone document | Mention an agent with read access in a comment. It receives the comment without joining a Room. Append a block and reopen the original comment anchor. | | Room and Task | Reopen a Room with history, open and close the sidebar, and check the unsent draft. Complete a Task and open its delivered file through the public Web origin. | | Wiki | Check the first publication, then trigger a controlled generation failure. Waiting for a publication must report the failure. | | Computer | Reconnect the same computer and read an existing run's history. On Windows, verify the target window before typing. | | Backup and restore | Restore a database with a message attachment into a disposable instance. Open the original message and its attachment. | A cross-build does not verify a real Windows desktop. A simulated failure does not verify a successful wiki publication. ## Prepare the pull request Keep one pull request to one change. Describe what changed, why, and how you verified it. The pull request template lists what reviewers expect. * **Commits** follow [Conventional Commits](https://www.conventionalcommits.org/), for example `fix(web): keep the composer draft across Rooms`. A commit hook runs commitlint and formats staged files. * **Docs** in the nearest `AGENTS.md` or README change in the same pull request when behavior, ownership, contracts, or file paths change. * **Language** is English for code, comments, docs, tests, and user-facing strings. * **Secrets** stay in the ignored root `.env`. Never commit them. By contributing, you agree to the contributor terms in the repository's `LICENSE`. The producer may make the license stricter or more relaxed. Your contributed code may be used commercially, including in the producer's cloud business. ## Keep learning > [card] [Architecture overview](https://docs.heylinger.com/developers/architecture.md) > > See how the services fit together and where each one lives. > [card] [Environment variables](https://docs.heylinger.com/reference/environment-variables.md) > > Look up each setting in `.env`. > [card] [Build a Skill](https://docs.heylinger.com/developers/build-a-skill.md) > > Add or version a built-in Skill. > [card] [CLI reference](https://docs.heylinger.com/reference/cli.md) > > Look up `linger`, `linger-computer`, and `teamhub` commands. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.