Skip to content

Getting Started

This guide will help you get started with the Directory project, including setting up your development environment, building the project, running tests, and deploying the services.

Prerequisites

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

Note

Make sure Docker is installed with Buildx.

Quick Start

To quickly get started with the Directory project, you need two components:

  • Directory API Server: The main service that manages agent directory records and handles API requests. Check Deployment section for deployment options.
  • Directory Client: A command-line or SDK tool to interact with the Directory API Server. Check Artifacts distribution section for installation instructions.

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 fetches all project dependencies and prepares 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.0.0-rc.3
docker pull ghcr.io/agntcy/dir-apiserver:v1.0.0-rc.3

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.0.0-rc.3

Binaries

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

Check CLI References for detailed installation instructions.

SDKs

Directory MCP Server

The Directory services are also accessible through the Directory MCP Server. It provides a standardized interface for AI assistants and tools to interact with the Directory system and work with OASF agent records. See the Directory CLI Reference for more information.

Deployment

Directory API services can be deployed either using the Taskfile or directly via the released Helm chart.

Using Taskfile

This starts the necessary components such as storage and API services.

DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL=https://schema.oasf.outshift.com task server:start

Note

MacOS users may encounter a "port 5000 already in use" error. This is likely caused by the AirPlay Receiver feature. You can disable it in your System Settings.

Using Helm chart

This deploys Directory services into an existing Kubernetes cluster.

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

Alternatively, you can configure the OASF schema URL explicitly:

helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.0.0-rc.3 \
  --set apiserver.config.oasf_api_validation.schema_url=https://schema.oasf.outshift.com

Or create a values.yaml file:

apiserver:
  config:
    oasf_api_validation:
      schema_url: "https://schema.oasf.outshift.com"

Then deploy:

helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.0.0-rc.3 -f values.yaml

For more configuration options, see the Validation documentation.

Using Docker Compose

This deploys Directory services using Docker Compose.

While the Directory server has a default OASF schema URL, Docker Compose deployments may require explicitly setting the DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL environment variable:

cd install/docker
export DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL=https://schema.oasf.outshift.com
docker compose up -d

Alternatively, you can disable API validation (not recommended for production):

cd install/docker
export DIRECTORY_SERVER_OASF_API_VALIDATION_DISABLE=true
docker compose up -d

For more configuration options, see the Validation documentation.

Next Steps

Now that you have the Directory services running, you can start using the Directory CLI to create and store your first agent record. See the Directory CLI Reference for more information.

For detailed use cases, see the Features and Usage Scenarios documentation, including: