Access and security

Fleet Agents join a host company as members during provisioning. Provisioning gives the agent read and write access to that company’s vault; see Default vault access for the grants and how to narrow them. Later company memberships do not automatically grant the same vault access. Give each agent the narrowest role, group membership, file access, secret access, connectors, and channel audience that lets it do its job.

Membership role

Role	Use it when
Member	The agent performs work within access granted by company policies and groups. This is the default for most agents.
Admin	The agent must manage company-level resources that are restricted to administrators. Review this choice carefully.

An agent cannot become the company owner. Ownership of the agent and the agent’s company membership role are separate concepts.

Agent owners

The person who creates an agent becomes its initial owner. Owners are accountable for its purpose, access, operating cost, and lifecycle. Companies with delegated ownership enabled can assign additional owners from the agent settings.

Changing an owner does not automatically change the agent’s role, groups, vault grants, or channel access. Review those separately during a handoff.

Groups

Groups make agent access easier to reason about:

• add the agent to groups that grant the resources it needs;
• use a dedicated group for privileged or narrowly scoped agents;
• select a group as the Telegram caller gate when only part of the company should call the agent; and
• remove stale group membership when the agent’s responsibility changes.

Group membership does not replace a direct vault ACL. Both layers must allow access when a resource uses explicit grants.

Vault and credentials

HQ creates a vault-backed workspace for each Fleet Agent. Provisioning grants the agent access to its host company’s vault as described below. Access does not cross into other companies: a later membership in another company does not create vault grants there.

• Provider credentials and channel tokens are stored in the vault.
• Runtime configuration carries credential references, not raw secret values.
• Review and narrow the default vault grants; manage secret access and other credentials separately.
• Company and personal credentials must not be copied between tenants.

Use the standard HQ file and secret grant flows to change access. Test with a harmless probe before assigning production work.

Default vault access

When provisioning creates a new Member Fleet Agent, HQ grants its agent identity read and write access to the whole host-company vault and to its own agents/<agent-uid>/ workspace. The workspace grant covers agents/<agent-uid>/*; the whole-vault grant uses the * prefix. Both grants are scoped to the host company’s vault and do not carry over to other companies.

To inspect the grants, find the agent UID in the UID column of hq agents list --company <company-slug>, then check the whole-vault and workspace ACLs:

hq files acl '*' --company <company-slug>
hq files acl 'agents/<agent-uid>/*' --company <company-slug>

The ACL output lists grant entries for each principal. Any effective-permission field describes the signed-in user who ran the command, not the agent.

To narrow access, remove the agent’s whole-vault grant, then grant only the folders it needs with read or write permission:

hq files unshare '*' --with <agent-uid> --company <company-slug>
hq files share 'knowledge/*' --with <agent-uid> --permission read --company <company-slug>

Use --permission write when the agent needs to change files in that folder. The agent’s own workspace grant remains in place when the whole-vault grant is removed. After narrowing access, ask the agent to list one known, non-sensitive folder you granted and one folder you did not grant. The granted folder should be listed; the other should be refused. Then check both ACLs and the workspace ACL again:

hq files acl 'knowledge/*' --company <company-slug>
hq files acl 'restricted/*' --company <company-slug>
hq files acl 'agents/<agent-uid>/*' --company <company-slug>

Substitute real folders for knowledge/* and restricted/*. Confirm that the agent UID appears only on folders you granted and on its own workspace.

A no-vault-access option at agent creation is planned, with no date announced. There is no commitment to change the default described here.

Multiple companies

An agent has one immutable host company that pays for it. Another company can invite the existing agt_* identity or machine email as a member or admin:

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

The new membership becomes active immediately. It does not add vault grants in the invited company; grant that company’s files, groups, secrets, and connectors separately. The host company remains responsible for billing.

Owner delegation

When delegated ownership is enabled, an agent can act with a strict subset of one active owner’s grants for a supported request. HQ does not merge grants from several owners.

Current requester-scoped delegation is carried by verified Slack work items. Email, Telegram, scheduled jobs, and other non-Slack work run as the agent’s own identity. Do not assume that adding an owner gives every channel the owner’s access.

Connect an owner’s Slack identity

The most reliable way for an agent to recognize an owner is a personal Slack connection for the workspace where they talk to it. HQ offers a non-blocking Connect Slack prompt after agent creation, after an ownership invitation is accepted, and in Agent Settings for an active owner. The same connection is available under Personal Integrations.

The connection is workspace-specific. If the saved connection points to another workspace or needs attention, reconnect it to the workspace used by the agent. HQ can fall back to a narrow verified-email match when the Slack email and active company membership email agree. If neither path verifies the sender, the agent acts as itself rather than guessing.

Only active owners can see the Owners panel, invite another owner, or revoke one. A company-level control can disable owner delegation; when disabled, the agent always acts as itself.

Caller restrictions

A channel user can trigger whatever the agent is allowed to do, so caller controls are part of the permission model:

• Slack and email can use API-managed allowed-caller lists. These lists are not exposed in general Agent Settings.
• Telegram can require the sender to belong to a selected active company group.
• A configured allowlist fails closed when HQ cannot resolve the sender.

Removing an agent

Removal is different from stopping:

• Stop preserves the agent and its configuration so it can be started again.
• Remove deprovisions the managed agent resources and ends its company membership.

Before removal, detach external channels, transfer any durable work, and confirm that no scheduled or channel workflow still depends on the agent. The Console requires confirmation because removal is destructive.