All articles
On this page
Teams & Cloud
Cloud Bots
Anyone who wants to create a cloud bot or talk to one. The For Champions part at the end covers access, cost, and upkeep.
What a cloud bot is#
HQ calls every AI teammate a bot. A cloud bot is a company bot that HQ hosts in your company's cloud. A local bot runs on your own computer; see Local Bots.
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.
Create a cloud bot#
You need to be a company owner, or an admin who's been given the Create agents permission. A cloud bot has a monthly price, and HQ shows it before you confirm.
There are two ways to create one.
1. Desktop app (easiest)
- Click New bot. You'll find it under the + button in your Home list, or in Settings → Bots. The shortcut is Cmd+Option+N (Ctrl+Alt+N on Windows).
- Pick Cloud.
- Type a name.
- Pick a brain: Claude, Codex, or Grok.
- Pick the company it works for. You'll only see this if you're in more than one.
- Pick a machine size. The default works for most bots.
- Click Create.
You can click Finish with defaults on any step to skip the rest.
Next you'll see a Waking up screen. If the brain asks you to sign in, sign in and paste the code it gives you. When setup's done, the bot shows up as a conversation in the app.
The desktop app uses subscription sign-in only. To use an API key, use the Console.
2. HQ Console
Go to hq.computer, open your company, click Bots, and follow the steps.
After you create it
- The handle can't change. It's part of the bot's email and file paths. The display name, picture, title, and description can change any time.
- Don't make a second bot if setup stalls. Setup picks up where it left off. In the Console, open the bot and click Retry, Resume setup, or Restart sign-in.
- Add Slack from the bot's settings in the Console: click Attach Slack and approve. A Slack admin may need to approve the app. If it says an install is pending, click Finish Slack install. Don't detach and reattach Slack to fix problems, since that can create a new Slack app.
- Test it before giving it real work: the bot shows as live, and a small request in Slack comes back from the bot.
Sign-in options by brain:
| Brain | Sign in with |
|---|---|
| Codex | ChatGPT subscription or an OpenAI API key |
| Grok | Grok subscription or an xAI API key |
| Claude | Claude subscription, if your account has it |
API keys are saved in the company vault and never shown again.
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: running cloud bots#
Everything from here down is for the person who runs and secures cloud bots.
What can the cloud bot see?
A cloud bot is a full company member with machine-managed credentials, and by default it can read and change all of the company's files, plus its own workspace folder. Secrets, groups, and connected apps are added deliberately. To narrow its file access, ask an owner to change it with /hq-files. For everything else, 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 Agents on the company's Integrations page (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): how hard the bot thinks before answering. The levels you can pick depend on the model.
- 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. Ask the bot, or use the terminal: hq agents jobs list <agentUid> shows a bot's jobs, and hq agents jobs pause, resume, and cancel manage them. Remember that scheduled jobs run as the bot's own identity, not as any channel requester.
Lifecycle
The Bots page 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.
| Action | Effect |
|---|---|
| Start | Starts a stopped runtime with its saved configuration |
| Stop | Stops the runtime while preserving identity, settings, and access |
| Restart sign-in | Repeats the provider sign-in without replacing the bot |
| Resume setup or Retry | Picks up a failed or interrupted setup step |
| Remove | Deprovisions the bot and ends its company membership |
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 price. Bigger boxes suit bots that serve many people or do development work. See HQ's pricing page for current prices.
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 memberThe new membership is active immediately and lets the bot use that company's files. Secrets and connected apps are granted separately.
Scripting
For scripts and terminal workflows there is a smaller hq agents CLI (provision, list, status, set, config, start, stop, retry, rename, rm, models, terminal, and jobs (including jobs update), 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#
Is a cloud bot the same as the HQ bot we made with /hq-new-bot?
No. That bot is a lighter, per-person Slack bot from the Slack Bot Factory; see HQ Bots in Slack. A cloud bot has its own company identity and membership, a managed cloud runtime that stays online on its own, and email and Telegram channels alongside Slack.
What's the difference between a cloud bot and a local bot?
A local bot runs on your own computer, so it's only available while your computer is on. A cloud bot runs in your company's cloud, stays on all the time, and uses company credits. See Local Bots.
Can the cloud bot read everything in our company?
By default it can read and change your company's files. It can't use secrets or connected apps until an owner or admin grants them, and it stays inside its own company.
Why is the cloud bot slow to answer?
The bot processes one conversation at a time, and a long-running task holds the queue until it finishes. Complex work or provider queues add time. Re-sending the same message doesn't help; it just adds queued work.
We removed an owner. Did the cloud bot lose access?
No. Ownership and the bot's own grants are separate. Changing owners never changes the bot's role, groups, vault grants, or channel access; review those yourself during a handoff.
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, Resume setup, or Restart sign-in. 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 and follow what it says, use Finish Slack 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.