Skip to main content
Registry connections allow AgentSystems to pull agent images from container registries. You can connect to multiple registries simultaneously.
Public registries typically work without credentials; some images may require authentication or be rate-limited. Private registries require authentication configured in credentials.

​
Managing via UI

Navigate to Configuration → Registry Connections in the AgentSystems UI at http://localhost:3001. The UI allows you to:
  • Add public and private registries
  • Configure authentication methods
  • Enable/disable registry connections

​
Configuration Structure

Each registry connection requires:
FieldDescriptionRequired
urlRegistry hostname (e.g., docker.io, ghcr.io)Yes
enabledWhether this connection is activeYes
auth.methodAuthentication type: none, basic, bearerYes
auth.username_envEnvironment variable for username (basic auth)No
auth.password_envEnvironment variable for password (basic auth)No
auth.token_envEnvironment variable for token (bearer auth)No

​
Manual Configuration

Edit agentsystems-config.yml directly: 
config_version: 1

registry_connections:
  # Public Docker Hub (no auth needed)
  dockerhub_public:
    url: docker.io
    enabled: true
    auth:
      method: none

  # Private Docker Hub
  dockerhub_private:
    url: docker.io
    enabled: true
    auth:
      method: basic
      username_env: DOCKERHUB_USER
      password_env: DOCKERHUB_TOKEN

  # GitHub Container Registry
  github:
    url: ghcr.io
    enabled: true
    auth:
      method: basic
      username_env: GHCR_USER
      password_env: GHCR_TOKEN
After editing, restart the platform: 
agentsystems restart

​
Registry Usage in Agent Configuration

Agents reference registry connections when specifying their image source: 
agents:
  - name: my-agent
    registry_connection: dockerhub_private  # References the connection ID
    repo: mycompany/my-agent
    tag: v1.0.0

​
Authentication Methods

For public registries and images. No credentials required.
Username and password/token authentication. Used by Docker Hub, GHCR, and many private registries.
Token-based authentication. Common for enterprise registries.
⌘I