Directory

Buf Registry | MCP Server | Go SDK | Python SDK | JavaScript SDK | GitHub Actions |

The Directory (dir) allows publication, exchange, and discovery of information about records over a distributed peer-to-peer network. It leverages OASF to describe AI agents and provides a set of APIs and tools to store, publish, and discover records across the network by their attributes and constraints. Directory also leverages CSIT for continuous system integration and testing across different versions, environments, and features.

Features

Directory enables several key capabilities for the agentic AI ecosystem:

• Capability-Based Discovery: Agents publish structured metadata describing their functional characteristics as described by the OASF. The system organizes this information using hierarchical taxonomies, enabling efficient matching of capabilities to requirements.
• Verifiable Claims: While agent capabilities are often subjectively evaluated, Directory provides cryptographic mechanisms for data integrity and provenance tracking. This allows users to make informed decisions about agent selection.
• Semantic Linkage: Components can be securely linked to create various relationships like version histories for evolutionary development, collaborative partnerships where complementary skills solve complex problems, and dependency chains for composite agent workflows.
• Distributed Architecture: Built on proven distributed systems principles, Directory uses content-addressing for global uniqueness and implements distributed hash tables (DHT) for scalable content discovery and synchronization across decentralized networks.
• Tooling and Integration: Provides a suite of command-line tools, SDKs, and APIs to facilitate interaction with the system, enabling developers to manage Directory records and node operations programmatically.
• Security and Trust: Incorporates robust security measures including cryptographic signing, verification of claims, secure communication protocols, and access controls to ensure the integrity and authenticity of Directory records and nodes.

Documentation

Check the Documentation for a full walkthrough of all the Directory features.

Source tree

• proto - gRPC specification for data models and services
• api - API models for tools and packages
• cli - command line client for interacting with system components
• client - client SDK for development and API workflows
• docs - research details and documentation around the project
• install - deployment assets (Helm charts, Docker Compose)
• reconciler - standalone service for periodic reconciliation (regsync, indexer)
• server - API services to manage storage, routing, and networking operations
• utils - shared utilities (logging, SPIFFE)
• tests - test suites and end-to-end (e2e) testing framework

Prerequisites

To build the project and work with the code, you will need the following installed in your system

• Taskfile
• Docker
• Golang

Make sure Docker is installed with Buildx.

Development

Use Taskfile for all related development operations such as testing, validating, deploying, and working with the project.

Clone the repository

git clone https://github.com/agntcy/dir
cd dir

Initialize the project

This step will fetch all project dependencies and prepare the environment for development.

task deps

Make changes

Make the changes to the source code and rebuild for later testing.

task build

Test changes

The local testing pipeline relies on Golang to perform unit tests, and Docker to perform E2E tests in an isolated Kubernetes environment using Kind.

task test:unit
task test:e2e

Artifacts distribution

All artifacts are tagged using the Semantic Versioning and follow the checked-out source code tags. It is not advised to use artifacts with mismatched versions.

Container images

All container images are distributed via GitHub Packages.

docker pull ghcr.io/agntcy/dir-ctl:v1.3.0
docker pull ghcr.io/agntcy/dir-apiserver:v1.3.0

Helm charts

All helm charts are distributed as OCI artifacts via GitHub Packages.

helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.3.0

Binaries

All release binaries are distributed via GitHub Releases and Homebrew agntcy/dir tap.

SDKs

Golang

• Go package
• Source code

Python

• PyPi package
• Source code

JavaScript

• NPM package
• Source code

Deployment

See the Quickstart documentation for the full platform support matrix, prerequisites, and configuration details.

Using dirctl daemon

The fastest way to run a local Directory instance is the built-in daemon. It bundles the gRPC apiserver and reconciler into a single process with embedded SQLite and a local OCI store.

dirctl daemon start

All state is stored under ~/.agntcy/dir/ by default. The daemon listens on localhost:8888 and can be managed with dirctl daemon stop and dirctl daemon status.

A custom configuration file can be used to connect to external databases (e.g. PostgreSQL) or remote OCI registries instead of the built-in SQLite and local store:

dirctl daemon start --config /path/to/daemon.config.yaml

Using Docker Compose

This will deploy Directory services (apiserver, reconciler, Zot registry, PostgreSQL) as separate containers using Docker Compose:

cd install/docker
docker compose up -d

Contributors working on the Directory codebase can also use the Taskfile wrapper:

task server:start

Using Helm Chart

This will deploy Directory services into an existing Kubernetes cluster.

helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.3.0
helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.3.0

Copyright Notice

Copyright Notice and License

Distributed under Apache 2.0 License. See LICENSE for more information. Copyright AGNTCY Contributors (https://github.com/agntcy)