Faheem Code overview
Faheem Code is a control surface for agentic work. From one place, you can manage conversations, files, terminals, model configuration, backends, and automations.
The browser interface connects to one or more backends that run the agent and its tools. By default, that backend runs on your machine, but you can instead use Docker, a VM, Modal, or Faheem Code Cloud. The LLM models can run locally, through a provider API or be accessed through an ACP agent.
When to use Faheem Code
Choose the path that matches where and how you want your agents to run:
| If you want to... | Start here |
|---|---|
| Run Faheem Code locally in a browser | Install Faheem Code |
| Use a sandboxed local environment | Use Docker with Faheem Code |
| Run agents on an always-on machine | VM / Self-Hosted Installation |
| Connect to managed cloud sandboxes | Cloud Backend |
| Use Claude Code, Codex, Gemini CLI, or another ACP agent | ACP Agents |
You can also test a preview build of the native desktop app. Try the desktop preview.
How Faheem Code works
Faheem Code is the browser client. It connects to backend services that own execution and persistent state:
| Concept | What It Means | Why It Matters |
|---|---|---|
| Browser UI | The web interface you open in your browser. | This is where you chat, inspect files, manage settings, and configure automations. |
| Backend | The agent server that runs conversations, tools, settings, secrets, and automations. | This determines where the agent runs and what machine or sandbox it can access. |
| Workspace | The folder, repository, container mount, or cloud sandbox the agent works in. | This determines which files the agent can read and write. |
| Agent and model | The Faheem Code agent or an ACP agent, plus the model credentials it uses. | This determines which LLM or provider receives conversation context and powers the agent. |
The faheem-code launcher can package the client and backend services into one local stack. You can also run the client separately and connect it to services on a VM, in Docker or Kubernetes, or through Faheem Code Cloud or Faheem Code Enterprise.
See Faheem Code Architecture for the complete service and deployment model.
Choosing A trust boundary
Before installing, decide where you want the agent to run and what files it should be able to access.
| Setup | Trust Boundary | Best For |
|---|---|---|
| npm local install | Runs directly on your machine. The agent server can operate on the local filesystem. | Fastest local setup when you trust the machine and understand the file access. |
| Docker | Runs inside a container and only sees the directories you mount. | Local sandboxing and clearer file boundaries. |
| VM or dedicated machine | Runs on the remote host you control. | Always-on agents, heavier compute, team-shared backends, or personal/work separation. |
| Faheem Code Cloud | Runs in managed Faheem Code Cloud sandboxes. | Cloud execution without maintaining your own machine or VM backend. |
What happens when you close the terminal?
For a local npm or npx installation, closing the terminal stops the Faheem Code process, so the browser UI can no longer use its local backend. Start Faheem Code again with the same command to continue. A Docker container, VM, or cloud backend continues running until that backend is stopped.
See Install to restart Faheem Code and Troubleshooting if the browser cannot reconnect.
Model access
Faheem Code supports several model access patterns:
- Direct provider key — enter an API key from Anthropic, OpenAI, Google, or another supported provider.
- Faheem Code LLM API key — use an Faheem Code LLM API key for verified hosted models.
- ACP agent subscription login — use a signed-in provider, such as Claude Code, Codex, or Gemini, when the backend runs on the same machine as that login.
- Local or OpenAI-compatible provider — connect providers such as Ollama, LM Studio, LiteLLM, or a compatible gateway through model settings.
See Manage LLM Profiles and ACP Agents for details.
How it fits with other Faheem Code products
| Surface | Best for | Where it runs |
|---|---|---|
| Faheem Code | Browser-first agent work, workspace access, and automations | The backend you select: your machine, Docker, a VM, Modal, or Cloud |
| Faheem Code SDK | Building agent-powered Python applications | Your application and the workspace you configure |
| Faheem Code Cloud | Fully managed hosted execution | Managed Faheem Code Cloud infrastructure |
| Local GUI (Legacy) | Following older Docker-based Local GUI documentation | Your local Docker environment |
Faheem Code vs "faheemcode serve"
faheem-code starts the current Faheem Code UI and backend stack. faheemcode serve starts the legacy Faheem Code CLI GUI server and will not run if you have only installed faheem-code.
How conversations and workspaces are isolated
A conversation belongs to one active backend and has its own history, agent configuration, and backend-managed state. Its workspace is the folder, mount, or sandbox attached to that backend. Start a new conversation for a separate task, or branch a conversation to explore another path while preserving the original.
Before you start
For the normal local setup, you need:
- Node.js 22.12 or later
npm- A model access path, such as a provider API key, Faheem Code Cloud LLM key, ACP subscription login, or local model server
- A folder, repository, or project workspace for the agent to work in
For a sandboxed local setup, use Docker instead of the direct npm backend path.