Install Faheem Code

The faheem-code launcher can run the Canvas client with Agent Server, Automation Server, and ingress as an all-in-one local stack. Use npm or npx for direct local execution, or Docker for a containerized stack with explicit project mounts. You can also run the client separately and connect it to an existing backend.

Warning

Treat agents and ACP processes as untrusted: they can run shell commands, read files, write files, and use connected tools within their execution environment. Faheem Code is the client and does not provide isolation. If the backend runs directly on your machine, the agent can act with your user account's permissions. Use a container, sandbox, or VM to define a tighter boundary. Before exposing backend services to a network you do not control, review VM / Self-Hosted Installation.

Choose an install method

Method	Use It When	What The Agent Can Access
npm local install	You want the quickest local browser setup.	Runs directly on your machine and can work in local workspaces you open.
Docker	You want a local sandbox with clearer file boundaries.	Runs inside a container and can access mounted project directories.
npx	You want to try Faheem Code without installing the package globally.	Runs directly on your machine and can work in local workspaces you open.
VM / self-hosted	You want an always-on backend, stronger hardware, or a team-accessible server.	Runs on the VM or dedicated host you configure.
From source	You are contributing to Faheem Code or changing the frontend/backend stack.	Runs your local development checkout.

Note

If you are new to Faheem Code, use npx for a quick first run or npm local install if you want a reusable faheem-code command. Use Docker when you specifically want sandboxing.

Verify prerequisites

Install Node.js 22.12 or later and uv, then verify both tools are available:

node --version
npm --version
uv --version

If uv or uvx is missing, install uv before starting Faheem Code. The local agent server runtime uses it.

Install Docker and make sure the Docker daemon is running:

docker --version
docker ps

On macOS and Windows, open Docker Desktop before running the container.

Install Node.js 22.12 or later and uv, then verify the tools are available:

node --version
npm --version
uv --version

If uv or uvx is missing, install uv before starting Faheem Code. The local agent server runtime uses it.

Note

Termux and other mobile Linux environments are not a primary supported target. For the most reliable local setup, use macOS, Linux, Windows with PowerShell, or Windows with WSL2.

Install and run

Install the published package globally:

npm install -g @faheem-code/app

Start the full local stack:

faheem-code

Faheem Code starts on http://localhost:8000 by default. If your browser does not open automatically, open that URL manually.

Create host directories for persistent settings and project files, then start the container.

macOS / Linux:

mkdir -p ~/projects ~/.faheem-code

docker run -it --rm \
  -p 8000:8000 \
  -v ~/.faheem-code:/home/faheemcode/.faheem-code \
  -v ~/projects:/projects \
  ghcr.io/smart-national-solution/faheem-code-app:latest

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.faheem-code", "$env:USERPROFILE\projects" | Out-Null

docker run -it --rm `
  -p 8000:8000 `
  -v "$($env:USERPROFILE)\.faheem-code:/home/faheemcode/.faheem-code" `
  -v "$($env:USERPROFILE)\projects:/projects" `
  ghcr.io/smart-national-solution/faheem-code-app:latest

The Docker image serves Faheem Code at http://localhost:8000/canvas. The agent can access project files under the mounted /projects directory.

Note

PowerShell uses backticks (`) for line continuation. If Docker reports that it cannot connect to the daemon, start Docker Desktop and run the command again.

Run the latest published package without installing it globally:

npx @faheem-code/app

Faheem Code starts on http://localhost:8000 by default. If your browser does not open automatically, open that URL manually.

Use npx when you want to try Faheem Code once, avoid global package installs, or work around a shell PATH issue with the global faheem-code command.

Use the source workflow only when you want to modify Faheem Code itself:

git clone https://github.com/SMART-National-Solution/faheem-code-app.git
cd Faheem Code
npm install
npm run dev

For development-specific environment variables and commands, see Contribute / Development.

Confirm it started

After startup:

1. Open http://localhost:8000.
2. Confirm the default local backend shows as connected.
3. Open Settings > LLM and configure a model.
4. Choose Open Workspace before starting a conversation if you want the agent to work in a specific folder.
5. Return to the home screen and start a conversation.

If the page does not load, check the terminal where Faheem Code is running. Common causes are a missing prerequisite, a busy port, or Docker not running.

Run Faheem Code again

After you close the terminal or restart your computer, start Faheem Code with the same command you used to install it. Keep that terminal or Docker container running while you use the browser UI.

faheem-code

npx @faheem-code/app

Run the same docker run command from Install and Run. The browser connects to the host port you map, while the backend and model configuration run where the Faheem Code process or container is running.

If the UI opens but the backend is disconnected or a model cannot respond, use Troubleshooting to identify the affected part of the stack.

Common startup options

Option	Description
-p, --port <port>	Set the ingress port. The default is 8000.
--backend-only	Start only the backend behind ingress. Use this for a headless backend on a local machine, VM, or server.
--frontend-only	Start only the static frontend behind ingress. Use this when connecting a local UI to a remote backend.
--public	Enable public mode. Requires LOCAL_BACKEND_API_KEY and is intended for deployments reachable beyond localhost.
-v, --version	Show the version number.
--info	Show version and stack configuration details.
-h, --help	Show built-in help.

If port 8000 is already in use, start Faheem Code on another port:

faheem-code --port 3000

Environment variables

Variable	Purpose
LOCAL_BACKEND_API_KEY	API key for the server. Required in --public mode; optional for local use because Faheem Code can auto-generate and persist one.
FC_SECRET_KEY	Secret used to protect stored settings and secrets.
FC_AGENT_SERVER_VERSION	Pin a specific agent server version, such as 0.1.0.
PORT	Ingress port inside the Docker container. Map it with -p <host>:<PORT>.

Stop Faheem Code

Return to the terminal running Faheem Code and press Ctrl+C.

Return to the terminal running Faheem Code and press Ctrl+C.

Return to the terminal running the container and press Ctrl+C.

If the container is running in the background, stop it with:

docker ps
docker stop <container-id-or-name>

Update Faheem Code

Stop Faheem Code, then reinstall the latest package:

npm install -g @faheem-code/app@latest
faheem-code --version

Stop Faheem Code, then run the latest package:

npx @faheem-code/app@latest

Stop the running container, pull the latest image, then run the container again:

docker pull ghcr.io/smart-national-solution/faheem-code-app:latest

Your settings and conversation data are stored outside the package or image when you use the documented ~/.faheem-code mount.

Note

Recover or reset: Use Troubleshooting when the browser is blank, a port is busy, the backend is unreachable, a model or API key fails, or an update or uninstall is stuck. It also explains clean removal and reinstall.

Uninstall Faheem Code

Stop any running Faheem Code process, then uninstall the package:

npm uninstall -g @faheem-code/app

If Windows reports that uv.exe or another file is in use, close terminals running Faheem Code, stop related processes, and run the uninstall command again.

There is no Faheem Code package to uninstall when you use npx. Stop the running process with Ctrl+C.

If you want to clear downloaded package cache entries, use npm's cache commands:

npm cache verify

Stop any running container, then remove the image if you no longer need it:

docker ps
docker stop <container-id-or-name>
docker rmi ghcr.io/smart-national-solution/faheem-code-app:latest

Uninstalling the package or image does not automatically remove your persisted data. If you want to delete local settings, secrets, and conversation history, remove the persistence directory you mounted or used, such as ~/.faheem-code.

Desktop app (preview build)

The Faheem Code desktop app for macOS, Windows, and Linux is an early preview build ready for user testing. It bundles the Node.js and uv runtimes, so you do not need to install prerequisites or keep a terminal open.

Note

Please join the Faheem Code Slack community to share feedback and open an issue for problems you find while testing the preview.

Install and run

Download the installer for your operating system from the Faheem Code releases page.

macOS (Apple silicon)

1. Download the Faheem-Code-<version>-arm64.dmg file.
2. Open the disk image and drag Faheem Code to Applications.
3. Launch Faheem Code from Applications.

Pre-built desktop releases support Apple silicon Macs. On an Intel Mac, use the npm or from-source installation method.

Windows

1. Download the Faheem-Code-Setup-<version>.exe installer.
2. Run the installer. If Windows SmartScreen prompts you, confirm that you want to continue.
3. Launch Faheem Code from the Start menu.

Linux

1. Download the Faheem-Code-<version>.AppImage or Faheem-Code-<version>.deb installer.
2. For the AppImage, make the file executable and run it. For the deb, install it with your package manager (for example, sudo apt install ./Faheem-Code-<version>.deb).
3. Launch Faheem Code from your applications menu.

The desktop app starts its local backend automatically. During startup, select Show details to view and copy the live startup log. This is useful if startup takes longer than expected or fails.

Troubleshooting and lifecycle

On macOS, the app is ad-hoc signed. If macOS reports that Faheem Code is damaged or cannot be opened, clear its quarantine attribute in Terminal, then launch it again:

xattr -d com.apple.quarantine /Applications/Agent\ Canvas.app

Do not use xattr -cr; that command does not clear this issue on macOS Sequoia.

To stop the app, quit Faheem Code from its application menu or window controls. To update it, download and install the latest desktop release; Settings > Application also shows the installed version and can check for updates. To uninstall, quit the app and move it to the Trash on macOS or uninstall it from Installed apps on Windows.

Next steps

• First Time Setup
• Connect and Manage Backends
• Manage LLM Profiles
• Use Docker with Faheem Code
• Troubleshooting