Registry Connections - AgentSystems

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:

Field	Description	Required
`url`	Registry hostname (e.g., `docker.io`, `ghcr.io`)	Yes
`enabled`	Whether this connection is active	Yes
`auth.method`	Authentication type: `none`, `basic`, `bearer`	Yes
`auth.username_env`	Environment variable for username (basic auth)	No
`auth.password_env`	Environment variable for password (basic auth)	No
`auth.token_env`	Environment 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

None

For public registries and images. No credentials required.

Basic

Username and password/token authentication. Used by Docker Hub, GHCR, and many private registries.

Bearer

Token-based authentication. Common for enterprise registries.

​Managing via UI

​Configuration Structure

​Manual Configuration

​Registry Usage in Agent Configuration

​Authentication Methods

Managing via UI

Configuration Structure

Manual Configuration

Registry Usage in Agent Configuration

Authentication Methods