# Firetower documentation Complete documentation, generated from the same content as the website. Screenshots show sample data. For a topic index, see https://usefiretower.com/llms.txt. --- # Firetower documentation > Set up your workspace. Run your first agent team. Keep your installation healthy. Source: https://usefiretower.com/docs New to Firetower? [Start with the key concepts](https://usefiretower.com/docs/concepts) for a visual introduction. [For your team ## Join an installation Download the app and connect to your company’s Firetower. **Get started ↗**](https://usefiretower.com/docs/join) [For administrators ## Deploy Firetower Install the control plane, add a machine and make it ready for your team. **Installation guide ↗**](https://usefiretower.com/docs/install-firetower) ## From setup to your first result [01 Connect an agent account](https://usefiretower.com/docs/accounts) [02 Connect your repositories](https://usefiretower.com/docs/git) [03 Run your first task](https://usefiretower.com/docs/first-run) [04 Build an agent team](https://usefiretower.com/docs/teams) ## Find the right guide | You want to… | Start here | | --- | --- | | Keep work running after closing your laptop | [How Firetower runs](https://usefiretower.com/docs/architecture) | | Share skills, profiles and subscriptions | [Share resources](https://usefiretower.com/docs/sharing) | | Continue when an account reaches its limit | [Configure fallback](https://usefiretower.com/docs/fallback) | | Maintain a company installation | [Updates](https://usefiretower.com/docs/updates) and [backups](https://usefiretower.com/docs/backups) | **Already using Firetower?** The desktop app is where you run work and configure resources. The administration site manages people and company settings. --- # Download and connect > Connect the app to an installation your company already runs. Source: https://usefiretower.com/docs/join Open the desktop app. This is where you enter the Firetower domain provided by your administrator. ![Desktop connection screen](https://usefiretower.com/product/guide-join-page-light.webp) Desktop connection screen. Desktop app · sample data. Select to enlarge. ## Before you start - Get your Firetower URL and sign-in details from an administrator. - Connect to your company VPN if the installation is private. - Use macOS or Windows for the desktop app. iOS and Android are available for mobile access. ## Connect from your computer 1. **Open your Firetower URL in a browser.** Sign in. Replace a temporary password when prompted. 2. **Download the desktop app from the installation’s download page.** Choose macOS or Windows. Install and open it. 3. **Enter the same Firetower URL in the app.** Complete sign-in with your own account. 4. **Check access.** Open Machines and check that a machine is available to you. Connect an agent account, or use one your team has shared. **Expected result** The app opens your company’s installation. An empty workspace list is normal on your first visit. ## If you cannot connect | What you see | What to check | | --- | --- | | Server cannot be reached | Open the same URL in a browser on this device. Check the VPN and the hostname. | | Sign-in rejected | Use your Firetower credentials, not your GitHub or agent account. Ask an administrator to reset your password if needed. | | No machines available | Ask for access to a shared machine. Administrators must add a worker before anyone can run work. | Next: [connect an agent account](https://usefiretower.com/docs/accounts) or [start your first task](https://usefiretower.com/docs/first-run) . --- # Run your first task > Start with a small change you can review. Source: https://usefiretower.com/docs/first-run Open **Workspaces** in the desktop app. Use the composer to start a task. ![Workspaces: the new-work composer](https://usefiretower.com/product/guide-workspaces-page-light.webp) Workspaces: the new-work composer. Desktop app · sample data. Select to enlarge. ## Before you start - An online machine you can use. - A connected agent account, or access to a shared account. - Access to a repository for a coding task. You can also [work without a repository](https://usefiretower.com/docs/workspaces) . ## Start the work 1. **Open the new-work composer.** Choose the repository and a machine. 2. **Choose an agent and account.** Use a profile if your team has already created one. Check the model and permission settings. 3. **Give it a bounded task.** State the result you want and how it should check its work. 4. **Start the task.** Read the conversation and answer permission requests as they appear. ``` Find one unclear error message in this repository. Improve the wording without changing behavior. Run the relevant checks and summarize the change. ``` ## Check the result - Review the changed files and the agent’s test results. - Ask for revisions in the same conversation. - Open a pull request or merge request when you are ready. Review and merge through your normal process. **Keep running** Closing the client does not stop the agent. The worker machine must stay awake and connected to the services the task needs. Next: [review and ship changes](https://usefiretower.com/docs/review) . --- # Key concepts > Understand what runs the work, where it runs and who can access it. Source: https://usefiretower.com/docs/concepts One task, three parts Example task **Fix the checkout timeout.** [What does the work **Agent + profile + skills** A configured agent starts a session.](https://usefiretower.com/docs/concepts-agents)[Where it runs **Workspace on a machine** The session works with files there.](https://usefiretower.com/docs/concepts-work)[Who can access it **People + permissions** Sharing controls access to resources.](https://usefiretower.com/docs/concepts-access) The agent’s settings, working files and access rules are separate parts of the same task. ## Learn the vocabulary **[Agents, profiles and skills](https://usefiretower.com/docs/concepts-agents)** Agent, harness, model, account, profile, skill and agent team. **[Workspaces and sessions](https://usefiretower.com/docs/concepts-work)** Workspace, session, subagent and sub-workspace. **[Machines and infrastructure](https://usefiretower.com/docs/architecture)** Machine, worker, control plane and client. **[Sharing and permissions](https://usefiretower.com/docs/concepts-access)** Person, company team, resource, directory, ownership and access level. **[Tasks and results](https://usefiretower.com/docs/concepts-results)** Task, repository, branch, artifact and preview. ## Three distinctions to remember - **A profile is a saved setup.** A session is an agent using that setup to do work. - **A workspace contains files.** A Firetower directory groups resources for sharing. - **An agent team does the work.** A company team groups people for access. Put it into practice [Run your first task](https://usefiretower.com/docs/first-run) --- # Agents, profiles and skills > Choose the agent, give it a role and equip it for the task. Source: https://usefiretower.com/docs/concepts-agents From saved setup to running work Agent profile **Code reviewer** Agent **Codex** Instructions **Review the diff** Skill **Review checklist** ↓ Start with a model and an account **Reviewer session** Reads the changes and reports findings. The profile is reusable. Each session is a new instance of work. ## Agent, model and account **Agent / harness** The software that uses a model and tools to do work. Claude Code and Codex are examples. The harness manages the conversation and tool execution. **Model** The AI model the agent uses. Available models and controls depend on the selected agent. **Agent account** The connected subscription or API credential that authorizes usage. Sharing an account shares its allowance. ## Profile, skill and team **Agent profile** Saved instructions and defaults for a job, such as Code reviewer. It can select an agent, account, skills and execution settings. **Skill** Reusable instructions and supporting files for a specific task. For example, a review checklist can be used by several profiles. **Agent team** A lead and the specialist profiles it can delegate to. A Manager can delegate; an Operator does its assigned work. Profiles and skills are optional. A profile defines the role; a skill supplies a reusable method. Neither is a running agent until work starts. See profiles in the redesigned app ![Saved agent profiles](https://usefiretower.com/product/profiles-light.webp) Saved agent profiles · supplied redesign prototype, not a release screenshot Put it into practice [Create a profile](https://usefiretower.com/docs/profiles) [Import a skill](https://usefiretower.com/docs/skills) [Build an agent team](https://usefiretower.com/docs/teams) --- # Workspaces and sessions > A workspace holds files. A session is an agent working with them. Source: https://usefiretower.com/docs/concepts-work One workspace can hold several sessions Workspace **Checkout fix** Example: one repository and shared branch **Lead session** Coordinates the fix **Reviewer session** Reads the same files ↳ Sub-workspace · separate placement **Test the checkout fix** QA session · separate working files and branch Example with a repository. The reviewer shares the lead’s workspace; QA runs in a sub-workspace. ## The four concepts **Workspace** A working directory on a machine, with its files and associated sessions. It can have a repository or contain work without git. **Session** One agent conversation and execution context. It can contain several turns, tool calls and approvals. Several sessions can work in one workspace. **Subagent** An agent session started by a lead to handle part of the task. It returns its result to the lead. **Sub-workspace** A separate workspace created for delegated work. It appears beneath the lead’s work and has its own files and, for git-backed work, branch. ## Two places for delegated work | Placement | What it means | | --- | --- | | Same workspace | A separate session uses the lead’s files and branch. Changes are shared immediately. | | Its own workspace | A separate workspace holds the delegated work. Its changes may need to be integrated. | A subagent does not always create a sub-workspace. A sub-workspace is also not a folder nested inside the lead’s files. See delegated work in the redesigned app ![Lead and delegated work](https://usefiretower.com/product/team-light.webp) Lead and delegated work · supplied redesign prototype, not a release screenshot Put it into practice [Create a workspace](https://usefiretower.com/docs/workspaces) [Manage a run](https://usefiretower.com/docs/runs) [Build an agent team](https://usefiretower.com/docs/teams) --- # Machines and infrastructure > Your app controls the work. Your machines execute it. Source: https://usefiretower.com/docs/architecture ## The parts of an installation **Machine** A physical or virtual computer where your agents run. One machine can host several workspaces. **Worker** The Firetower program installed on a machine. It starts agents and manages their working files. **Control plane** The server that coordinates work and manages accounts, credentials and access. **Client** The desktop or mobile app you use to start work and review results. Your devices **Desktop & mobile** Start, review and continue work ↕ Your infrastructure **Control plane** Accounts, access and coordination ↕ SSH Your worker machines **Workers → agent processes** Repositories, tools and execution ## What happens when something disconnects? | Event | What continues | What you lose temporarily | | --- | --- | --- | | You close the app | Agents already running on a worker | Live visibility until you reconnect | | The control plane restarts | Existing agent processes on other machines | Coordination, new starts and server-side actions | | A worker machine stops | Work on other machines | Every process on the stopped machine | Agent processes run under tmux and can outlive the connection to the control plane. A lost machine does not automatically move its work to another machine. ## Where work lives The control plane stores shared state and credentials. Each worker keeps the working files and executes tools as its SSH account. A separate VM is the isolation boundary when work must not share host access. **A new installation starts empty** Installing the control plane does not create a worker. [Add a machine](https://usefiretower.com/docs/machines) before starting your first task. --- # Sharing and permissions > Decide who can see, use and manage each resource. Source: https://usefiretower.com/docs/concepts-access Share a pool with a company team Company team **Engineering** Ada · Sam · Maya ↓ Editor access Firetower directory **Engineering resources** Worker machine Reviewer profile Review skill The grant gives this team access to resources in this directory. Exact actions depend on the resource type. ## People, resources and directories **Person / company team** A person has a Firetower account. A company team groups people so access can be granted once for the group. **Resource** Something you can share, such as a machine, workspace, profile, skill, artifact or agent account. **Directory** A container for shared resources in Firetower. It is an access boundary, not a folder on a worker’s disk. **Grant** Access given to a person or company team, directly on a resource or through its directory. ## Access levels | Level | Purpose | | --- | --- | | Viewer | Read the resource and its visible activity. | | Editor | Use or work with the resource. On workspaces, this includes terminal access. | | Directory Admin | Manage the directory, its contents and who can access it. | ## Ownership and sharing Moving a resource into a directory transfers ownership to that directory. Adding a direct Viewer or Editor grant keeps the existing owner. An organization Admin manages the installation and people. That role does not automatically expose everyone’s private resources. The person who started a session controls its messages and approvals. Colleagues with the appropriate access can start their own sessions in that workspace. ## Secrets and execution access The vault stores credentials and secrets. Sharing a saved resource and approving an agent action are separate decisions. Agent tools run with the worker’s SSH-account access; use a separate machine or VM when work needs isolation. Put it into practice [Share a resource](https://usefiretower.com/docs/sharing) [Check permissions](https://usefiretower.com/docs/permissions) [Manage people and teams](https://usefiretower.com/docs/people) --- # Tasks and results > A task describes the goal. Its results can be code, a document or a running preview. Source: https://usefiretower.com/docs/concepts-results One task can produce several kinds of result Task **Fix and explain the checkout timeout** ↓ Work happens in sessions and workspaces **Code change** A branch and pull request **Artifact** A saved visual explanation **Preview** The running application Choose the result the task needs. Not every task needs a repository or a preview. ## From request to code **Task** The goal given to an agent. It can start as your request or an issue from a connected tracker. **Repository** The git project an agent works on. A workspace checks out working files from it. **Branch** A line of changes in git. A separate git-backed workspace gives work its own branch. **Pull / merge request** The reviewable change submitted to your git host. Your team reviews and merges it through its normal process. ## Artifact versus preview | | Artifact | Preview | | --- | --- | --- | | What it is | A saved, versioned result | A running service in a workspace | | Example | A report or website prototype | The app the agent is building | | What it depends on | The stored artifact and its access policy | The running service and its worker | An artifact is not the running application. A preview is not an archive. Save or export the outputs you need before ending the workspace. Put it into practice [Start from an issue](https://usefiretower.com/docs/trackers) [Review and ship](https://usefiretower.com/docs/review) [Review an artifact](https://usefiretower.com/docs/artifacts) --- # Requirements > Prepare the server, network and worker machines separately. Source: https://usefiretower.com/docs/requirements ## Control-plane server | Setup | CPU | Memory | Storage | | --- | --- | --- | --- | | Minimum | 2 vCPU | 2 GB | 20 GB | | Recommended | 2 vCPU | 4 GB | 40 GB | - A Linux server you administer, with SSH access and root or sudo for installation. - Docker with the Compose plugin. Node.js 20 or later for the installer CLI. The bootstrap script can install these prerequisites. - A domain, access to its DNS records and a DNS provider API token for certificate issuance. - Network access to download deployment files, container images and certificate dependencies. ## Worker machines Firetower runs agents directly, without a container per agent. CPU and memory needs depend on your agents, tasks and how many run at once. A Mac mini with 16 GB of memory is a practical starting point. A VPS with 8 GB or less can also work for lighter tasks. Builds, tests and large repositories may need more. **Keep workers separate from the control plane** Do not run your agents on the same VPS as the control plane. Use a separate machine for agent work. Workers support macOS and Linux on arm64 and x86\_64. On Windows, run the worker inside WSL2. - SSH reachable from the control plane, using a dedicated account for agent work. - git, tmux, a POSIX shell, curl and tar. - The coding agents and project tools needed by your tasks. - Access to your git hosts, agent providers and project dependencies. **Separate requirements** Workers do not need Node.js or Docker just to run the Firetower worker. An agent or your project may need them. ## People and devices Provide a reachable HTTPS URL and a Firetower account for each person. Install the company VPN on every device that needs private access. Next: [install Firetower](https://usefiretower.com/docs/install-firetower). --- # Install Firetower > Deploy the control plane on a Linux server, then connect your first worker. Source: https://usefiretower.com/docs/install-firetower **Your installation, at a glance** Tailscale example Your domain · DNS records **firetower.your-domain.com** \*.firetower.your-domain.com for previews → Both point to **The server’s Tailscale IP** Use the address shown by the installer ↓ A public DNS name can point to a private address. **Your private Tailscale network** **Your devices** Desktop or mobile app Connected to Tailscale HTTPS ↔ Private connection **Firetower control plane** Your Linux server Connected to Tailscale ↓ **Next: add a worker machine** The control plane connects over SSH to run your agents. Your domain gives Firetower an address. Tailscale provides private access. HTTPS certificates are issued separately through DNS validation. ## Before you start - Prepare a Linux server with SSH access and root or sudo. - Choose a hostname, such as `firetower.your-domain.com` . - Have access to DNS records and a DNS provider API token. - Choose how the team reaches the server: a mesh VPN, private network or a managed public endpoint. See [requirements](https://usefiretower.com/docs/requirements) before you start. ## 1\. Prepare private access Connect the server and your computer to the same private network. For Tailscale, run: ``` curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` Open the sign-in URL printed in the terminal to join your company’s Tailscale network. Install Tailscale on your computer and join the same network. Confirm your computer can reach the server before continuing. See the [Tailscale installation guide](https://tailscale.com/docs/install/linux) for details. ## 2\. Run the installer ``` curl -fsSL https://usefiretower.com/install.sh | sh ``` The bootstrap checks prerequisites, installs Docker and Node.js when needed, installs the Firetower CLI, then opens the installation wizard. ## 3\. Complete the wizard 1. **Choose the network.** Confirm the detected mesh VPN address, or use Advanced to supply your own reachable address. 2. **Enter the domain and certificate settings.** Select your DNS provider and enter its API token in the prompt. 3. **Create both DNS records shown by the wizard.** The hostname serves Firetower; the wildcard serves previews. 4. **Choose the deployment directory and administrator name.** Record the directory for future maintenance. 5. **Review the plan and confirm.** Wait for the deployment to start. The initial proxy build can take several minutes. | Example record | Type | Value | | --- | --- | --- | | firetower.your-domain.com | A | The address people use to reach this server | | \*.firetower.your-domain.com | A | The same address | Use the exact values printed by your installer. Behind NAT, the address clients use may differ from the local address the proxy listens on. ## 4\. Sign in 1. **Sign in with the administrator credentials printed by the installer.** Open the Firetower URL to sign in. 2. **Back up the root key and database.** Keep the root key separately from the database backup, outside this server. See [Back up Firetower](https://usefiretower.com/docs/backups) . **Server ready does not mean agents ready** A fresh installation has no worker machines. Download the desktop app, connect it to this URL, then [add your first machine](https://usefiretower.com/docs/machines) . ## If DNS or certificates take longer DNS changes can take time to propagate. Obtaining the HTTPS certificate can also take several minutes while the certificate authority validates your domain. **Let the process continue** Do not stop or restart the installation while it is waiting for DNS or certificates. Certificate retries happen automatically. Repeated failed certificate requests can trigger [Let’s Encrypt rate limits](https://letsencrypt.org/docs/rate-limits/) . Avoid restarting setup to force another attempt. If a retry time is shown, let that time pass. If the delay persists, [contact us](https://discord.gg/Y2HYVEhSc) with the message shown by the installer. We’ll help you finish the setup. Next: [add a worker machine](https://usefiretower.com/docs/machines) → [connect an agent account](https://usefiretower.com/docs/accounts) → [run a task](https://usefiretower.com/docs/first-run) . --- # Add a worker machine > Give Firetower a machine on which it can run agents. Source: https://usefiretower.com/docs/machines ## Before you start Use a separate worker machine running macOS, Linux or Linux inside WSL2. Enable SSH and make sure the control plane can reach it. Prepare an SSH account with the file and network access your agents need. Keep it separate from your control-plane server. Screenshots show the desktop app with sample data. ## 1\. Open Machines In the desktop app, select **Machines** in the sidebar. Select **Add a machine** to open the connection form. ![Open Machines and select Add a machine](https://usefiretower.com/product/setup-machine-page-light.webp) Open Machines and select Add a machine. Select to enlarge. ## 2\. Enter the machine details Enter the worker’s address, SSH account and a recognizable name in the connection form. ![Enter the worker’s address, SSH account and name](https://usefiretower.com/product/setup-machine-address-light.webp) Enter the worker’s address, SSH account and name. Select to enlarge. ## 3\. Authorize Firetower’s SSH key Copy the public key shown in the app. Add it to the worker account’s `~/.ssh/authorized_keys`, or register it through your cloud provider. The expandable instructions show the command to use. Return to the app and select **Add it**. Firetower checks the SSH connection. ![Expand the SSH key instructions before connecting](https://usefiretower.com/product/setup-machine-key-light.webp) Expand the SSH key instructions before connecting. Select to enlarge. ## 4\. Install the worker Once SSH connects, select **Install the worker**. Keep the app open while Firetower installs it and reconnects. ![SSH connected: install the worker from the app](https://usefiretower.com/product/setup-machine-install-light.webp) SSH connected: install the worker from the app. Select to enlarge. ## 5\. Install your agents Choose the agents this machine should run. Select **Install Claude Code**, **Install Codex** or another available agent. Wait for the checkmarks, then select **Done**. ![Choose agents and wait for installation to finish](https://usefiretower.com/product/setup-machine-agents-light.webp) Choose agents and wait for installation to finish. Select to enlarge. ## 6\. Check readiness in the app Expand the machine’s row. Look for **Ready**, green checks for SSH, the worker and required tools, and an installed agent under **Agents**. If a check fails, follow the remedy shown in the app, then select **check again**. System packages that require administrator access must be installed on the worker by its operator. ![Ready: the worker checks and installed agents are green](https://usefiretower.com/product/setup-machine-ready-light.webp) Ready: the worker checks and installed agents are green. Select to enlarge. Next: [connect an agent account](https://usefiretower.com/docs/accounts). --- # Connect an agent account > Use an agent subscription or supported API credential for your work. Source: https://usefiretower.com/docs/accounts ## Before you start [Add a worker](https://usefiretower.com/docs/machines) and install the agent you want to use. Have your subscription sign-in ready. Screenshots show the desktop app with sample data. ## 1\. Choose your agent Open **Customize → Agents**. Expand the agent, then select **Connect an account**. If an account is already connected, select **Connect another account**. ![Agents page: expand an agent to find its account connections](https://usefiretower.com/product/setup-account-page-light.webp) Agents page: expand an agent to find its account connections. Select to enlarge. ## 2\. Sign in to your subscription Give the connection a clear name, such as **Engineering · Primary**. Follow the sign-in method shown for your agent. ### Claude Code Run `claude setup-token` on your own computer. Sign in with the intended Claude account, paste the resulting token into Firetower, then select **Connect account**. ![Name the Claude Code account and paste its setup token](https://usefiretower.com/product/setup-account-token-light.webp) Name the Claude Code account and paste its setup token. Select to enlarge. Connecting Codex instead Name the account and select **Continue to sign in**. ![Start Codex’s browser sign-in](https://usefiretower.com/product/setup-account-codex-start-light.webp) Start Codex’s browser sign-in. Select to enlarge. Open the displayed sign-in address. Enter the code and approve access with the intended Codex account. Return to Firetower and wait for **Account connected**. ![Approve the Codex device code in your browser](https://usefiretower.com/product/setup-account-codex-code-light.webp) Approve the Codex device code in your browser. Select to enlarge. ## 3\. Choose the default At **Account connected**, check the identity. Leave **Use by default for new work** selected if this should be your usual account, then select **Done**. ![Confirm the account and choose whether to use it by default](https://usefiretower.com/product/setup-account-confirm-light.webp) Confirm the account and choose whether to use it by default. Select to enlarge. ## 4\. Check the saved connection The account now appears under the agent. Confirm it says **Connected**. New work can use this account; existing runs keep their current account. ![The saved account appears in the agent’s account list](https://usefiretower.com/product/setup-account-saved-light.webp) The saved account appears in the agent’s account list. Select to enlarge. Next: [configure fallback](https://usefiretower.com/docs/fallback) or [share an account](https://usefiretower.com/docs/shared-accounts). --- # Configure account fallback > Choose which accounts a run may use when its current allowance is exhausted. Source: https://usefiretower.com/docs/fallback ## Before you start [Connect at least two accounts](https://usefiretower.com/docs/accounts) you can use. Open the run whose fallback you want to configure. Screenshots show the desktop app with sample data. ## 1\. Open fallback settings Below the message box, select **on limit: ask me**. ![The full workspace, with fallback settings highlighted](https://usefiretower.com/product/setup-fallback-page-light.webp) The full workspace, with fallback settings highlighted. Desktop app · sample data. Select to enlarge. ## 2\. Choose accounts in order Enable **Switch automatically, in this order**. Select your first backup, then the next. The numbers show the order Firetower will try. A backup for the same agent resumes its conversation. Selecting a different agent starts a new conversation with the task and progress so far, using the same workspace files. ![Select backup accounts in the order they should be tried](https://usefiretower.com/product/setup-fallback-order-light.webp) Select backup accounts in the order they should be tried. Select to enlarge. ## 3\. Save the fallback list Select **Save**. The control changes to **on limit: switch**. Select it again whenever you want to review or change the list. ![On limit: switch confirms automatic fallback is enabled](https://usefiretower.com/product/setup-fallback-saved-light.webp) On limit: switch confirms automatic fallback is enabled. Select to enlarge. ## What happens at the limit When the agent reports that its usage allowance is exhausted, Firetower tries the selected accounts in order. Temporary throttling and sign-in errors do not trigger a switch. Each target is tried once per recovery chain. If a switch fails or no target remains, open the run to choose the next account. API-key accounts use their provider’s usage billing. --- # Connect a git host > Connect your own identity to GitHub, GitLab, Gitea or Forgejo. Source: https://usefiretower.com/docs/git ## Before you start Use your own git-host account. If your company’s host is missing, ask an administrator to [add it](https://usefiretower.com/docs/git-admin). The steps below show GitHub’s browser sign-in. Screenshots show the desktop app with sample data. ## 1\. Choose your git host Open **Repositories → Git hosts**. Find your host and select **Connect**. ![Repositories → Git hosts: choose Connect](https://usefiretower.com/product/setup-git-page-light.webp) Repositories → Git hosts: choose Connect. Desktop app · sample data. Select to enlarge. ## 2\. Approve the connection Firetower opens your browser and shows a code. Enter it on the sign-in page and approve access to the organizations you need. Return to Firetower when you finish. ![Use the displayed code to approve GitHub access](https://usefiretower.com/product/setup-git-code-light.webp) Use the displayed code to approve GitHub access. Select to enlarge. ## 3\. Confirm your identity Wait for the host to show **connected**. Select **Identity** to review the name and email used for commits. ![Connected host and commit identity](https://usefiretower.com/product/setup-git-connected-light.webp) Connected host and commit identity. Select to enlarge. ## 4\. Find your repository Open **Repositories → All repositories**. Find the repository you want to use. If it is missing, check your organization access on the git host. ![Find repositories available through your connection](https://usefiretower.com/product/setup-git-repos-light.webp) Find repositories available through your connection. Select to enlarge. ## Other sign-in methods GitLab can use browser sign-in when the instance supports it. Gitea and Forgejo use personal access tokens. When Firetower asks for a token, use its provider link and follow the permissions shown, then paste the token and select **Connect**. Next: [configure a repository](https://usefiretower.com/docs/repo-setup). --- # Configure company git hosts > Register the instances your organization uses. Source: https://usefiretower.com/docs/git-admin ## Before you start You need administrator access to Firetower and the URL of your company’s git instance. For browser sign-in, you also need permission to register an OAuth application on that instance. Screenshots show the desktop app with sample data. Open **Repositories → Git hosts** in the desktop app. The **Add a host** button starts the setup. ![Git hosts: start with Add a host](https://usefiretower.com/product/setup-git-admin-page-light.webp) Git hosts: start with Add a host. Desktop app · sample data. Select to enlarge. ## 1\. Choose the provider Open **Repositories → Git hosts → Add a host**. Choose your provider. For a private instance, choose its self-hosted option. ![Choose a hosted service or a company instance](https://usefiretower.com/product/setup-git-admin-provider-light.webp) Choose a hosted service or a company instance. Select to enlarge. ## 2\. Set the address and sign-in method Enter the instance URL. Firetower checks it and shows the supported sign-in method. Give it a name your team will recognize. For browser sign-in, register an OAuth application using the instructions shown. Paste its client ID or application ID. If you cannot register one, select the token option; each person will connect with their own token. ![Configure the company instance and its OAuth application](https://usefiretower.com/product/setup-git-admin-settings-light.webp) Configure the company instance and its OAuth application. Select to enlarge. ## 3\. Add the host Select **Add the host**. The instance appears under Git hosts. Firetower may immediately offer to connect your own account. Each team member can now select **Connect** and sign in with their own identity. Adding a host does not grant access to its repositories. ![The company host is available for people to connect](https://usefiretower.com/product/setup-git-admin-saved-light.webp) The company host is available for people to connect. Select to enlarge. Next: [connect your git-host account](https://usefiretower.com/docs/git). --- # Connect tasks and issues > Bring an issue into a workspace with its source context. Source: https://usefiretower.com/docs/trackers ## Before you start Issues from a [connected git host](https://usefiretower.com/docs/git) need no separate token. For Linear, create a personal API key from its API settings. The steps below show Linear. Screenshots show the desktop app with sample data. ## 1\. Connect the tracker Open **Tasks → Trackers**. Paste your Linear key into **API key**, then select **Connect**. The **get one** link opens Linear’s key settings. ![Tasks → Trackers: connect your issue tracker](https://usefiretower.com/product/setup-tracker-page-light.webp) Tasks → Trackers: connect your issue tracker. Desktop app · sample data. Select to enlarge. ## 2\. Check the connection Wait for **connected**. Firetower shows the teams available to that key. If it fails, check that the key is valid and has access to the intended Linear workspace. ![Linear is connected and its teams are available](https://usefiretower.com/product/setup-tracker-connected-light.webp) Linear is connected and its teams are available. Select to enlarge. ## 3\. Choose an issue Return to **Tasks**. Choose **Linear** from the tracker picker, then narrow the list by team or status. Select **Start** beside an issue. ![Select a Linear issue from the task list](https://usefiretower.com/product/setup-tracker-tasks-light.webp) Select a Linear issue from the task list. Select to enlarge. ## 4\. Review and start the work Firetower fills in the issue context. Choose the repository, worker machine and agent profile. Adjust the request if needed, then use the send button to start. ![Review the issue, repository, machine and agent before starting](https://usefiretower.com/product/setup-tracker-start-light.webp) Review the issue, repository, machine and agent before starting. Select to enlarge. Starting from an issue preserves its source link. Updates to the issue’s status depend on your tracker’s git integration and team workflow. --- # Configure a repository > Make a repository reproducible on a worker. Source: https://usefiretower.com/docs/repo-setup ## Before you start [Connect your git host](https://usefiretower.com/docs/git). Have a setup command for your project and any environment variables it needs. Screenshots show the desktop app with sample data. ## 1\. Open the repository Open **Repositories → All repositories**. Find the repository and select its row to expand the settings. ![Repositories: find the project you want to configure](https://usefiretower.com/product/setup-repository-page-light.webp) Repositories: find the project you want to configure. Desktop app · sample data. Select to enlarge. ## 2\. Save the setup command Enter the command under **Setup script**. It runs after checkout and before the agent starts. For example: `pnpm install --frozen-lockfile`. If the project needs an environment file, enter a relative path such as `.env`. Select **Save**. ![Save the setup script and environment-file path](https://usefiretower.com/product/setup-repository-script-light.webp) Save the setup script and environment-file path. Select to enlarge. ## 3\. Add environment variables Under **Environment**, enter a variable name and value, then select **Add**. Repeat for each variable the project needs. ![Add a named environment variable](https://usefiretower.com/product/setup-repository-env-light.webp) Add a named environment variable. Select to enlarge. ## 4\. Review the saved configuration The saved variable names appear under **Environment**; their values stay hidden. Keep the environment file out of git. Start a new workspace to use these settings. If setup fails, check the setup output, then correct the command or missing tools on the worker. ![Saved setup command, environment file and variable names](https://usefiretower.com/product/setup-repository-saved-light.webp) Saved setup command, environment file and variable names. Select to enlarge. --- # Workspaces and repositories > Choose where files live and how changes are isolated. Source: https://usefiretower.com/docs/workspaces Start from **Workspaces → New workspace**. You can begin with a repository, or leave it empty and add code later. ![The new-work composer with the repository picker open](https://usefiretower.com/product/guide-workspace-no-repo-light.webp) The new-work composer with the repository picker open. Desktop app · sample data. Select to enlarge. ## 1\. Choose whether to use a repository For coding work, select **Add a repository**, then choose one or more repositories. Select its branch if you need a different starting point. Check the machine before sending your task. ![A repository selected before starting work](https://usefiretower.com/product/guide-workspace-with-repo-light.webp) A repository selected before starting work. Desktop app · sample data. Select to enlarge. ## 2\. Start without a repository For research, reports or other file-based work, leave every repository unselected. The picker confirms **No repository: a bare workspace with no code in it.** Close the picker and send your request. You still get a working directory and the Files panel. Download individual files or folders when you need a local copy. Git diff and shipping become useful once you add a repository. ## 3\. Add a repository after work has started Open the repository control at the top of the workspace. It shows the current repository names, or **No repository**. Choose **Add a repository to this workspace**. ![Add repositories inside an existing workspace](https://usefiretower.com/product/guide-workspace-add-later-light.webp) Add repositories inside an existing workspace. Desktop app · sample data. Select to enlarge. Select the repositories and their starting branches, then click **Check in**. Firetower clones them beside the existing files and tells the agent where they are. Continue in the same conversation. ## Share the place, own the conversation People with workspace access can inspect shared work. Each agent conversation belongs to its initiator. A colleague can start their own agent in the workspace. **Save outputs before ending the workspace** Ending a workspace can remove its working files and conversations. Ship code or export files you need to keep. --- # Create an agent profile > Save the instructions and defaults for a repeatable role. Source: https://usefiretower.com/docs/profiles Open **Customize → Agent profiles**. A profile saves an agent’s role, instructions and execution settings. ![Customize → Agent profiles](https://usefiretower.com/product/guide-profiles-page-light.webp) Customize → Agent profiles. Desktop app · sample data. Select to enlarge. ## 1\. Ask an AI to create a profile Choose **New profile → Create with AI**. Describe the job, the agent you want to use, and whether it can delegate. Firetower opens a new task with a profile-creation prompt. ![New profile → Create with AI](https://usefiretower.com/product/guide-profile-create-ai-light.webp) New profile → Create with AI. Desktop app · sample data. Select to enlarge. ``` Create a Firetower agent profile named Release captain. Use Claude Code to coordinate a release and delegate review to Reviewer. Follow our release runbook. Ask before publishing or deploying. ``` Send the request. When the agent finishes, return to **Agent profiles** and open the saved profile. You can also choose **Write it myself** to fill in the form directly. ## 2\. Set its role and workspace ![Edit a profile: identity, placement and machine](https://usefiretower.com/product/guide-profile-settings-light.webp) Edit a profile: identity, placement and machine. Desktop app · sample data. Select to enlarge. | Setting | What it does | | --- | --- | | Name | The name you select at launch or use when delegating. | | Description | What the profile does and when another agent should choose it. | | Placement | **Same workspace** shares the lead’s files and branch. **Its own workspace** creates a separate work area. | | Machine | Where a delegated agent’s own workspace runs. Shown when you select **Its own workspace**. | ## 3\. Choose how it runs ![Agent, subscription, run controls and delegation](https://usefiretower.com/product/guide-profile-runtime-light.webp) Agent, subscription, run controls and delegation. Desktop app · sample data. Select to enlarge. | Setting | What it does | | --- | --- | | Agent | The coding agent that runs this profile, such as Claude Code or Codex. | | Subscription | The connected account the agent uses. | | Model | A specific model, or the engine’s default. | | Permissions | How the selected agent handles approval requests. | | Effort | The reasoning effort, when supported by the agent. | | Sandbox | The execution boundary, when this control is offered by the selected agent. | | Delegation | **Operator** works alone. **Manager** can delegate. | | Can delegate to | Choose all accessible profiles or a selected set. Only shown for a Manager. | Available run controls depend on the selected agent. A setting left on **Engine default** uses that agent’s default. ## 4\. Choose the skills it loads ![Profile skill sources and selected skills](https://usefiretower.com/product/guide-profile-skills-light.webp) Profile skill sources and selected skills. Desktop app · sample data. Select to enlarge. | Setting | What it does | | --- | --- | | Your always-on skills | Include the skills you normally load in every task. | | This repository’s defaults | Include your default skills for the repositories used by the task. | | Counted for | Preview the skill set for a repository; it does not assign that repository to the profile. | | Always include these | Add named skills to the enabled sources above. | These sources add together. Check the skill count and any budget or review warnings before saving. ## 5\. Review instructions and save ![Profile instructions, access and default settings](https://usefiretower.com/product/guide-profile-instructions-light.webp) Profile instructions, access and default settings. Desktop app · sample data. Select to enlarge. | Setting | What it does | | --- | --- | | Instructions | The working rules included in the agent’s prompt. For a Manager, explain when to use each delegate. | | Who can use it | Open the permissions dialog for an existing profile. | | Where it lives | For a new profile, choose your personal space or a shared directory. | | Default | Use this profile for new workspaces unless you select another. | Click **Save changes**. Running agents keep the profile they started with; the changes apply to future launches. Next: [build an agent team](https://usefiretower.com/docs/teams) or [share the profile](https://usefiretower.com/docs/sharing). --- # Build an agent team > Give a lead a clear objective and specialists it can delegate to. Source: https://usefiretower.com/docs/teams Start in **Customize → Agent profiles**. Agent teams are configured through the profiles that do and delegate the work. ![Agent profiles: specialists and managers](https://usefiretower.com/product/guide-profiles-page-light.webp) Agent profiles: specialists and managers. Desktop app · sample data. Select to enlarge. ## Create the specialists Create an Operator profile for each responsibility. A small team might have an Implementer, a Reviewer and a QA specialist. Give each a clear output and the skills it needs. ## Create the lead 1. **Create a Manager profile.** Enable delegation. 2. **Choose the profiles it can delegate to.** Keep the allowed set focused on the work. 3. **Write the coordination instructions.** Say what to delegate, what results to collect and when to ask you for a decision. 4. **Choose each specialist’s placement.** Shared files suit review and coordinated edits; separate workspaces suit independent changes. 5. **Launch a task with the Manager profile.** Follow delegated work and its returned results in the conversation. ``` Implement the requested change. Ask Reviewer to inspect the diff and QA to check the behavior. Resolve their findings and summarize the results. Ask before expanding the scope of the task. ``` ![Delegated work in the redesigned desktop app](https://usefiretower.com/product/team-light.webp) Delegated work in the redesigned desktop app · supplied redesign prototype, not a release screenshot ## Review the team’s output The lead receives specialist results, but you still review changes and permission requests. Separate branches may need integration before shipping. **Two meanings of “team”** An agent team is a group of profiles working together. A company team is a group of people used for access control. Manage company membership in the administration site. --- # Import and share skills > Give agents reusable instructions and supporting files. Source: https://usefiretower.com/docs/skills Open **Customize → Skills**. The library lists your skills, built-in skills and skills shared with you. ![The skill library](https://usefiretower.com/product/guide-skills-page-light.webp) The skill library. Desktop app · sample data. Select to enlarge. ## 1\. Create a skill with AI Choose **Add a skill → Create with AI**. Describe a repeatable task and when the agent should use the skill. ![Create a skill with AI or upload a folder](https://usefiretower.com/product/guide-skill-create-menu-light.webp) Create a skill with AI or upload a folder. Desktop app · sample data. Select to enlarge. ``` Create a Firetower skill named release-notes. Use it when preparing customer-facing release notes. Group merged PRs into features, fixes and improvements. Link each change to its PR. Ask before publishing. ``` Send the request, then return to the skill library to inspect the result. If it appears under **Waiting for you**, review its files and approve it before use. ## 2\. Import an existing skill Choose **Add a skill → Upload a folder**. Click **Choose a folder**, or drop the folder into the app. The folder must contain `SKILL.md` and any files it references. ![Choose or drop a skill folder](https://usefiretower.com/product/guide-skill-upload-light.webp) Choose or drop a skill folder. Desktop app · sample data. Select to enlarge. ## 3\. Review before importing Check the detected name, description and file list. Resolve any reported errors. When importing several skills, select only the ones you need. ![Review the release-notes skill before import](https://usefiretower.com/product/guide-skill-import-review-light.webp) Review the release-notes skill before import. Desktop app · sample data. Select to enlarge. Click **Import skill**. Nothing is imported until you confirm. ## 4\. Find the skill in your library Search for the skill by name. Open it to read its instructions and files, then select it in an agent profile or the workspace’s skills control. ![The imported release-notes skill in the library](https://usefiretower.com/product/guide-skill-imported-light.webp) The imported release-notes skill in the library. Desktop app · sample data. Select to enlarge. ## Update a skill Import the folder again. Firetower shows whether it is unchanged, a new version or a separate copy. You can also ask an agent to revise the skill. ## Share a skill Use the skill’s permissions control to grant access to a person or move it into a shared directory. Follow the illustrated [sharing guide](https://usefiretower.com/docs/sharing). ## Check what an agent loads Profile skills, always-on skills and repository defaults can combine. Review the final selection before starting work. --- # Manage a run > Follow progress, answer requests and keep work moving. Source: https://usefiretower.com/docs/runs Open a workspace to read the agent’s conversation. Use the **Overview** panel to follow the team working on the task. ![A lead conversation with delegated agents in the Team panel](https://usefiretower.com/product/guide-runs-team-light.webp) A lead conversation with delegated agents in the Team panel. Desktop app · sample data. Select to enlarge. ## 1\. Follow the lead’s conversation Read progress, tool activity and questions. Send a message to clarify the task or change direction. Review permission requests before approving them. ## 2\. Open a teammate or sub-workspace In **Overview → Team**, click the agent you want to follow. For example, select **Quota band thresholds** to open the delegated review. ![A delegated agent’s conversation and its link back to the lead](https://usefiretower.com/product/guide-runs-child-light.webp) A delegated agent’s conversation and its link back to the lead. Desktop app · sample data. Select to enlarge. You now see that agent’s messages and questions. Agents in the same workspace share its files; agents with their own sub-workspace have a separate working area. The Team panel keeps the lead and other teammates within reach. ## 3\. Return to the lead Click the lead’s name in the Team panel, or the **from** link above the child conversation. Review the lead’s summary once the delegated work returns. ## Continue from another device Connect to the same Firetower installation and open the workspace. Closing a client does not stop work unless that device is also the worker. Keep the worker awake. ## Change accounts Use the workspace account control to switch accounts. See [account fallback](https://usefiretower.com/docs/fallback) for the difference between continuing with the same agent and handing work to another agent. ## Finish the work Review outputs, ship changes or export files before ending the workspace. Stopping an agent and removing its workspace are different actions; check the confirmation before continuing. --- # Review and ship changes > Turn an agent’s work into a change your team can accept. Source: https://usefiretower.com/docs/review **Recommended: track the work in a draft PR** For GitHub projects, ask your lead agent to use the `gh` CLI to create a draft pull request and keep it updated as the team works. Have the agents record progress, checks and review findings there. Firetower also lets you inspect the diff and ship changes from the app. ``` Use gh to open a draft PR for this task. Keep it updated with changes, checks and findings from every agent. Leave it as a draft until I have reviewed it. ``` Open the workspace, then select **Diff** in the right panel to inspect changed files. ![Workspace conversation and Diff panel](https://usefiretower.com/product/guide-review-page-light.webp) Workspace conversation and Diff panel. Desktop app · sample data. Select to enlarge. ## Review the work 1. **Read the agent’s summary.** Compare the result with the original request. 2. **Inspect the changed files.** Check for unrelated edits, sensitive data and behavior changes. 3. **Verify the checks.** Review test results and rerun anything needed in the workspace. 4. **Request revisions.** Keep the feedback concrete and review the updated diff. ## Ship through your git host Use the workspace’s shipping flow to create or update a pull request or merge request. Your connected git identity needs permission to push and create the request. Complete code review and merge through your team’s normal process. ## If shipping fails - Check whether your git token expired or lost repository access. - Check write permissions and provider token scopes. - Resolve branch conflicts before retrying. - Confirm you are acting in your own agent conversation. Work without a repository? [Download the result](https://usefiretower.com/docs/workspaces) instead of using a git shipping flow. --- # Review artifacts > Open a visual result and leave feedback on the part that matters. Source: https://usefiretower.com/docs/artifacts Open **Artifacts** in the sidebar to find pages and other results your agents have published. ![The artifact library](https://usefiretower.com/product/guide-artifacts-page-light.webp) The artifact library. Desktop app · sample data. Select to enlarge. ## 1\. Open an artifact Select an artifact, such as **Checkout flow**. It opens inside Firetower. You can also open it from the agent’s conversation. Check the version next to the title before reviewing. ![Checkout flow open in the artifact viewer](https://usefiretower.com/product/guide-artifact-open-light.webp) Checkout flow open in the artifact viewer. Desktop app · sample data. Select to enlarge. ## 2\. Select an element and write a note Click **Annotate**, then click the part of the page you want changed. Write a specific request in the note box. ![An annotation attached to the checkout button](https://usefiretower.com/product/guide-artifact-annotate-light.webp) An annotation attached to the checkout button. Desktop app · sample data. Select to enlarge. Click **Keep this note** to add it to your draft feedback. Repeat for any other changes. ## 3\. Send the feedback to an agent ![Draft artifact feedback ready to send](https://usefiretower.com/product/guide-artifact-notes-light.webp) Draft artifact feedback ready to send. Desktop app · sample data. Select to enlarge. Open **Notes** to review your feedback. Choose the receiving agent if the viewer asks, then send the notes. When the agent publishes an update, open the new version and check the changes. ## Share the artifact Use the artifact’s sharing control to grant access. See [Share a resource](https://usefiretower.com/docs/sharing). Export a copy when you need to keep it outside Firetower. **Artifact or preview?** An artifact is a saved result. A [preview](https://usefiretower.com/docs/previews) is a running application in a workspace. --- # Run and share a preview > Open the service an agent is building and give feedback. Source: https://usefiretower.com/docs/previews Ask the agent to start the application and tell you its port. Open the workspace, then click the globe button, **Preview a port**. ![The workspace preview button and port picker](https://usefiretower.com/product/guide-previews-page-light.webp) The workspace preview button and port picker. Desktop app · sample data. Select to enlarge. ## 1\. Open the running application Enter the port, such as **3000**, and click **Open**. The preview appears in a tab beside the conversation. Firetower routes it through the control plane; the worker does not need a public port. ![The running application inside Firetower](https://usefiretower.com/product/guide-preview-open-light.webp) The running application inside Firetower. Desktop app · sample data. Select to enlarge. Use **Full width**, **Tablet** or **Phone** to check different layouts. ## 2\. Annotate the page Click **Annotate**, then click an element in the application. Describe what should change and click **Keep this note**. ![Writing a note on the preview’s checkout button](https://usefiretower.com/product/guide-preview-annotate-light.webp) Writing a note on the preview’s checkout button. Desktop app · sample data. Select to enlarge. ## 3\. Send the notes and check the result ![Preview notes ready to send to the agent](https://usefiretower.com/product/guide-preview-notes-light.webp) Preview notes ready to send to the agent. Desktop app · sample data. Select to enlarge. Review the notes in the right panel. Click **Send notes to the agent**; the button shows how many notes will be sent. After the agent makes the change, reload the preview and check it. ## Share access A preview uses a signed URL. Anyone opening it still needs a network route to your Firetower installation. The application’s own sign-in may also apply. ## If the preview stops Check that the service is running on the selected port and the worker is reachable. Ending the workspace stops its running preview. A [saved artifact](https://usefiretower.com/docs/artifacts) is a separate output. --- # People and company teams > Give each person an account and group access by responsibility. Source: https://usefiretower.com/docs/people In the desktop app, open **Settings → People**. Select **Manage on the web** to create accounts or change roles in the administration site. ![People and the link to administration](https://usefiretower.com/product/guide-people-page-light.webp) People and the link to administration. Desktop app · sample data. Select to enlarge. ## Add a person 1. **Open People in the administration site.** Create an account with a unique username. 2. **Choose Member or Admin.** Use Admin for people who manage the installation. 3. **Deliver the temporary password securely.** It is shown once. Give the person the installation URL too. 4. **Ask them to sign in and replace the password.** Then grant access to the resources they need. ## Create a company team Use Teams in the administration site to group people, such as Engineering or Platform. Add members, then grant the team access to a directory. Membership and resource access are separate settings. ## Reset a password Use the person’s action menu in People. A reset replaces their password and ends their sign-in sessions. Share the new temporary password securely; the person must replace it at the next sign-in. **An Admin is not the owner of everything** An organization administrator manages people and installation settings. That role does not automatically reveal another person’s private resources. Next: [share resources](https://usefiretower.com/docs/sharing). --- # Share resources > Give a company team access to machines, skills, profiles and work. Source: https://usefiretower.com/docs/sharing A resource’s permissions control shows who can use it. This example shares the **pr-screenshots** skill; subscriptions and agent profiles use the same permissions dialog. ![Open the skill’s permissions control, highlighted with a box and arrow](https://usefiretower.com/product/guide-sharing-entry-light.webp) Open the skill’s permissions control, highlighted with a box and arrow. Desktop app · sample data. Select to enlarge. ## 1\. Open the permissions dialog Go to **Customize → Skills**. Click the access label on the skill: **yours** for a personal skill, or its directory name for a shared one. You can also open the skill and click **Who can use it**. ![The permissions dialog shows ownership and individual access](https://usefiretower.com/product/guide-sharing-modal-light.webp) The permissions dialog shows ownership and individual access. Desktop app · sample data. Select to enlarge. ## 2\. Share with an individual Under **Individual access**, click **Add people or teams…**. Search for a colleague and select them. Here, we add Ana. ![Ana added to the skill with an individual permission](https://usefiretower.com/product/guide-sharing-person-light.webp) Ana added to the skill with an individual permission. Desktop app · sample data. Select to enlarge. Choose **Viewer** to let them use the resource, or **Editor** to let them change it. Click **Save**. You remain the owner; the resource stays in your personal space. ## 3\. Or move it into a shared directory To make it part of a team’s shared resources, choose **Move into a directory…**. Select the destination, such as **Platform**. ![Choose the resource’s shared directory](https://usefiretower.com/product/guide-sharing-directories-light.webp) Choose the resource’s shared directory. Desktop app · sample data. Select to enlarge. Review the directory and who can access it. Click the directory row to inspect its members. Then click **Move it** and confirm the ownership transfer. ![Review directory access before moving the skill](https://usefiretower.com/product/guide-sharing-directory-light.webp) Review directory access before moving the skill. Desktop app · sample data. Select to enlarge. ## What changes? | Setting | What it does | | --- | --- | | Individual access | Adds a person’s permission to this resource. The current owner stays the same. | | Move into a directory | Transfers ownership to the directory. Its access rules apply to the resource. | | A new directory… | Creates a shared place when the intended people are not already grouped in one. Add people or teams and choose their permissions before saving. | ## Share a subscription the same way Open **Customize → Agents**, expand the agent, and find the connected subscription. Open its permissions control. Add an individual or move the subscription into a directory, as above. See [permission levels](https://usefiretower.com/docs/permissions) and [shared subscriptions](https://usefiretower.com/docs/shared-accounts) for the access each role provides. --- # Permission levels > Understand what a person can read, use and administer. Source: https://usefiretower.com/docs/permissions ## Directory and resource access | Level | Purpose | | --- | --- | | Viewer | Read what the resource exposes to viewers | | Editor | Work with the resource; workspace access includes powerful tools such as the terminal | | Admin | Manage the directory and its access | Additional grants on a single resource are Viewer or Editor. Directory administration is a separate responsibility. The resource’s type determines its exact actions. ## Company roles are different Member and Admin are installation roles. They control organization administration. Viewer, Editor and directory Admin are resource permissions. Being an installation Admin does not make every private resource visible. ## Workspace access is not conversation ownership People can read shared workspace activity according to their access. The person who starts an agent owns that conversation and its actions, including messages, approvals and shipping. A colleague starts their own agent to work alongside it. ## Verify access After changing a team or directory grant, check with a member account. Test both the action you intend to allow and one you intend to restrict. --- # Share agent subscriptions > Let a team use a connected account through controlled access. Source: https://usefiretower.com/docs/shared-accounts Open **Customize → Agents** and expand the agent whose subscription you want to share. ![The subscription sharing control, highlighted with a box and arrow](https://usefiretower.com/product/guide-shared-account-entry-light.webp) The subscription sharing control, highlighted with a box and arrow. Desktop app · sample data. Select to enlarge. ## Share the connection 1. **Connect and test the account yourself.** Give it an identifiable name. 2. **Click the subscription’s access label, highlighted above.** It shows **yours** for a personal subscription, or its directory name when shared. In the dialog, add a person or choose **Move into a directory…**. 3. **Grant the company team access.** Check that a member can select the account when starting work. 4. **Agree how it may be used.** Include whether it can appear in fallback lists and how usage is monitored. ![The subscription permissions dialog](https://usefiretower.com/product/guide-shared-account-permissions-light.webp) The subscription permissions dialog. Desktop app · sample data. Select to enlarge. Follow [Share a resource](https://usefiretower.com/docs/sharing) for the steps to grant individual or directory access. ## Understand the allowance All users of the connection consume the same provider allowance. Firetower sharing does not create extra seats or quota. Follow the provider agreement that applies to your subscription. ## Maintain the account The original connector controls credential actions such as reconnecting and disabling the account. Plan continuity before that person leaves the organization. **Sharing does not configure fallback** A person still selects fallback targets for a run. Access to a shared account does not automatically add it to every recovery chain. --- # Data, secrets and retention > Explain where company data goes and what deletion means. Source: https://usefiretower.com/docs/data ## Where information lives - **Control plane:** shared state, conversation records and encrypted credentials. - **Worker machines:** repository mirrors, workspace files, local event logs and running agents. - **Agent providers:** requests sent by the coding agent under the account you selected. - **Git hosts:** repository operations and changes you push. Self-hosting controls where Firetower runs. It does not make a cloud model local. Review each agent provider’s data policy and the tools available to that agent. ## Protect credentials Keep the root key separate from database backups. Limit access to the control-plane host and to worker SSH accounts. A worker executes with its account’s filesystem and network permissions. Use [resource sharing](https://usefiretower.com/docs/sharing) to control who can use an account. Rotate or revoke credentials at their provider when access must end. ## Review telemetry Open Settings in the administration site to review Telemetry. The panel shows its current state and the payload preview. An administrator can turn it on or off for the organization. ## Export before cleanup Save needed files and ship changes before ending a workspace. Workspace teardown can remove its working directory and conversation records. Do not rely on workspace history as a long-term archive. See [Back up Firetower](https://usefiretower.com/docs/backups) to protect installation data. --- # Update Firetower > Review the impact, take a backup and update compatible components. Source: https://usefiretower.com/docs/updates Open **Updates** from the account menu. Start by checking for updates, then update the control plane, workers and app in that order. ![Check for updates using the Check again button](https://usefiretower.com/product/guide-updates-check-light.webp) Check for updates using the Check again button. Desktop app · sample data. Select to enlarge. ## Check for updates Click **Check again** to refresh the available versions. The screenshot highlights this button. Version numbers are examples; yours will depend on the current release. Before proceeding, read the release notes and [create a backup](https://usefiretower.com/docs/backups). Keep the matching root key and deployment configuration. ## 1\. Update the control plane In **This Firetower**, click **Upgrade to…**. This opens the plan for the control plane. ![Choose the control-plane upgrade](https://usefiretower.com/product/guide-updates-control-light.webp) Choose the control-plane upgrade. Desktop app · sample data. Select to enlarge. Review the proposed file changes and any required environment variables. Keep your edited configuration unless you intend to replace it. Then click **Start the upgrade**. ![Review the control-plane plan and start the upgrade](https://usefiretower.com/product/guide-updates-control-plan-light.webp) Review the control-plane plan and start the upgrade. Desktop app · sample data. Select to enlarge. Follow the run until it succeeds and the control plane is reachable again. Resolve a failed step before updating workers. ## 2\. Update the workers Let running tasks finish, or stop them deliberately after saving their outputs. A worker update restarts its execution environment. Do not interrupt work you need to keep. Select the machines to update, then click **Plan the update for…**. Workers are updated to the control-plane version. ![Select the workers and plan their update](https://usefiretower.com/product/guide-updates-workers-light.webp) Select the workers and plan their update. Desktop app · sample data. Select to enlarge. Keep **Wait until nothing is running** selected. Click **Start the upgrade**; Firetower waits for the selected workers to become idle. If you choose not to wait, affected sessions will end. ![Wait for running tasks before starting the worker upgrade](https://usefiretower.com/product/guide-updates-workers-plan-light.webp) Wait for running tasks before starting the worker upgrade. Desktop app · sample data. Select to enlarge. Check that every selected worker reconnects after the update. ## 3\. Update the app In the desktop app, find **This app**. Click **Update to… and relaunch**. Save any unsent message first; the desktop window will restart. ![Update the desktop app and relaunch](https://usefiretower.com/product/guide-updates-app-light.webp) Update the desktop app and relaunch. Desktop app · sample data. Select to enlarge. This app’s update control appears in the desktop client. For mobile, install the available update through your app distribution channel. --- # Back up Firetower > Protect the database, credentials and files needed for recovery. Source: https://usefiretower.com/docs/backups Open **Updates** from the account menu as an administrator. You can create a database backup directly from the app. ![Updates → Back up now, highlighted with a box and arrow](https://usefiretower.com/product/guide-backup-start-light.webp) Updates → Back up now, highlighted with a box and arrow. Desktop app · sample data. Select to enlarge. ## 1\. Create a backup Click **Back up now** below the Machines list. Keep the page open while it shows **Backing up…**. ## 2\. Check completion The button changes to **Backed up** when the request succeeds. The dump is saved on the server; it is not downloaded to your device. ![The app confirms that the backup completed](https://usefiretower.com/product/guide-backup-done-light.webp) The app confirms that the backup completed. Desktop app · sample data. Select to enlarge. ## 3\. Keep the rest of the recovery set The in-app backup contains the database’s public schema. Keep these items as well: | Setting | What it does | | --- | --- | | Matching root key | Required to decrypt saved credentials. Store a protected copy separately from the database dump. | | Deployment configuration | Your domains, environment settings and service configuration. | | Worker files | Uncommitted changes and non-git outputs you need to keep. These are not in the server database. | The server keeps the ten most recent dumps. Keep off-server copies under your team’s retention policy. ## Test recovery Test the complete recovery set in an isolated environment. Follow [Restore and recover](https://usefiretower.com/docs/restore). --- # Troubleshoot an installation > Locate the failing layer before changing configuration. Source: https://usefiretower.com/docs/troubleshoot ## Collect the basics Run these on the control-plane server. Use the directory chosen at installation. ``` firetower --dir /opt/firetower status firetower --dir /opt/firetower doctor firetower --dir /opt/firetower logs ``` ## Follow the symptom | Problem | Start with | | --- | --- | | App cannot reach the server | Open the URL in a browser; check VPN, DNS and TLS | | Server is reachable but sign-in fails | Account status, temporary-password flow and trusted-proxy configuration | | No machine can start work | [Worker setup](https://usefiretower.com/docs/machines) and [readiness](https://usefiretower.com/docs/machines#section-5) | | Only one provider fails | [Agent credentials](https://usefiretower.com/docs/accounts) or [git-host authorization](https://usefiretower.com/docs/git) | | A run waits unexpectedly | Permission requests, quota failure and worker connectivity | | An upgrade stopped | [The update step and its recorded error](https://usefiretower.com/docs/updates) | ## Prepare a useful report - Include the time, affected component and versions. - Describe what you expected and the exact error. - Include relevant diagnostic output after checking it for secrets. - Say whether the failure affects everyone, one machine or one account. Do not include `.env` , root keys, provider tokens or private repository content in a public report. --- # Restore and recover > Recover a deployment with its matching database and root key. Source: https://usefiretower.com/docs/restore ## Keep the recovery set together Record the Firetower and CLI versions used for each backup. You need the database dump, its matching root key, deployment configuration, and any worker files you need to recover. A database dump alone cannot decrypt credentials. The installer CLI has no restore command. ## Prepare an isolated environment - Keep the original backup unchanged. Work from a copy. - Use an isolated server that cannot contact production workers. - Preserve the source versions and configuration before planning upgrades. - Include separately stored files and persistent volumes in the recovery plan. ## Get help with the restore [Contact us](https://discord.gg/Y2HYVEhSc) with your versions, backup method and the error you are recovering from. Do not send root keys, passwords or database dumps through chat. The exact import and volume-recovery steps depend on your deployment. Rehearse them in the isolated environment before replacing production. ## Validate before reconnecting - Sign in and confirm the expected people and resources. - Confirm stored credentials can be decrypted. - Reconnect one worker deliberately and run a small task. - Check repository access and recovered files before reconnecting the rest of the fleet. Start with [Back up Firetower](https://usefiretower.com/docs/backups) to prepare your recovery set.