Cloud Bots

What a cloud bot is#

The HQ desktop app calls every AI teammate a bot. A cloud bot is a company bot that HQ hosts in your company's cloud. The HQ Console and some older docs call these "Fleet Agents". It's the same thing.

A cloud bot is a persistent AI teammate managed by HQ. It has its own identity and company membership, its own vault-backed workspace, a managed cloud runtime, and optional Slack, email, and Telegram channels. Because it runs in the cloud, it's always on, and it stays available when your laptop is closed. It uses company credits.

If you'd rather have a bot that runs on your own computer, see Local Bots. For where bots live in the app, see A Tour of the HQ Desktop App.

A cloud bot is different from a worker. A worker is a reusable task definition that runs inside your own HQ session; it does its job and the session moves on. A cloud bot stays available between conversations, can be addressed directly ("@scout, can you look at this?"), and acts under its own company identity rather than yours.

Everything a cloud bot touches stays inside one company's boundary: its files, secrets, and channels all belong to the company that hosts it. See The HQ Ecosystem for where cloud bots sit in the product family.

Talking to a cloud bot in Slack#

Cloud bots show up in Slack as apps, not people. Day to day:

• Start a conversation by @-mentioning the bot in a channel. It replies in a thread.
• You don't need to keep mentioning it. Once the bot is part of a thread, it follows replies in that thread without another mention. It ignores unrelated top-level channel chatter.
• To make it stop following a thread, send @botname stop (using the bot's actual name). A follow that goes inactive expires on its own after 48 hours.
• Direct messages work too: send your request to the bot's app in a DM. You must be an active member of the bot's company (and pass any caller restriction the company has configured), otherwise the bot won't respond.

Adding the bot to a channel: because it's an app, Slack's /invite command is designed for people and may not offer it. Instead, @-mention the bot in the target channel; when Slack says the app is not in the channel, confirm Add. You can also open the channel's Settings, choose Integrations, and use Add apps.

Pacing: the bot processes one conversation at a time. A long-running task (a scheduled job, a big question) holds the queue, and later messages are answered when it finishes. If the bot is mid-task, don't re-send the same request. Duplicates don't speed anything up, they just queue more work.

One thing to keep straight: there is a second, simpler kind of HQ bot in Slack, minted with /hq-new-bot. If that's what your workspace has, see HQ Bots in Slack. Cloud bots are the richer of the two.

Emailing a cloud bot#

When email is enabled for your deployment, every cloud bot gets its own address:

{handle}@{company-slug}.hq-agents.com

• Reply threading works like normal email: the bot's responses are plain text and preserve the thread.
• A company owner or admin can set up a verified company subdomain in Console settings, so the bot's address uses your own domain. HQ shows the DNS records you need but never changes your DNS for you. If the company domain is later removed, the bot falls back to the generic address.
• Any active member of the company can email the bot. The company can also maintain an allowed-sender list (managed via API) to admit specific outside senders or to narrow access further. When such a list exists, it fails closed: if HQ can't determine the sender's email or the sender isn't on the list, the message is rejected.

For Champions: creating and running cloud bots#

Everything from here down is for the person who creates, secures, and operates cloud bots. Everyday users can stop reading.

Creating a cloud bot

The easiest way is the HQ desktop app:

1. Start a New bot. Press Cmd+Option+N (Ctrl+Alt+N on Windows), click the + button in your Home list and choose New bot, or go to Settings → Bots and click New bot. To open Settings, click your picture at the bottom of the left rail and choose Settings.
2. Name. Type the bot's name. This is how it appears in HQ.
3. Where should <name> live? Pick Cloud (always on, uses company credits). If the bot already runs somewhere else, click Connect it instead for the steps to link it with hq agent enroll.
4. Choose a brain. Pick the model your bot uses: Claude, Codex, or Grok, depending on what your company offers.
5. Choose a company. If you're in more than one company that can host a cloud bot, pick the one it works for and is billed to.
6. Machine size. The default fits most bots. The company's monthly price shows before you create it (see Pricing below).
7. Click Create followed by the bot's name. Each earlier screen also has Finish with defaults, which creates the bot with the defaults for the steps you skipped.

HQ then shows a Waking up screen. If the bot's brain needs a sign-in, it asks you to sign in to that provider and paste the code it gives you. Once setup finishes, the cloud bot gets its own conversation in the app. If your company's plan doesn't include cloud bots, HQ says so and offers the upgrade options or a local bot instead.

You can also move an existing bot to the cloud. A company local bot has Promote to cloud on its profile. Promoting it keeps its identity, conversation, skills, and memory.

Other ways to create one:

• HQ Console: open your company in HQ Console (hq.computer), choose Agents, and run the wizard.
• Terminal: hq agents provision <name> --company <slug> --size basic|power|dev --yes (the --yes confirms the monthly charge for the size you pick).

Before you start, you need:

• permission to manage bots for the company: owners and admins can create cloud bots when the company grants them the Create agents permission. Only a company owner can create a cloud bot with the admin membership role. Cloud bots can't create other bots.
• a provider account or API key HQ supports;
• permission to install apps in Slack, if you plan to connect Slack;
• approval for the recurring price shown before activation (see Pricing below).

Identity first, and the handle is permanent. The handle becomes part of the bot's company identity, email address, and vault paths, so treat it as permanent. Display name, avatar, title, and description can all change later; the handle can't.

Provider and authentication:

Provider choices can vary by account and release; use what the app or Console shows. API keys are write-only: you submit the key during setup, HQ stores it in the company vault, and it's never displayed again.

Setup is resumable, so never create a duplicate. Setup provisions identity, membership, vault workspace, runtime, authentication, company context, and any selected channels as staged steps. You can leave and come back while it runs. If a stage stalls in the Console, open the bot's row and use Retry (for a transient failure) or Reauthenticate (for an expired or incomplete provider login). Don't create a replacement bot while the original setup can still resume.

Attaching Slack happens from the bot's settings in the Console: choose Attach Slack and approve the authorization screen (your workspace may require an admin to approve the app). If the Console shows a pending installation, use Finish install. Don't detach and reattach Slack as a routine repair: detaching can delete the current app and its credentials, and reattaching can mint a different app identity.

Verify before handing it real work:

1. The roster shows the bot as live.
2. Settings show healthy runtime and heartbeat signals.
3. A small task sent through a connected channel comes back.
4. The response arrives under the bot's own identity.

What can the cloud bot see?

A cloud bot is a full company member with machine-managed credentials, but new membership grants nothing by itself: no files, no secrets, no groups, no connectors. You add access deliberately, and the guidance is the same as for a person: the narrowest role, groups, file access, secret access, connectors, and channel audience that lets it do its job.

• Role: a cloud bot can be a member (the default, right for most bots) or an admin (only when it must manage admin-restricted resources; review that choice carefully). A cloud bot can never become the company owner.
• Credentials: provider keys and channel tokens are stored in the vault, and the bot's runtime configuration carries references to them, never the raw values. The settings API never returns a raw key.
• The caller is part of the permission model: anyone who can message the bot can trigger whatever the bot is permitted to do. That's why caller controls exist: Slack and email support API-managed allowed-caller lists, and Telegram can require a company group. A configured restriction fails closed when HQ can't resolve the sender.
• Never paste keys into a bot conversation. Credentials go through HQ's credential flows only; see the Secrets Guide.

Groups make access easier to reason about: add the bot to groups that grant what it needs, use a dedicated group for a narrowly scoped bot, and prune stale memberships when its job changes. Note that group membership doesn't replace a direct vault ACL; where a resource uses explicit grants, both layers must allow access. Test with a harmless probe before assigning production work.

One more access surface worth knowing: owners and admins can connect a running cloud bot to approved HQ tools under Integrations > For Agents (the HQ MCP connector), which avoids copying a long-lived company secret onto its runtime. Disconnect it from the same screen when no longer needed.

Owners and delegation

The person who creates a cloud bot becomes its initial owner, accountable for its purpose, access, operating cost, and lifecycle. Companies with delegated ownership enabled can add more owners from the bot's settings; only active owners can see the Owners panel, invite another owner, or revoke one.

When delegated ownership is on, the bot can act with a strict subset of one active owner's grants for a supported request. HQ never merges grants from several owners. Two boundaries matter:

• Delegation is Slack-only today. It rides on verified Slack work items. Email, Telegram, scheduled jobs, and other non-Slack work always run as the bot's own identity. Don't assume adding an owner gives every channel that owner's access.
• Unverified senders get the bot's own identity. The reliable way for the bot to recognize an owner is a personal Slack connection for the workspace where they talk to it (HQ prompts for this after creation and it also lives under Personal Integrations; the connection is workspace-specific). HQ can fall back to a narrow verified-email match when the Slack email and the active membership email agree. If neither path verifies the sender, the bot acts as itself rather than guessing.

Changing an owner doesn't automatically change the bot's role, groups, vault grants, or channel access; review those separately during any handoff. A company-level control can disable owner delegation entirely, in which case the bot always acts as itself.

Telegram

Connect Telegram from the bot's settings: choose the managed bot flow or provide your own Telegram bot token, complete the caller enrollment step the Console shows, and optionally pick a company group whose members may call the bot. With no caller group set, any active company member can call it; with a group set, the sender must resolve to an active member of that group.

Telegram is available for Codex and Grok cloud bots. It's not available for Claude cloud bots in the current release.

Tuning

Open the gear menu on the bot's row in the Console. Saving updates the running bot when possible; a change that can't be applied live is saved for the next start.

• Provider, model, and authentication must agree. The Console filters or rejects incompatible combinations, and some models require API-key authentication even when the provider also supports subscription sign-in. Provider migration isn't available in general Agent Settings.
• Reasoning effort (for supported models): Minimal, Low, Medium, High, or Extra high. Grok doesn't use this setting, and not every model supports every level.
• Speed: a Default or Priority service tier, available for supported Codex configurations. Priority can increase provider cost.
• Profile: display name, avatar, title, and description are all editable. Make the profile operational: what the bot owns, what to send it, and what a teammate should do when a request is out of scope. People in Slack should be able to decide whether to mention it without opening the Console.

Scheduled work

Cloud bots can schedule one-time or recurring work from their own runtime, with relative or absolute times, cron or rate expressions, and IANA time zones. The limits:

• recurring work can't run more often than every five minutes;
• each bot can hold up to 25 active jobs;
• the same job never overlaps itself.

There's no general Console screen for scheduled jobs in the current release; manage them through the bot's own jobs tool (in practice, by asking the bot). Remember that scheduled jobs run as the bot's own identity, not as any channel requester.

Lifecycle

The Agents roster in the Console is the operations home. It uses states like Setting up, Live, Needs re-auth, Needs attention, Degraded, Down, Stopped, and Removed, and each bot's settings show runtime health, heartbeat, authentication, and channel diagnostics. Owners and admins can also inspect a bot's session and transcript pages, which helps distinguish a channel delivery problem from work that reached the runtime and failed later.

Stop is safe: everything is preserved and the bot can start again. Remove is destructive and requires confirmation. Before removing a cloud bot, detach its external channels, transfer any durable work, and confirm no scheduled job or channel workflow still depends on it.

Pricing

Every cloud bot runs on its own dedicated box, and the box size sets its monthly list price:

You pick a size when you create the bot, and the company-specific monthly price is shown before creation. It's billed to the company that creates the bot, and charging starts when the bot is created. Plan inclusions, contract pricing, credits, or sponsorship can change the amount actually invoiced.

You can change the size later from the bot's settings. A mid-cycle change is prorated on your next invoice, and the confirmation step shows the exact monthly change before anything is applied. Changing size needs permission: company owners always have it, and admins have it when the owner grants it. Everyone else can request a change, which goes to the owner to approve or decline.

The creating company stays the bot's host company and keeps paying, even when other companies add the bot as a member.

One cloud bot, multiple companies

A cloud bot has one immutable host company. Another company doesn't create a second bot; it invites the existing identity (the agt_* id or the bot's machine email) as a member or admin:

hq members --company <company> invite <agent-id-or-email> --role member

The new membership is active immediately, but as always it grants nothing by itself: the inviting company grants its own groups, files, secrets, and connectors separately.

Scripting

For scripts and terminal workflows there is a smaller hq agents CLI (provision, list, status, set, config, start, stop, retry, rename, rm, plus message and thread for talking to a cloud bot from the terminal, with --json on supported commands). The desktop app and Console are the recommended surfaces, especially for anything destructive; the full command reference is at docs.hq.computer.

Common questions#

If you get stuck#

Quick symptom map:

• Setup stalled: open the bot's row in the Console, find the stage that needs attention, and use Retry or Reauthenticate. Never create a duplicate bot.
• Live but silent: check runtime heartbeat, provider authentication, and that the model is compatible with the provider and auth method.
• Slack messages not arriving: open Slack diagnostics in the bot's settings (Waiting for event, Outbound only, or Missing configuration each mean different things), use Finish install if an installation is pending, and confirm the app is still in the channel. Don't detach and reattach unless you intend to replace the Slack app.
• One person can't call the bot: check the Telegram caller group in settings, or have an operator inspect the API-managed allowlist for Slack or email. A configured restriction rejects callers HQ can't map to an allowed active member.

If you escalate, include the company and bot UID, the roster state, the failing stage or channel, the runtime and heartbeat status, the last Slack event timestamp if Slack is affected, and the exact time of a safe test request. Never include provider keys, bot tokens, vault values, or authentication codes. For general help paths, see The "I'm Stuck" Guide and Getting More Help.