# Prerequisites for Running Freebuff: Complete Setup Guide

> Discover the essential prerequisites for running Freebuff. Learn how to set up Bun, npm, Node.js, Docker, Git, and your .env.local file for a smooth development experience.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-21

---

**To run Freebuff, you need the Bun runtime (for all development tasks), npm with Node.js (for global CLI installation), Docker (for local development with databases and browsers), Git (for repository cloning), and a configured `.env.local` file for environment variables.**

Freebuff is a TypeScript monorepo developed by CodebuffAI that provides CLI tooling for AI-assisted coding workflows. Understanding the prerequisites for running Freebuff ensures you can build the SDK, execute the full test suite, and deploy the CLI without encountering environment-related failures. This guide references specific files from the repository to provide authoritative setup instructions.

## Core Runtime Dependencies

### Bun (Required)

**Bun** serves as the primary JavaScript/TypeScript runtime and package manager for Freebuff. All build scripts, test commands, and development workflows depend exclusively on Bun rather than Node.js.

According to the [`README.md`](https://github.com/CodebuffAI/freebuff/blob/main/README.md) (lines 21-30), the repository uses Bun for every critical operation:

- `bun install` – Installs monorepo dependencies
- `bun up` – Updates packages
- `bun test` – Executes the test suite across packages
- `bun start-cli` – Launches the interactive CLI from source

Install Bun using the official installer:

```bash
curl https://bun.sh/install | bash

```

### npm and Node.js (Required for Global Installation)

While Bun handles development, **npm** remains necessary for global CLI distribution. The [`README.md`](https://github.com/CodebuffAI/freebuff/blob/main/README.md) (lines 24-27) documents the global installation method:

```bash
npm install -g freebuff

```

This command installs the compiled binary to your system path, allowing you to invoke `freebuff` from any directory. Node.js must be present on your system to support npm operations, even if Bun executes the runtime code.

## Local Development Infrastructure

### Docker (Optional but Recommended)

Docker is **required for full local development** according to [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md) (lines 81-83). The CI pipeline and local test suites spin up external services including databases and browser environments that depend on containerization.

The file [`scripts/ci/bun-test-failures.ts`](https://github.com/CodebuffAI/freebuff/blob/main/scripts/ci/bun-test-failures.ts) executes `bun test` across packages with Docker-dependent service orchestration. Without Docker, you cannot run integration tests that validate database connectivity or browser automation features.

Start Docker Desktop (or your system daemon) before executing:

```bash
bun test

```

### Environment Configuration (.env.local)

A minimal **`.env.local`** file supplies placeholder values for environment variables consumed by the SDK and test suites. As documented in [`docs/testing.md`](https://github.com/CodebuffAI/freebuff/blob/main/docs/testing.md) (lines 9-15), CI expects this file to exist before running any test commands.

The repository includes templates within `packages/*/bunfig.toml` that preload [`sdk/test/setup-env.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/test/setup-env.ts). Create your local environment file:

```bash
touch .env.local

```

Populate it with placeholder values required by the specific packages you intend to build, typically including API keys and database connection strings for testing.

## System Requirements

### Git

**Git** is mandatory for repository cloning and for agents that execute Bash scripts within the Freebuff ecosystem. The [`WINDOWS.md`](https://github.com/CodebuffAI/freebuff/blob/main/WINDOWS.md) guide (lines 19-26) explicitly mentions installing Git for Windows to ensure proper Bash support on Windows environments.

Clone the repository:

```bash
git clone https://github.com/CodebuffAI/freebuff.git
cd freebuff

```

### Operating System Support

Freebuff supports **Linux** and **macOS** natively. For **Windows** development, the repository provides specific instructions in [`WINDOWS.md`](https://github.com/CodebuffAI/freebuff/blob/main/WINDOWS.md) for running via Git Bash or Windows Subsystem for Linux (WSL). Native Windows CMD or PowerShell without WSL is not recommended due to Bash script dependencies throughout the build pipeline.

## Step-by-Step Installation

Follow these steps to satisfy all prerequisites and run Freebuff from source:

1. **Install Node.js** (includes npm):
   ```bash
   # Verify installation

   node --version
   npm --version
   ```

2. **Install Bun**:
   ```bash
   curl https://bun.sh/install | bash
   ```

3. **Clone and navigate to the repository**:
   ```bash
   git clone https://github.com/CodebuffAI/freebuff.git
   cd freebuff
   ```

4. **Install dependencies**:
   ```bash
   bun install
   ```

5. **Configure environment** (create empty placeholder):
   ```bash
   touch .env.local
   ```

6. **Build the SDK** (required before CLI usage):
   ```bash
   bun run build:sdk
   ```

7. **Build the Freebuff binary** (optional, for packaged CLI):
   ```bash
   bun run build:freebuff
   ```

8. **Run the CLI**:
   ```bash
   # From source

   bun start-cli
   
   # Or install globally

   npm install -g freebuff
   freebuff
   ```

## Summary

- **Bun** is the mandatory runtime for development, testing, and building the TypeScript monorepo.
- **npm/Node.js** enables global installation of the `freebuff` CLI binary.
- **Docker** is required for running the complete test suite and developing features that depend on external services like databases.
- **`.env.local`** must exist in the repository root to satisfy CI and development environment requirements.
- **Git** is required for repository operations and Bash script execution across all platforms.
- **Windows users** must use Git Bash or WSL due to Bash dependencies in build scripts.

## Frequently Asked Questions

### Can I run Freebuff without Docker?

You can build the SDK and run basic CLI commands without Docker, but you cannot execute the full test suite. According to [`CONTRIBUTING.md`](https://github.com/CodebuffAI/freebuff/blob/main/CONTRIBUTING.md), local development requires Docker for services that CI spins up, including database containers and browser environments. Without Docker, `bun test` will fail on integration tests.

### Is Bun strictly required, or can I use Node.js?

**Bun is strictly required** for development workflows. While npm installs the global CLI package, all repository scripts in [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) and build processes invoke `bun` commands. Node.js alone cannot execute the monorepo's build pipeline or test suite.

### What environment variables need to be in `.env.local`?

The specific variables depend on which packages you are building. The [`docs/testing.md`](https://github.com/CodebuffAI/freebuff/blob/main/docs/testing.md) file indicates that `.env.local` supplies values for the SDK and test suites, typically including API endpoints and service credentials. The repository includes templates in `packages/*/bunfig.toml` that reference [`sdk/test/setup-env.ts`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/test/setup-env.ts) for automatic loading.

### How do I install Freebuff on Windows?

Windows development requires Git for Windows (providing Bash support) or WSL. The [`WINDOWS.md`](https://github.com/CodebuffAI/freebuff/blob/main/WINDOWS.md) file provides explicit instructions for Git Bash setup, Docker configuration, and proxy handling. Do not attempt to build using native Windows CMD, as the build scripts rely on Bash commands throughout the pipeline.