Connections
A connection is an organization-level credential grant to a provider. You create one interactively from the Connections page in the web app — never in YAML: credentials are not configuration. Agent YAML then references connections by name, in triggers (connection: github-acme) and in tools; git mounts resolve the project’s GitHub connection implicitly from the repository they name.
Each connection records how the platform authenticates, its credential kind:
GitHub: App installations
Connecting GitHub installs the auto GitHub App on an account. The resulting connection carries the installation id, the account (User or Organization), and a repository selection — either all repositories or an explicit list. Repository selection is the primary scoping lever: agents can only mount, read events from, and write to repositories the installation covers, and you can narrow the list per project.
A GitHub connection also declares which webhook event families it subscribes to (pull_request, issues, issue_comment, check_run, workflow_run, push, and so on). An event family the connection does not subscribe to is dropped at ingress — if a trigger on github.workflow_run.completed never fires, check the connection’s event subscriptions first.
Slack, Discord, Linear: workspace OAuth
Connecting Slack (or Discord, Linear) runs an OAuth flow that authorizes auto in the workspace. The grant records the provider scopes it was given; when a later platform version requests scopes the grant does not have, the connection reports the missing scopes, and reconnecting the provider re-consents to pick them up.Telegram: manager bot token
Telegram has no OAuth. You create a manager bot through BotFather with Bot Management Mode enabled and paste its token when connecting Telegram. The platform validates the token live and can then create per-agent persona bots through the manager (see identities below).Model providers and hosted MCP providers
Two more connection families exist beyond chat and code hosts. Model provider connections hold API tokens foranthropic, openai, or openrouter, letting sessions bill model usage to your own keys. Hosted MCP provider connections are OAuth grants to built-in remote MCP servers — Notion, Sentry, Stripe, Vercel, Datadog, Supabase, and more — that agents consume as tools.
Grants and project scoping
Connections live at the organization, but agents live in projects — so there is an explicit allowance step between them. A project can use a connection only after it has been allowed to that project — granted from the Connections page at connect time or later. The project-level access can further narrow the grant’s resource selection, so one GitHub installation can expose different repository subsets to different projects. At apply time, every trigger, tool, and mount that names a connection resolves it against the grants allowed to the project. A missing connection fails the apply with a diagnostic — unless the trigger is markedoptional: true, in which case it is skipped silently and picks up automatically on the next apply after the connection appears. This is what keeps a shared .auto/ directory or managed template portable across projects with different provider setups.
Connection changes are themselves events: when a project’s usable connection set changes, the platform emits auto.connection.established / auto.connection.removed, which agents can trigger on — the standard way to run one-time setup work the moment a workspace comes online. See lifecycle events.
Agent identities
An identity is the face an agent presents: display name, username, avatar, and a short description. You declare it inline on the agent, and it compiles into its own identity resource named after the agent:.auto/agents/assistant.yaml
.auto/assets/ and must be square PNG or JPEG, 512–2000 px, at most 2 MiB. The description is capped at 140 characters as Slack counts them, because it becomes the bot description on chat surfaces. Field-by-field constraints are in the identity reference.
Provider presence: dedicated bots
By default, agents speak through the workspace’s shared auto app. Optionally, an agent’s identity can be realized as a dedicated, individually-@mentionable bot per provider — its own Slack app, its own Telegram persona bot — through an explicit per-workspace connect step for the agent’s presence. For Slack this creates and installs a real Slack app from the identity (name, avatar, description) via a browser authorization. For Telegram it is push-based: the platform mints a creation deep link, you confirm in Telegram, and the manager bot provisions the persona bot’s profile and webhook. Presence is always an explicit user action — applying YAML never creates provider-side apps on its own.Attribution: tying activity back to sessions
Identity is also how the platform keeps events and artifacts attributable when agents and humans share the same surfaces:- GitHub. All agent writes go through the shared GitHub App identity, so every agent-authored body is stamped with a visible header — avatar, bold display name, and a link back to the authoring session — bracketed by hidden, machine-readable markers. Webhook ingress parses the marker back into
github.auto.attribution { sessionId, agentName }, so trigger filters and routing can distinguish agent activity from human activity and route follow-ups to the right session. Repeated edits converge on exactly one header; it is an attribution convenience, not a security boundary. - Chat. Messages an agent posts carry
auto.authored: trueplus the originating session, and the platform tracks which sessions are attributed to each thread. This powersrouteBy: attributedSessionsdelivery and the loopback guard that stops an agent from reacting to its own messages.
User identity linking
Humans have identities too. In account settings (Linked identities), a user can self-link their GitHub or Linear account through a short OAuth flow that verifies they control it. Each mapping carries a verification level —verified (OAuth-proven), confirmed, or asserted (claimed by an agent, never trusted for anything sensitive).
The flagship consumer is git attribution: when a session was explicitly requested by a user with a verified, git-trusted GitHub identity, the sandbox authors that user’s commits under their GitHub identity; otherwise it falls back to a non-linking Requested-by: commit trailer. An asserted mapping can never flip commit authorship onto a real person. Users can turn git attribution off entirely with a per-account preference.
How the pieces fit
Identity reference
Every identity field, avatar constraints, and the generated-resource rules.
Tools reference
Connection-backed tools, hosted MCP providers, and OAuth tool auth.
Mounts reference
GitHub App mount auth and the per-capability permission matrix.
Lifecycle events
Reacting to connections being established or removed.