Local Deployment
Run the Agent Directory on your own machine for development, testing, or as a standalone local instance. This page defines the supported deployment modes, platform support matrix, and prerequisites for local-first Directory usage.
Deployment Modes
Directory offers the following local deployment modes with different trade-offs:
| Mode | Components | Requires Docker | Best for |
|---|---|---|---|
| dirctl daemon | Single process (apiserver + reconciler + SQLite + local OCI store) | No | Quick setup, single-user development, lightweight testing |
| Docker Compose | Separate containers (apiserver, reconciler, Zot registry, PostgreSQL) | Yes | Multi-service development, closer to production topology |
Platform Support Matrix
dirctl daemon (recommended local mode)
| OS | Architecture | Status | Notes |
|---|---|---|---|
| macOS | arm64 (Apple Silicon) | Supported | Primary development platform |
| macOS | amd64 (Intel) | Supported | |
| Linux | amd64 | Supported | |
| Linux | arm64 | Supported | |
| Windows | amd64 | Experimental | Binary is available from GitHub Releases. Docker Compose or WSL2 are recommended alternatives if you encounter issues. |
Docker Compose
| OS | Architecture | Status | Notes |
|---|---|---|---|
| macOS | arm64 / amd64 | Supported | Requires Docker Desktop or Colima |
| Linux | amd64 / arm64 | Supported | Requires Docker Engine with Compose plugin |
| Windows | amd64 | Supported | Requires Docker Desktop |
dirctl CLI (client only)
The dirctl CLI binary is available for all platforms regardless of which deployment mode is used for the server.
| OS | Architecture | Status |
|---|---|---|
| macOS | arm64 / amd64 | Supported |
| Linux | amd64 / arm64 | Supported |
| Windows | amd64 | Supported |
Prerequisites
dirctl daemon
- dirctl binary: install via Homebrew or download from GitHub Releases:
brew tap agntcy/dir https://github.com/agntcy/dir
brew install dirctl
# Example for Linux amd64 — adjust OS and architecture as needed
curl -L https://github.com/agntcy/dir/releases/latest/download/dirctl-linux-amd64 -o dirctl
chmod +x dirctl
sudo mv dirctl /usr/local/bin/
Docker Compose
- Docker with the Compose plugin (v2)
- Docker Desktop (macOS / Windows) or Docker Engine (Linux)
Taskfile (contributors)
Configuration
Without --config, the daemon listens on localhost:8888 and stores all data (SQLite database, OCI store, routing) under ~/.agntcy/dir/.
To override defaults, pass a YAML configuration file or use environment variables prefixed with DIRECTORY_DAEMON_:
dirctl daemon start --config /path/to/daemon.config.yaml
dirctl daemon start --data-dir /var/lib/dir
DIRECTORY_DAEMON_SERVER_LISTEN_ADDRESS="localhost:9999" dirctl daemon start
When --config is provided, the file replaces built-in defaults entirely. See the reference configuration for all available options.
Sync is not supported with the local OCI store
The default daemon configuration uses a filesystem-based OCI Image Layout (server.store.oci.local_dir). Records synced from a remote peer via regsync are not visible to the daemon in this mode because the in-memory tag cache is not refreshed when an external process writes to the store. To use sync, configure a remote OCI registry (e.g., Zot) instead.
Docker Compose deployment
The Docker Compose stack runs separate containers for the apiserver, reconciler, Zot OCI registry, and PostgreSQL:
cd install/docker
docker compose up -d
This is closer to the production topology and is useful for testing multi-service interactions. See the Kubernetes Deployment guide for deploying with Helm in a Kind cluster.