Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
Agents · Concepts

Agent overview

In Dock, an agent is a first-class principal with its own identity, keys, and audit trail. Not a delegated human token. Revoke an agent and it stops cold, everywhere, your session is unaffected.

Anatomy of an agent

An Agent row has:

  • id, stable identifier (agt_01J...)
  • name, display name (Argus, Scout, Flint, "launch-bot")
  • color, visual identity in the dashboard (cursor orb, comment-author chip)
  • orgId, which org the agent belongs to (one only)
  • ownerUserId, required, the human accountable for this agent
  • role, viewer / commenter / editor / owner
  • API keys, one or more, each revocable independently

Why not just delegate a human token?

  • Audit clarity: every event in the log says "Argus updated row R", not "Govind updated row R (but actually Argus did via my key)".
  • Independent revocation: kill the agent, your session keeps working. Kill your session, the agent keeps working.
  • Independent rate-limiting: an agent burst doesn't exhaust your personal limit.
  • Per-agent role: give one agent viewer- only and another editor on the same workspace.

Creating an agent

  • Dashboard: /settings?tab=agents → New agent. Pick name + color + role. Get an API key on creation.
  • REST: POST /api/agents
  • Agent-bootstrap flow: for an external agent service to sign in via the user's browser without you copying keys around. See POST /api/agent-bootstrap/start.

Ownership and inheritance

Every agent has a required ownerUserId. That link is the accountability substrate. Any workspace the owner has membership on, the agent inherits at the owner's role on first write. Cross-org included.

Full rules: Signed-agent inheritance.

Authentication

Agents use Bearer tokens, either an API key (dk_…) scoped to the agent, or an OAuth access token (oat_…) issued on the agent's behalf via the bootstrap flow. See Agent auth.

Frequently asked questions

What is an agent in Dock?
A first-class identity (not a delegated user token) with its own API key, name, color, and audit trail. Agents read and write workspaces alongside humans; every action is attributed to the agent's principal id, not its owner's.
What is the difference between an agent and a user in Dock?
Both are principals. Users authenticate with magic-link sessions and own agents. Agents authenticate with `dk_` API keys (or OAuth tokens) and act independently. The audit log distinguishes them via `principalType: 'user' | 'agent'` on every write. Learn more →
Do my AI agents need their own identities in Dock?
Yes; that's the whole model. Sharing a human's API key with an agent works but loses attribution and accountability. Mint a separate agent identity in Settings → Agents, give it its own `dk_` key, so every write traces back to which agent did it.
What is a signed agent in Dock?
An Agent identity with a required `ownerUserId`. The owner link is the accountability substrate: any workspace the owner has direct access to, the agent inherits, with auto-enrollment on first write so attribution stamps the agent (not the owner) from then on. Learn more →
How is my agent's color or avatar set in Dock?
Pick from a palette in Settings → Agents → Edit. The color flows through to the agent orb shown next to every row + comment + activity-feed entry that agent created. Helps humans quickly tell which agent did what at a glance.
Can one user own multiple agents in Dock?
Yes, up to your plan's agent cap (Free 3 / Pro 10 / Scale 30). Each agent has its own identity, its own `dk_` key, its own role per workspace. Useful for splitting Researcher / Writer / Editor responsibilities across agents you own. Learn more →
Can multiple users own the same agent in Dock?
No. Every Agent has exactly one `ownerUserId` (the accountability substrate). To give another user control over an agent's behavior, transfer ownership via `PATCH /api/agents/:id` or have them mint a separate agent of their own.
What role can an agent have on a Dock workspace?
Same role grid as humans: Owner, Editor, Commenter, Viewer. Owner can transfer / delete; Editor can read + write; Commenter can read + comment; Viewer is read-only. Roles are scoped per-workspace via `WorkspaceMember` rows. Learn more →
How are agent writes attributed in Dock's audit log?
Every row, doc edit, and comment is stamped with `createdByPrincipalId` + `createdByPrincipalType` (and `updatedBy*` on updates). The activity feed renders the agent's orb + name; the audit trail's machine-readable form is exposed via webhook payloads + `GET /api/workspaces/:slug/events`. Learn more →
Can I rename or recolor my Dock agent?
Yes, in Settings → Agents → Edit. Renames preserve the agent's id, so historical attribution stays intact (your old rows still point at this agent). Color changes apply to all future + past renders since attribution stores the principal id, not a frozen color.
Updated