Installation

Note

Windows users: All commands below should be run inside the WSL terminal (Ubuntu). Use wsl -d Ubuntu in PowerShell or search "Ubuntu" in the Start menu to access the Ubuntu terminal. We also have a step-by-step video tutorial available.

Installation methods

Requires Python 3.12+ and uv installed.

Install Faheem Code:

uv tool install faheemcode --python 3.12

Run Faheem Code:

faheemcode

Upgrade Faheem Code:

uv tool upgrade faheemcode --python 3.12

Install the Faheem Code CLI binary with the install script:

curl -fsSL https://install.faheemcode.ai/install.sh | sh

Then run:

faheemcode

Note

Your system may require you to allow permissions to run the executable.

macOS

When running the Faheem Code CLI on Mac, you may get a warning that says "faheemcode can't be opened because Apple cannot check it for malicious software."

1. Open System Settings.
2. Go to Privacy & Security.
3. Scroll down to Security and click Allow Anyway.
4. Rerun the Faheem Code CLI.

Screenshot: mac-security.

1. Set the following environment variable in your terminal:

   • SANDBOX_VOLUMES to specify the directory you want Faheem Code to access (See using SANDBOX_VOLUMES for more info)

2. Ensure you have configured your settings before starting:

   • Set up ~/.faheem-code/settings.json with your LLM configuration

3. Run the following command:

docker run -it \
    --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/smart-national-solution/faheem-code-agent-server \
    -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
    -e SANDBOX_USER_ID=$(id -u) \
    -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.faheem-code:/root/.faheem-code \
    --add-host host.docker.internal:host-gateway \
    --name faheem-code-cli-$(date +%Y%m%d%H%M%S) \
    python:3.12-slim \
    bash -c "pip install uv && uv tool install faheemcode --python 3.12 && faheemcode"

The -e SANDBOX_USER_ID=$(id -u) is passed to the Docker command to ensure the sandbox user matches the host user's permissions. This prevents the agent from creating root-owned files in the mounted workspace.

First run

The first time you run the CLI, it will take you through configuring the required LLM settings. These will be saved for future sessions in ~/.faheem-code/settings.json.

The conversation history will be saved in ~/.faheem-code/conversations.

Note

If you're upgrading from a CLI version before release 1.0.0, you'll need to redo your settings setup as the configuration format has changed.

Next steps

• Quick Start - Learn the basics of using the CLI
• MCP Servers - Configure MCP servers