Faheem Code architecture
Faheem Code is the browser client and control center for Faheem Code conversations and automations. It presents backend state and sends requests to backend services; it is not an agent runtime or sandbox. Agent Server or an ACP agent CLI executes tools, and the selected workspace or sandbox provides the execution boundary.
Core components
| Component | Responsibility | Source |
|---|---|---|
| Faheem Code | Browser interface for conversations, files, settings, backends, and automations | alsairy/faheem-code-app |
| Agent Server | Runs conversations, agents, tools, and workspace operations; streams events to clients | alsairy/faheem-code-sdk |
| Automation Server | Stores schedules and event triggers, tracks runs, and dispatches conversations | alsairy/faheem-code-automation |
| Workspace or sandbox | Defines which files, processes, credentials, and networks an agent can access | Deployment-specific |
Sandbox Server is a community-driven standalone API and sandbox control plane. Learn more about Sandbox Server.
Service relationships
The normal browser path is Browser → Faheem Code → selected backend. Agent Server owns conversation execution. Automation Server owns scheduled and event-driven run lifecycle. A backend distribution can expose both services behind one URL, but they remain separate responsibilities.
A remote backend uses the same Agent Server API as a local backend. The Agent Server can run on another machine, or in a separate container on the same machine as Canvas. Faheem Code Cloud and Faheem Code Enterprise are managed backend platforms: their platform control planes create conversation sandboxes that host Agent Server.
Client and launcher boundaries
Faheem Code can refer to two related surfaces:
- Canvas client — The React browser application. It renders state and sends requests to backend services.
faheem-codelauncher and distributions — Packaging that can start the Canvas client, Agent Server, Automation Server, and ingress together.
The launcher supports split modes:
| Mode | Services started |
|---|---|
faheem-code | Canvas client, Agent Server, Automation Server, and ingress |
faheem-code --frontend-only | Canvas client and ingress |
faheem-code --backend-only | Agent Server, Automation Server, and ingress |
Docker and Helm packages can also bundle the client and backend services. A bundled deployment changes how services are installed, not which component owns execution or isolation.
Execution and isolation
When you send a message, Faheem Code sends it to the selected backend. Agent Server starts or resumes the conversation, runs the selected agent, invokes tools, updates backend state, and streams events to Canvas.
The workspace determines the execution boundary:
| Execution environment | Execution and isolation boundary |
|---|---|
| Host process | Agent Server and tools run directly on the backend host without container isolation. If the backend is remote, that host—not the browser's machine—is the execution boundary. |
| Docker or Kubernetes | Agent Server and tools run inside the configured container or pod with its mounts and network policy. |
| Faheem Code Cloud or Enterprise | The managed platform creates and operates the conversation sandbox that hosts Agent Server. |
Connecting Canvas to a remote backend does not grant the browser direct access to that backend's filesystem. Canvas displays files and terminal output returned by Agent Server.
State ownership
State belongs to backend services rather than the browser client:
- Agent Server stores conversation history, agent and LLM profiles, secrets, MCP configuration, and related settings.
- Automation Server stores automation definitions, schedules, events, and run history.
- The workspace or sandbox stores files produced or changed by the agent.
- Faheem Code stores connection information needed to reach configured backends.
Switching backends changes which backend-managed conversations, settings, automations, and workspaces Canvas displays.
Deployment patterns
| Pattern | Relationship |
|---|---|
| Local all-in-one | The launcher starts Canvas and local backend services on one machine. |
| Self-hosted backend services | You deploy Agent Server, and optionally Automation Server, in another process, on a VM, in Docker or Kubernetes, or on Modal. Canvas connects to the deployment as a remote backend. |
| Managed platform | Canvas connects to Faheem Code Cloud or Faheem Code Enterprise, which operate their backend and sandbox infrastructure. |