Skip to main content

Setup

System requirements​

A system with a modern processor and a minimum of 4GB RAM is recommended to run Faheem Code.

Prerequisites​

macOS

Docker Desktop

  1. Install Docker Desktop on Mac.
  2. Open Docker Desktop, go to Settings > Advanced and ensure Allow the default Docker socket to be used is enabled.
Linux

Docker Desktop

  1. Install Docker Desktop on Linux.
Windows

WSL

  1. Install WSL.
  2. Run wsl --version in PowerShell and confirm Default Version: 2.

Ubuntu (Linux Distribution)

  1. Install Ubuntu: wsl --install -d Ubuntu in PowerShell as Administrator.
  2. Restart computer when prompted.
  3. Open Ubuntu from Start menu to complete setup.
  4. Verify installation: wsl --list should show Ubuntu.

Docker Desktop

  1. Install Docker Desktop on Windows.
  2. Open Docker Desktop, go to Settings and confirm the following:
  • General: Use the WSL 2 based engine is enabled.
  • Resources > WSL Integration: Enable integration with my default WSL distro is enabled.

Start the app​

We recommend using uv for the best Faheem Code experience. uv provides better isolation from your current project's virtual environment and is required for Faheem Code' default MCP servers (like the fetch MCP server).

Install uv (if you haven't already):

See the uv installation guide for the latest installation instructions for your platform.

Install Faheem Code:

uv tool install faheemcode --python 3.12

Launch Faheem Code:

# Launch the GUI server
faheemcode serve

# Or with GPU support (requires nvidia-docker)
faheemcode serve --gpu

# Or with current directory mounted
faheemcode serve --mount-cwd

This will automatically handle Docker requirements checking, image pulling, and launching the GUI server. The --gpu flag enables GPU support via nvidia-docker, and --mount-cwd mounts your current directory into the container.

Upgrade Faheem Code:

uv tool upgrade faheemcode --python 3.12
Alternative: traditional pip installation

If you prefer to use pip and have Python 3.12+ installed:

# Install Faheem Code
pip install faheemcode

# Launch the GUI server
faheemcode serve

Note that you'll still need uv installed for the default MCP servers to work properly.

Option 2: using Docker directly​

Docker command (click to expand)
docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/alsairy/faheem-code-agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.faheem-code:/.faheem-code \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name faheem-code-app \
    ghcr.io/alsairy/faheem-code-app:1.8

You'll find Faheem Code running at http://localhost:3000.

Setup​

After launching Faheem Code, you must select an LLM Provider and LLM Model and enter a corresponding API Key. This can be done during the initial settings popup or by selecting the Settings button (gear icon) in the UI.

If the required model does not exist in the list, in Settings under the LLM tab, you can toggle Advanced options and manually enter it with the correct prefix in the Custom Model text box. The Advanced options also allow you to specify a Base URL if required.

Getting an API key​

Faheem Code requires an API key to access most language models. Here's how to get an API key from the recommended providers:

Faheem Code (recommended)
  1. Log in to Faheem Code Cloud.
  2. Go to the Settings page and navigate to the API Keys tab.
  3. Copy your LLM API Key.

Faheem Code provides access to state-of-the-art agentic coding models with competitive pricing. Learn more about Faheem Code LLM provider.

Anthropic (Claude)
  1. Create an Anthropic account.
  2. Generate an API key.
  3. Set up billing.
OpenAI
  1. Create an OpenAI account.
  2. Generate an API key.
  3. Set up billing.
Google (Gemini)
  1. Create a Google account if you don't already have one.
  2. Generate an API key.
  3. Set up billing.
Local LLM (e.g. LM Studio, llama.cpp, Ollama)

If your local LLM server isn’t behind an authentication proxy, you can enter any value as the API key (e.g. local-key, test123) — it won’t be used.

Consider setting usage limits to control costs.

Using a local LLM​

To run Faheem Code with a locally hosted language model instead of a cloud provider, see the Local LLMs guide for setup instructions.

Setting up search engine​

Faheem Code can be configured to use a search engine to allow the agent to search the web for information when needed.

To enable search functionality in Faheem Code:

  1. Get a Tavily API key from tavily.com.
  2. Enter the Tavily API key in the Settings page under LLM tab > Search API Key (Tavily)

For more details, see the Search Engine Setup guide.

Versions​

The docker command above pulls the most recent stable release of Faheem Code. You have other options as well:

  • For a specific release, replace $VERSION in faheemcode:$VERSION and runtime:$VERSION, with the version number. For example, 0.9 will automatically point to the latest 0.9.x release, and 0 will point to the latest 0.x.x release.
  • For the most up-to-date development version, replace $VERSION in faheemcode:$VERSION and runtime:$VERSION, with main. This version is unstable and is recommended for testing or development purposes only.

Next steps​