# firetower-cloud/firetower architecture

> Architecture diagram of the GitHub repository firetower-cloud/firetower, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firetower-cloud/firetower
- Repository: https://github.com/firetower-cloud/firetower

## Overview

Firetower is a self-hosted control plane for running coding agents on local or remote machines. A user connects a client to the control plane, configures repositories and hosts, then starts work; the control plane selects a host and uses SSH to reach a worker, which creates an isolated worktree and runs the agent under tmux. Clients also support conversation, task tracking, previews, voice, and fleet management. The tree and README document these capabilities; sampled code confirms selected client and task behavior, so unsampled subsystem wiring is shown only where documented.

Main entry points: [`crates/ft-server/src/api.rs`](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/api.rs) (HTTP API), [`crates/ft-worker/src/runtime.rs`](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/runtime.rs) (Session runtime), [`crates/ft-server/src/tasks.rs`](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/tasks.rs) (Tracker tasks), [`desktop/src/App.tsx`](https://github.com/firetower-cloud/firetower/blob/main/desktop/src/App.tsx) (Desktop app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_desktop["Desktop app<br/>[App.tsx]"]
  node_mobile["Mobile app<br/>[index.tsx]"]
  node_web["Web console<br/>[page.tsx]"]
  node_client_api["Client API<br/>[workspaces.ts]"]
end

subgraph group_control["Control plane"]
  node_server["HTTP API<br/>[api.rs]"]
  node_auth["Accounts and auth<br/>[auth.rs]"]
  node_database[("Control-plane database<br/>[db.rs]")]
  node_fleet["Fleet orchestration<br/>[fleet.rs]"]
  node_ssh["SSH transport<br/>[transport.rs]"]
  node_tasks["Tracker tasks<br/>[tasks.rs]"]
  node_preview["Preview proxy<br/>[preview.rs]"]
  node_vault[("Secrets vault<br/>[vault.rs]")]
  node_updater["Update service<br/>[mod.rs]"]
end

subgraph group_execution["Worker execution"]
  node_worker["Worker entry<br/>[entry.rs]"]
  node_runtime["Session runtime<br/>[runtime.rs]"]
  node_workspace["Git worktree<br/>[git.rs]"]
  node_tmux["Terminal session<br/>[tmux.rs]"]
  node_agent["Coding agent<br/>[agents.rs]"]
end

subgraph group_integrations["Connected services"]
  node_tracker(("Issue tracker"))
  node_git_host(("Git host"))
  node_updater_process["Updater container<br/>[main.rs]"]
end

node_user(("Developer"))

node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_web
node_desktop -->|"requests"| node_client_api
node_client_api -->|"HTTPS"| node_server
node_mobile -->|"HTTPS"| node_server
node_web -->|"HTTPS"| node_server
node_server -->|"authenticates"| node_auth
node_server -->|"reads/writes"| node_database
node_server -->|"dispatches work"| node_fleet
node_fleet -->|"connects to worker"| node_ssh
node_ssh -->|"runs remotely"| node_worker
node_worker -->|"starts session"| node_runtime
node_runtime -->|"creates worktree"| node_workspace
node_runtime -->|"starts terminal"| node_tmux
node_runtime -->|"launches"| node_agent
node_tasks -->|"fetches issues"| node_tracker
node_server -->|"serves task requests"| node_tasks
node_tasks -->|"queries issues"| node_git_host
node_server -->|"serves previews"| node_preview
node_server -->|"manages secrets"| node_vault
node_server -->|"requests updates"| node_updater
node_updater -->|"calls update service"| node_updater_process
node_updater_process -->|"recreates deployment"| node_server

click node_desktop "https://github.com/firetower-cloud/firetower/blob/main/desktop/src/App.tsx"
click node_mobile "https://github.com/firetower-cloud/firetower/blob/main/mobile/app/(tabs)/index.tsx"
click node_web "https://github.com/firetower-cloud/firetower/blob/main/web/app/page.tsx"
click node_client_api "https://github.com/firetower-cloud/firetower/blob/main/desktop/src/api/workspaces.ts"
click node_server "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/api.rs"
click node_auth "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/auth.rs"
click node_database "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/db.rs"
click node_fleet "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/fleet.rs"
click node_ssh "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/transport.rs"
click node_tasks "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/tasks.rs"
click node_preview "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/preview.rs"
click node_vault "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/vault.rs"
click node_updater "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/updates/mod.rs"
click node_worker "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/entry.rs"
click node_runtime "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/runtime.rs"
click node_workspace "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/git.rs"
click node_tmux "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/tmux.rs"
click node_agent "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/agents.rs"
click node_updater_process "https://github.com/firetower-cloud/firetower/blob/main/crates/ft-updater/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_mobile,node_web,node_client_api toneBlue
class node_server,node_auth,node_database,node_fleet,node_ssh,node_tasks,node_preview,node_vault,node_updater toneAmber
class node_worker,node_runtime,node_workspace,node_tmux,node_agent toneMint
class node_tracker,node_git_host,node_updater_process toneRose
class node_user toneIndigo
```

## Components

### Client apps

- [Desktop app](https://github.com/firetower-cloud/firetower/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [Mobile app](https://github.com/firetower-cloud/firetower/blob/main/mobile/app/(tabs)/index.tsx): `mobile/app/(tabs)/index.tsx`
- [Web console](https://github.com/firetower-cloud/firetower/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Client API](https://github.com/firetower-cloud/firetower/blob/main/desktop/src/api/workspaces.ts): `desktop/src/api/workspaces.ts`

### Control plane

- [HTTP API](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/api.rs): `crates/ft-server/src/api.rs`
- [Accounts and auth](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/auth.rs): `crates/ft-server/src/auth.rs`
- [Control-plane database](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/db.rs): `crates/ft-server/src/db.rs`
- [Fleet orchestration](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/fleet.rs): `crates/ft-server/src/fleet.rs`
- [SSH transport](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/transport.rs): `crates/ft-server/src/transport.rs`
- [Tracker tasks](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/tasks.rs): `crates/ft-server/src/tasks.rs`
- [Preview proxy](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/preview.rs): `crates/ft-server/src/preview.rs`
- [Secrets vault](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/vault.rs): `crates/ft-server/src/vault.rs`
- [Update service](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-server/src/updates/mod.rs): `crates/ft-server/src/updates/mod.rs`

### Worker execution

- [Worker entry](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/entry.rs): `crates/ft-worker/src/entry.rs`
- [Session runtime](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/runtime.rs): `crates/ft-worker/src/runtime.rs`
- [Git worktree](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/git.rs): `crates/ft-worker/src/git.rs`
- [Terminal session](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/tmux.rs): `crates/ft-worker/src/tmux.rs`
- [Coding agent](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-worker/src/agents.rs): `crates/ft-worker/src/agents.rs`

### Connected services

- **Issue tracker**
- **Git host**
- [Updater container](https://github.com/firetower-cloud/firetower/blob/main/crates/ft-updater/src/main.rs): `crates/ft-updater/src/main.rs`

### Other components

- **Developer**

## Connections

- Developer → Desktop app: uses
- Developer → Mobile app: uses
- Developer → Web console: uses
- Desktop app → Client API: requests
- Client API → HTTP API: HTTPS
- Mobile app → HTTP API: HTTPS
- Web console → HTTP API: HTTPS
- HTTP API → Accounts and auth: authenticates
- HTTP API → Control-plane database: reads/writes
- HTTP API → Fleet orchestration: dispatches work
- Fleet orchestration → SSH transport: connects to worker
- SSH transport → Worker entry: runs remotely
- Worker entry → Session runtime: starts session
- Session runtime → Git worktree: creates worktree
- Session runtime → Terminal session: starts terminal
- Session runtime → Coding agent: launches
- Tracker tasks → Issue tracker: fetches issues
- HTTP API → Tracker tasks: serves task requests
- Tracker tasks → Git host: queries issues
- HTTP API → Preview proxy: serves previews
- HTTP API → Secrets vault: manages secrets
- HTTP API → Update service: requests updates
- Update service → Updater container: calls update service
- Updater container → HTTP API: recreates deployment