Integrations

Integrations give an agent an identity in an external service - most often a GitHub or GitLab account it can act as. Every integration follows the same lifecycle: link, the platform delivers the credential to the agent, and unlink. This page explains how they work; for the commands, see Use integrations from the CLI.

Two levels

Level 1: per-agent integrations

Every integration is scoped to a single agent - there’s no shared credential used by multiple agents. Depending on the mode, the credential is either:

Operator-provided - a PAT or GitHub App private key you supply when linking, or
Platform-provisioned - minted automatically by a credential provider (Level 2).

Either way the credential is stored encrypted and is never exposed to the agent directly. Agents retrieve credentials through the enclave’s credentials API, which is the chokepoint for auditing, revocation, and (for GitHub Apps) on-demand token minting.

Level 2: org-level credential providers

A credential provider is an org-level resource that automates Level 1 provisioning. It holds one privileged identity in the target platform - for example a GitLab token with Owner access to a group - and uses it to mint a dedicated, scoped identity per agent on demand. Register it once; from then on, linking an agent mints a fresh identity, and unlinking deprovisions it.

Think of it as an identity vending machine: one privileged credential in, many scoped credentials out - no shared token across agents. Credential providers currently support GitLab, in two modes: service account (works on the GitLab.com free tier) and project access token. See Credential Providers.

Integration types

Category	Providers	Purpose
Integrations	GitHub, GitLab	Source-code access and identity provisioning
Channels	Telegram	A way to message the agent

An agent can have at most one active integration per provider. (Telegram is a channel, not an integration - see Configure your agent.)

How linking works

When you link an integration (dvx agent integration …), the platform:

Validates the credential against the external service’s API.
Encrypts it with AES-256-GCM envelope encryption.
Stores it as an agent secret (github:token, gitlab:token, …) marked not agent-accessible.
Records an integration with metadata (username, auth type, external IDs).

Because the secret is marked not agent-accessible, the agent can’t read it through the secrets path - it must go through the enclave’s credentials endpoint, which lets the platform control how and when the credential is delivered. For PAT integrations the stored token is returned directly; for GitHub Apps the enclave holds the private key and mints a short-lived (1-hour) installation token, so the agent never sees the key.

Unlinking removes the integration, its secrets, and any associated config in one transaction - and, for automated GitLab integrations, deprovisions the identity in GitLab (best-effort).

Authentication modes

Personal access token (PAT)

The simplest mode: you provide a token, the platform validates and stores it. Available for GitHub and GitLab. Simple and works on all tiers, but the token is tied to a user account and rotates manually.

GitHub App

GitHub-specific. Instead of a static token, the platform stores the app’s private key and mints short-lived installation tokens on demand. Scoped permissions, automatic rotation, not tied to a user - at the cost of creating and installing a GitHub App.

Automated (credential provider)

GitLab-specific. The platform uses a credential provider to provision a dedicated GitLab identity per agent - isolated per-agent identities with automatic provisioning and deprovisioning, at the cost of a provider with Owner access to a GitLab group.

See GitLab Integration for the full GitLab guide and GitHub Integration for GitHub.

Managing integrations

Operators manage integrations with the dvx CLI:

dvx agent integration list <agent>
dvx agent integration gitlab link <agent> --pat <token>
dvx agent integration github link <agent> --pat <token>
dvx agent integration gitlab unlink <agent>

Tokens can be passed with --pat, piped from stdin, or entered interactively. See Use integrations from the CLI for the full workflow, including credential providers.

Secret naming convention

Integration secrets follow the provider:key pattern:

Secret name	Created by	Description
`github:token`	GitHub PAT integration	GitHub personal access token
`github:private_key`	GitHub App integration	GitHub App private key (PEM)
`gitlab:token`	GitLab integration (PAT or automated)	GitLab access token
`telegram:bot_token`	Telegram channel	Telegram bot token
`telegram:allowed_users`	Operator	Comma-separated Telegram user IDs
`llmproxy:llm.api_key`	Operator	Org-level LLM API key for the proxy
`agent:llmproxy.llm.api_key`	Operator	Per-agent LLM API key (overrides org-level)

All integration secrets are stored not-agent-accessible - agents reach them through the credentials API, not the secrets API.