From 33509a9a0a3e98f8b3f960ad853bc236014aeb4d Mon Sep 17 00:00:00 2001 From: Aron Kerekes Date: Thu, 21 May 2026 19:12:59 +0200 Subject: [PATCH 1/3] chore: dir restructure Signed-off-by: Aron Kerekes --- docs/dir/.index | 45 +- docs/dir/dir-api-reference.md | 3 +- .../{architecture.md => dir-architecture.md} | 0 docs/dir/dir-cli-guide.md | 7 + ...-cli-reference.md => dir-cli-reference.md} | 79 ++- ...ts.md => dir-component-event-streaming.md} | 6 +- ...{directory-gui.md => dir-component-gui.md} | 0 ...ory-mcp.md => dir-component-mcp-server.md} | 0 ...d => dir-component-oidc-authentication.md} | 8 +- ...md => dir-component-records-validation.md} | 2 +- docs/dir/dir-component-routing.md | 31 + ....md => dir-component-runtime-discovery.md} | 0 docs/dir/dir-component-store.md | 28 + ...-model.md => dir-component-trust-model.md} | 0 ...scenarios.md => dir-features-scenarios.md} | 29 +- ...n-aws-eks.md => dir-federation-aws-eks.md} | 2 +- docs/dir/dir-federation-overview.md | 36 + ...profiles.md => dir-federation-profiles.md} | 0 ...-federation.md => dir-federation-setup.md} | 0 ...g.md => dir-federation-troubleshooting.md} | 0 docs/dir/dir-getting-started.md | 54 +- docs/dir/{overview.md => dir-overview.md} | 6 +- ...d-deployment.md => dir-prod-deployment.md} | 2 +- docs/dir/dir-quickstart.md | 131 ++++ docs/dir/{directory-sdk.md => dir-sdk.md} | 18 +- docs/dir/{validation.md => dir-validation.md} | 0 docs/dir/directory-cli.md | 668 ------------------ mkdocs/mkdocs.yml | 6 +- 28 files changed, 403 insertions(+), 758 deletions(-) rename docs/dir/{architecture.md => dir-architecture.md} (100%) create mode 100644 docs/dir/dir-cli-guide.md rename docs/dir/{directory-cli-reference.md => dir-cli-reference.md} (92%) rename docs/dir/{events.md => dir-component-event-streaming.md} (98%) rename docs/dir/{directory-gui.md => dir-component-gui.md} (100%) rename docs/dir/{directory-mcp.md => dir-component-mcp-server.md} (100%) rename docs/dir/{directory-oidc-authentication.md => dir-component-oidc-authentication.md} (97%) rename docs/dir/{records-validation.md => dir-component-records-validation.md} (98%) create mode 100644 docs/dir/dir-component-routing.md rename docs/dir/{runtime.md => dir-component-runtime-discovery.md} (100%) create mode 100644 docs/dir/dir-component-store.md rename docs/dir/{trust-model.md => dir-component-trust-model.md} (100%) rename docs/dir/{scenarios.md => dir-features-scenarios.md} (96%) rename docs/dir/{federation-aws-eks.md => dir-federation-aws-eks.md} (99%) create mode 100644 docs/dir/dir-federation-overview.md rename docs/dir/{federation-profiles.md => dir-federation-profiles.md} (100%) rename docs/dir/{partner-prod-federation.md => dir-federation-setup.md} (100%) rename docs/dir/{federation-troubleshooting.md => dir-federation-troubleshooting.md} (100%) rename docs/dir/{overview.md => dir-overview.md} (93%) rename docs/dir/{prod-deployment.md => dir-prod-deployment.md} (96%) create mode 100644 docs/dir/dir-quickstart.md rename docs/dir/{directory-sdk.md => dir-sdk.md} (82%) rename docs/dir/{validation.md => dir-validation.md} (100%) delete mode 100644 docs/dir/directory-cli.md diff --git a/docs/dir/.index b/docs/dir/.index index 0f21f64..210a7c0 100644 --- a/docs/dir/.index +++ b/docs/dir/.index @@ -1,25 +1,32 @@ nav: - - Overview: overview.md - - Getting Started: - - dir-getting-started.md + - Get Started: + - Overview: overview.md + - Features and Usage Scenarios: scenarios.md + - Quickstart: quickstart.md + - Concepts: + - Architecture: architecture.md + - Records: records-validation.md + - Store: store.md + - Routing: routing.md + - Trust Model: trust-model.md + - Federation: federation-overview.md + - Extensions: + - Runtime Discovery: runtime.md + - Event Streaming: events.md + - MCP Server: directory-mcp.md + - GUI: directory-gui.md + - Deploy: - Local Deployment: dir-deployment-local.md - Kubernetes Deployment: dir-deployment-kubernetes.md - - OIDC Authentication: directory-oidc-authentication.md - - Features and Usage Scenarios: scenarios.md - - Production Deployment: prod-deployment.md - - CLI Guide: directory-cli.md - - MCP Server: directory-mcp.md - - Federation: - - Federation on Amazon EKS: federation-aws-eks.md - - Running a Federated Directory Instance: partner-prod-federation.md - - Profiles: federation-profiles.md - - Best Practices and Troubleshooting: federation-troubleshooting.md + - Production Deployment: prod-deployment.md + - Federation Deployment: + - Federation on Amazon EKS: federation-aws-eks.md + - Running a Federated Directory Instance: partner-prod-federation.md + - Profiles: federation-profiles.md + - Best Practices and Troubleshooting: federation-troubleshooting.md + - OIDC Authentication: directory-oidc-authentication.md + - SDKs: + - SDK Overview: directory-sdk.md - Reference: - CLI Reference: directory-cli-reference.md - API Reference: dir-api-reference.md - - Architecture: architecture.md - - Components: - - Runtime Discovery: runtime.md - - Event Streaming: events.md - - Records and Validation: records-validation.md - - Trust Model: trust-model.md diff --git a/docs/dir/dir-api-reference.md b/docs/dir/dir-api-reference.md index 9c05c39..06cdb45 100644 --- a/docs/dir/dir-api-reference.md +++ b/docs/dir/dir-api-reference.md @@ -1,3 +1,2 @@ # Directory API Reference - -The Directory API reference is available at [buf.build/agntcy/dir](https://buf.build/agntcy/dir). \ No newline at end of file +The Directory API reference is available at [buf.build/agntcy/dir](https://buf.build/agntcy/dir). diff --git a/docs/dir/architecture.md b/docs/dir/dir-architecture.md similarity index 100% rename from docs/dir/architecture.md rename to docs/dir/dir-architecture.md diff --git a/docs/dir/dir-cli-guide.md b/docs/dir/dir-cli-guide.md new file mode 100644 index 0000000..8b2d7d3 --- /dev/null +++ b/docs/dir/dir-cli-guide.md @@ -0,0 +1,7 @@ +# Directory CLI Guide + +The CLI guide has been reorganized: + +- **Installation and first publish/discover flow** — [Quickstart](quickstart.md) +- **Workflow examples** (sync, import, export, events) — [Features and Usage Scenarios](scenarios.md) +- **Command reference** — [Directory CLI Reference](directory-cli-reference.md) diff --git a/docs/dir/directory-cli-reference.md b/docs/dir/dir-cli-reference.md similarity index 92% rename from docs/dir/directory-cli-reference.md rename to docs/dir/dir-cli-reference.md index 81cda8e..a4832b1 100644 --- a/docs/dir/directory-cli-reference.md +++ b/docs/dir/dir-cli-reference.md @@ -1,5 +1,82 @@ # Directory CLI Command Reference +Command-line reference for `dirctl`. Install the CLI in the [Quickstart](quickstart.md) +only; workflow examples live in [Features and Usage Scenarios](scenarios.md). + +## Global options + +### Output formats + +All commands support `--output` / `-o`: + +| Format | Description | Use case | +|--------|-------------|----------| +| `human` | Formatted tables and colors (default) | Interactive use | +| `json` | Pretty-printed JSON | Debugging, single-record scripts | +| `jsonl` | One JSON object per line | Streaming, batch processing | +| `raw` | Values only (CIDs, IDs) | Shell pipelines | + +Structured formats send data to **stdout** and messages to **stderr**, so piping to `jq` +works cleanly. + +```bash +CID=$(dirctl push record.json -o raw) +dirctl routing search --skill "AI" -o json | jq '.[] | .record_ref.cid' +dirctl events listen -o jsonl | jq -c 'select(.type == "EVENT_TYPE_RECORD_PUSHED")' +``` + +### Server connection + +```bash +dirctl --server-addr localhost:8888 routing list +export DIRECTORY_CLIENT_SERVER_ADDRESS=localhost:8888 +dirctl --context dev routing list # see Context Operations below +``` + +### Authentication + +For remote servers, authenticate with OIDC before running commands. The full auth model, +gateway endpoints, and SPIFFE/SPIRE integration are documented in +[OIDC Authentication](directory-oidc-authentication.md). + +| Command | Description | +|---------|-------------| +| `dirctl auth login` | OIDC login (PKCE, `--no-browser`, or `--device`) | +| `dirctl auth logout` | Clear cached credentials | +| `dirctl auth status` | Show current auth state | + +```bash +dirctl auth login --oidc-issuer "https://prod.idp.ads.outshift.io" --oidc-client-id "dirctl" +dirctl --auth-mode=oidc --server-addr prod.gateway.ads.outshift.io:443 search --skill "AI" +``` + +Pre-issued tokens: `--auth-token` or `DIRECTORY_CLIENT_AUTH_TOKEN` for CI and automation. +Other modes: `--auth-mode=x509`, `jwt`, `tls`, or `insecure` for local development. Default +(empty) auto-detects SPIFFE → OIDC → insecure. + +### Command groups + +| Group | Commands | +|-------|----------| +| Daemon | `daemon start`, `stop`, `status` | +| Auth | `auth login`, `logout`, `status` | +| Context | `context list`, `current`, `set`, `show`, `validate` | +| Storage | `push`, `pull`, `delete`, `info` | +| Import / Export | `import`, `export` | +| Routing | `routing publish`, `list`, `search` | +| Search | `search` | +| Security | `sign`, `verify`, `validate`, `naming verify` | +| Sync | `sync create`, `status`, `list`, `delete` | +| Events | `events listen` | + +### Getting help + +```bash +dirctl --help +dirctl routing --help +dirctl routing search --help +``` + ## Daemon Operations The daemon commands run a self-contained local directory server that bundles the gRPC apiserver and reconciler into a single process with embedded SQLite and a filesystem OCI store. All state is stored under `~/.agntcy/dir/` by default. @@ -935,7 +1012,7 @@ Record name verification proves that the signing key is authorized by the domain dirctl sign --key private.key ``` -3. Check verification status using [`dirctl naming verify`](./directory-cli.md#dirctl-naming-verify-reference). +3. Check verification status using [`dirctl naming verify`](#dirctl-naming-verify-reference). ### `dirctl sign [flags]` diff --git a/docs/dir/events.md b/docs/dir/dir-component-event-streaming.md similarity index 98% rename from docs/dir/events.md rename to docs/dir/dir-component-event-streaming.md index e308ad5..e163ad5 100644 --- a/docs/dir/events.md +++ b/docs/dir/dir-component-event-streaming.md @@ -500,6 +500,6 @@ DIRECTORY_SERVER_EVENTS_LOG_PUBLISHED_EVENTS=false ## See Also - [Events API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1) - Protocol buffer definitions and message formats -- [CLI Reference](directory-cli.md) - Complete CLI command documentation -- [SDK Reference](directory-sdk.md) - Language-specific SDK usage guides -- [Getting Started](dir-getting-started.md) - Initial setup and deployment guide +- [CLI Reference](directory-cli-reference.md) — `dirctl events listen` and related commands +- [SDK Overview](directory-sdk.md) — language-specific SDK usage +- [Quickstart](quickstart.md) — install CLI and start a local Directory diff --git a/docs/dir/directory-gui.md b/docs/dir/dir-component-gui.md similarity index 100% rename from docs/dir/directory-gui.md rename to docs/dir/dir-component-gui.md diff --git a/docs/dir/directory-mcp.md b/docs/dir/dir-component-mcp-server.md similarity index 100% rename from docs/dir/directory-mcp.md rename to docs/dir/dir-component-mcp-server.md diff --git a/docs/dir/directory-oidc-authentication.md b/docs/dir/dir-component-oidc-authentication.md similarity index 97% rename from docs/dir/directory-oidc-authentication.md rename to docs/dir/dir-component-oidc-authentication.md index bc0cc9a..6458f94 100644 --- a/docs/dir/directory-oidc-authentication.md +++ b/docs/dir/dir-component-oidc-authentication.md @@ -85,7 +85,7 @@ This keeps token handling and policy enforcement at the edge rather than spreadi Human users typically authenticate with `dirctl auth login`, using browser-based PKCE, headless login, or device flow. This is the best fit for operators and developers who need interactive CLI access to a remote Directory. -Use the [CLI Guide](directory-cli.md#authentication) for command examples and token cache behavior. +Use the [CLI Reference](directory-cli-reference.md#global-options) for command examples and token cache behavior. ### Service Users and Non-Interactive Automation @@ -155,7 +155,7 @@ In both cases, the Directory-facing model is the same: the edge validates tokens The two main operator touchpoints are: -- [`directory-cli.md`](directory-cli.md) for user-facing commands such as `dirctl auth login`, `dirctl auth status`, `--auth-mode=oidc`, and pre-issued token usage +- [CLI Reference](directory-cli-reference.md#global-options) for `dirctl auth login`, `dirctl auth status`, `--auth-mode=oidc`, and pre-issued token usage - deployment configuration for Envoy and the `ext_authz` layer that trusts one or more issuers and maps verified identities to principals and roles When documenting or configuring this feature, it helps to think in three layers: @@ -369,7 +369,7 @@ Client identity -> Envoy validation -> `ext_authz` canonical principal mapping - ## Further Reading -- [CLI Guide](directory-cli.md) for command-level usage -- [Getting Started](dir-getting-started.md) for deployment entry points +- [CLI Reference](directory-cli-reference.md) for command-level usage +- [Quickstart](quickstart.md) and [Deploy](dir-deployment-local.md) for deployment entry points - [Production Deployment](prod-deployment.md) for production topology and external endpoints - [Running a Federated Directory Instance](partner-prod-federation.md) for network federation guidance diff --git a/docs/dir/records-validation.md b/docs/dir/dir-component-records-validation.md similarity index 98% rename from docs/dir/records-validation.md rename to docs/dir/dir-component-records-validation.md index b0837cd..56f4161 100644 --- a/docs/dir/records-validation.md +++ b/docs/dir/dir-component-records-validation.md @@ -21,7 +21,7 @@ Records must include a `name` field with a domain-based identifier that enables - The domain must host a JWKS file at `:///.well-known/jwks.json`. - Records signed with a private key associated with a public key present in that JWKS file can be verified as authorized by the domain. -See the [Directory CLI documentation](directory-cli.md#name-verification) for details on name verification workflows. +See [Features and Usage Scenarios — Name Verification](scenarios.md#name-verification) and the [CLI Reference](directory-cli-reference.md#security-verification) for name verification workflows. ### Example Email Agent diff --git a/docs/dir/dir-component-routing.md b/docs/dir/dir-component-routing.md new file mode 100644 index 0000000..f16d569 --- /dev/null +++ b/docs/dir/dir-component-routing.md @@ -0,0 +1,31 @@ +# Routing + +**Routing** (content routing) is a core Directory component that maps agent **skills** to +record identifiers and to the directory servers that host those records. It builds on a +[Distributed Hash Table (DHT)](https://en.wikipedia.org/wiki/Distributed_hash_table) so +discovery scales across a decentralized network of peers. + +## Announce and discover + +Publishing a record to the network is a two-step process: + +1. **Store** — push the record to local storage and obtain its CID. +2. **Announce** — call `routing publish` so the server advertises the CID and its skill + taxonomy in the DHT. Announcements are processed asynchronously and have a TTL; republish + periodically to keep routing data fresh. + +Discovery uses: + +- **`routing list`** — records indexed on the local peer only. +- **`routing search`** — records announced by remote peers (cached network view). + +Skill matching supports exact and hierarchical prefix matching. Network search results +reflect cached announcements and may be stale or incomplete until peers replicate records. + +## Related documentation + +- [Architecture](architecture.md) — full system design and diagram +- [Records](records-validation.md) — skill taxonomy and record structure +- [Features and Usage Scenarios — Announce / Discover](scenarios.md#announce) — CLI walkthroughs +- [CLI Reference — Routing Operations](directory-cli-reference.md#routing-operations) — `routing publish`, `list`, `search` +- [Federation](federation-overview.md) — multi-instance routing across federated directories diff --git a/docs/dir/runtime.md b/docs/dir/dir-component-runtime-discovery.md similarity index 100% rename from docs/dir/runtime.md rename to docs/dir/dir-component-runtime-discovery.md diff --git a/docs/dir/dir-component-store.md b/docs/dir/dir-component-store.md new file mode 100644 index 0000000..a166af2 --- /dev/null +++ b/docs/dir/dir-component-store.md @@ -0,0 +1,28 @@ +# Store + +The **Store** is a core Directory component that persists agent records as +[OCI](https://opencontainers.org) artifacts in a registry-backed content store. + +## Role in the system + +When a client pushes a record, the server: + +1. Validates the record against the [OASF](../oasf/open-agentic-schema-framework.md) schema. +2. Writes the payload to the configured OCI registry. +3. Derives a [content identifier (CID)](https://github.com/multiformats/cid) from the artifact digest for immutable, content-addressed lookup. + +Records can be retrieved by CID or, when configured with a verifiable name, by +Docker-style name references (`name`, `name:version`, `name:version@cid`). + +## Backends + +Directory supports OCI-compatible registries including [Zot](https://github.com/project-zot/zot) +(default for local deployments), GitHub Container Registry, and Docker Hub. The server selects +the backend via store configuration (see [Local Deployment](dir-deployment-local.md) and +[Production Deployment](prod-deployment.md)). + +## Related documentation + +- [Records](records-validation.md) — OASF record model, CIDs, and validation +- [Features and Usage Scenarios — Store](scenarios.md#store) — CLI examples and registry configuration +- [CLI Reference — Storage Operations](directory-cli-reference.md#storage-operations) — `push`, `pull`, `delete`, `info` diff --git a/docs/dir/trust-model.md b/docs/dir/dir-component-trust-model.md similarity index 100% rename from docs/dir/trust-model.md rename to docs/dir/dir-component-trust-model.md diff --git a/docs/dir/scenarios.md b/docs/dir/dir-features-scenarios.md similarity index 96% rename from docs/dir/scenarios.md rename to docs/dir/dir-features-scenarios.md index 5e15918..1cfba58 100644 --- a/docs/dir/scenarios.md +++ b/docs/dir/dir-features-scenarios.md @@ -13,11 +13,9 @@ The Agent Directory Service is also accessible through the Directory MCP Server. The following prerequisites are required to follow the examples below: -- Locally available Directory CLI client -- Running instance of Directory API server - -To deploy the necessary components, please refer to the [Getting Started](dir-getting-started.md) -guide. +- Directory CLI (`dirctl`) — install via [Quickstart](quickstart.md) +- Running Directory API server — start with `dirctl daemon start` or see + [Local Deployment](dir-deployment-local.md) / [Kubernetes Deployment](dir-deployment-kubernetes.md) ## Build @@ -636,6 +634,27 @@ dirctl import --type=mcp \ For comprehensive documentation including all configuration options, filtering capabilities, LLM enrichment setup, and advanced usage examples, see the [CLI Import Workflow documentation](https://github.com/agntcy/dir/tree/main/cli#-import-workflow). +## Export + +Export records from Directory into formats for external tools and agentic CLIs: + +```bash +# Single record as A2A AgentCard +dirctl export my-agent:1.0 --format=a2a --output-file=./agent-card.json + +# SKILL.md for Cursor, Claude Code, etc. +dirctl export my-agent:1.0 --format=agent-skill --output-file=./SKILL.md + +# GitHub Copilot MCP config +dirctl export my-agent:1.0 --format=mcp-ghcopilot --output-file=./mcp.json + +# Batch export by module +dirctl export --output-dir=./exports/ --format=a2a --module "integration/a2a" +``` + +By default, only the latest semver version is exported; use `--all-versions` to export every +version. See [CLI Reference — Export Operations](directory-cli-reference.md#export-operations). + ## gRPC Error Codes The following table lists the gRPC error codes returned by the server APIs, along with a diff --git a/docs/dir/federation-aws-eks.md b/docs/dir/dir-federation-aws-eks.md similarity index 99% rename from docs/dir/federation-aws-eks.md rename to docs/dir/dir-federation-aws-eks.md index c7563db..20a0fac 100644 --- a/docs/dir/federation-aws-eks.md +++ b/docs/dir/dir-federation-aws-eks.md @@ -658,7 +658,7 @@ This guide does not try to provision the AWS infrastructure from zero in the mai # Expected: Error: record not found ``` - If you want a fuller post-deployment smoke test against your own Directory, use the normal Directory CLI workflows from [Directory CLI Guide](directory-cli.md): + If you want a fuller post-deployment smoke test against your own Directory, use the CLI workflows in [Features and Usage Scenarios](scenarios.md) and the [CLI Reference](directory-cli-reference.md): - `dirctl push record.json` - `dirctl info ` diff --git a/docs/dir/dir-federation-overview.md b/docs/dir/dir-federation-overview.md new file mode 100644 index 0000000..63da7b8 --- /dev/null +++ b/docs/dir/dir-federation-overview.md @@ -0,0 +1,36 @@ +# Federation + +**Federation** connects separate Directory deployments so agents published in one instance +can be discovered and synchronized across organizational or regional boundaries. Federated +instances exchange routing metadata and records according to configured profiles and trust +policies. + +## When to federate + +- **Join the public network** — connect to the production Directory at + `prod.api.ads.outshift.io` to discover agents published by other participants. +- **Run a private federated instance** — deploy your own Directory and peer with selected + partners while keeping operational control. +- **Multi-cloud or multi-region** — link EKS (or other) clusters so teams share a consistent + agent catalog. + +## Deployment guides + +Federation is configured at deploy time. Choose the guide that matches your environment: + +| Guide | Use case | +|-------|----------| +| [Federation on Amazon EKS](federation-aws-eks.md) | End-to-end AWS deployment into the public network | +| [Running a Federated Directory Instance](partner-prod-federation.md) | Connect an existing instance to production federation | +| [Profiles](federation-profiles.md) | Federation profile configuration | +| [Best Practices and Troubleshooting](federation-troubleshooting.md) | Operations and debugging | + +Also see [Production Deployment](prod-deployment.md) and +[OIDC Authentication](directory-oidc-authentication.md) for gateway and external access when +federating user-facing endpoints. + +## Concepts + +- [Trust Model](trust-model.md) — signing, verification, and SPIFFE/SPIRE identity +- [Routing](routing.md) — how skill-based discovery works within and across peers +- [Architecture](architecture.md) — Directory components and trust boundaries diff --git a/docs/dir/federation-profiles.md b/docs/dir/dir-federation-profiles.md similarity index 100% rename from docs/dir/federation-profiles.md rename to docs/dir/dir-federation-profiles.md diff --git a/docs/dir/partner-prod-federation.md b/docs/dir/dir-federation-setup.md similarity index 100% rename from docs/dir/partner-prod-federation.md rename to docs/dir/dir-federation-setup.md diff --git a/docs/dir/federation-troubleshooting.md b/docs/dir/dir-federation-troubleshooting.md similarity index 100% rename from docs/dir/federation-troubleshooting.md rename to docs/dir/dir-federation-troubleshooting.md diff --git a/docs/dir/dir-getting-started.md b/docs/dir/dir-getting-started.md index 6914953..9b1824a 100644 --- a/docs/dir/dir-getting-started.md +++ b/docs/dir/dir-getting-started.md @@ -1,52 +1,10 @@ # Getting Started -The Agent Directory Service supports multiple deployment modes depending on -your use case. Choose the approach that best fits your environment and goals. +Onboarding content has moved to [Quickstart](quickstart.md). -## Deployment Options +Deployment guides: -| Mode | Components | Best for | -|------|-----------|----------| -| [**dirctl daemon**](dir-deployment-local.md#dirctl-daemon-recommended-local-mode) | Single process (apiserver + reconciler + SQLite + local OCI store) | Quick local setup, single-user development, lightweight testing | -| [**Docker Compose**](dir-deployment-local.md#docker-compose-deployment) | Separate containers (apiserver, reconciler, Zot registry, PostgreSQL) | Multi-service local development, closer to production topology | -| [**Helm / Kubernetes**](dir-deployment-kubernetes.md) | Full Kubernetes deployment with SPIRE identity | Dev/staging clusters, team environments, pre-production | - -### Start locally in seconds - -The fastest way to get a Directory running is the built-in daemon, which -requires only the `dirctl` binary: - -```bash -brew tap agntcy/dir https://github.com/agntcy/dir -brew install dirctl - -dirctl daemon start -``` - -The daemon listens on `localhost:8888` with all state stored under -`~/.agntcy/dir/`. See [Local Deployment](dir-deployment-local.md) for the full -guide, platform support matrix, and configuration options. - -### Deploy on Kubernetes - -For team environments or when you need SPIFFE/SPIRE workload identity, deploy -Directory into a Kubernetes cluster using Helm or GitOps. See -[Kubernetes Deployment](dir-deployment-kubernetes.md) for the full walkthrough. - -## 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 -[MCP Server documentation](directory-mcp.md) for more information. - -## Next Steps - -- Connect to the public Directory: federate with the public Directory network - at `prod.api.ads.outshift.io` to discover and publish agents. See - [Running a Federated Directory Instance](partner-prod-federation.md). -- Enable external authenticated access for users or automation with OIDC. See - [OIDC Authentication for Directory](directory-oidc-authentication.md). -- Use the [Directory CLI](directory-cli.md) to create and query records. -- Explore [Features and Usage Scenarios](scenarios.md): build, store, sign, - discover, search. +- [Local Deployment](dir-deployment-local.md) +- [Kubernetes Deployment](dir-deployment-kubernetes.md) +- [Production Deployment](prod-deployment.md) +- [Federation](federation-overview.md) diff --git a/docs/dir/overview.md b/docs/dir/dir-overview.md similarity index 93% rename from docs/dir/overview.md rename to docs/dir/dir-overview.md index 39a1532..907bdcb 100644 --- a/docs/dir/overview.md +++ b/docs/dir/dir-overview.md @@ -26,6 +26,8 @@ leveraged for content routing in the distributed network of directory servers. The ADS specification is under active development and is published as an Internet Draft at [ADS Spec](https://spec.dir.agntcy.org). The source code is available in the [ADS Spec sources](https://github.com/agntcy/dir-spec). +Directory gRPC APIs and protobuf definitions are published on +[buf.build/agntcy/dir](https://buf.build/agntcy/dir). The current reference implementation, written in Go, provides server and client nodes with gRPC and protocol buffer interfaces. The directory record storage is built on [ORAS](https://oras.land) (OCI Registry As Storage), while data @@ -62,7 +64,7 @@ ADS leverages [Content Identifiers](https://github.com/multiformats/cid) for naming directory records. CIDs provide a self-describing, content-addressed naming scheme that ensures data integrity and immutability. -In addition to CID-based addressing, ADS supports verifiable domain-based names that enable human-readable references while maintaining cryptographic verification. See the [Directory CLI documentation](directory-cli.md#name-verification) for details. +In addition to CID-based addressing, ADS supports verifiable domain-based names that enable human-readable references while maintaining cryptographic verification. See [Features and Usage Scenarios — Name Verification](scenarios.md#name-verification) and the [CLI Reference](directory-cli-reference.md#security-verification) for details. ## Content Routing @@ -139,7 +141,7 @@ sequenceDiagram Ready to get started? Choose your path: -- Run a local instance: get Directory running locally in seconds or deploy in a Kind cluster. See [Getting Started](dir-getting-started.md). +- Run a local instance: follow the [Quickstart](quickstart.md) or see [Local Deployment](dir-deployment-local.md) and [Kubernetes Deployment](dir-deployment-kubernetes.md). - Configure external user or automation access with OIDC: see [OIDC Authentication for Directory](directory-oidc-authentication.md). - Connect to the public Directory: use the existing network at `prod.api.ads.outshift.io` to discover and publish agents. See [Running a Federated Directory Instance](partner-prod-federation.md). - Deploy for production: run your own Directory instance on AWS EKS and optionally federate with the network. See [Production Deployment](prod-deployment.md). diff --git a/docs/dir/prod-deployment.md b/docs/dir/dir-prod-deployment.md similarity index 96% rename from docs/dir/prod-deployment.md rename to docs/dir/dir-prod-deployment.md index b0052af..5866d28 100644 --- a/docs/dir/prod-deployment.md +++ b/docs/dir/dir-prod-deployment.md @@ -1,6 +1,6 @@ # Production Deployment -This guide documents production deployment of Directory on AWS EKS. For a single opinionated AWS walkthrough that carries the deployment all the way into public federation, see [Federation on Amazon EKS](federation-aws-eks.md). For local development and testing with Kind, see [Getting Started](dir-getting-started.md). For connecting to the public Directory network or federating your instance, see [Running a Federated Directory Instance](partner-prod-federation.md). +This guide documents production deployment of Directory on AWS EKS. For a single opinionated AWS walkthrough that carries the deployment all the way into public federation, see [Federation on Amazon EKS](federation-aws-eks.md). For local development and testing, see [Quickstart](quickstart.md) and [Local Deployment](dir-deployment-local.md). For connecting to the public Directory network or federating your instance, see [Federation](federation-overview.md) and [Running a Federated Directory Instance](partner-prod-federation.md). !!! important "Trust Domain Selection" Choose your **trust domain** carefully before deployment—it cannot be changed later. A trust domain is a permanent identifier for your SPIRE deployment (e.g., `acme.com`, `engineering.acme.com`). diff --git a/docs/dir/dir-quickstart.md b/docs/dir/dir-quickstart.md new file mode 100644 index 0000000..f2203b7 --- /dev/null +++ b/docs/dir/dir-quickstart.md @@ -0,0 +1,131 @@ +# Quickstart + +Get from zero to publishing and discovering an agent record in a few minutes. This is the +only page on the docs site with CLI installation instructions. + +## Install the CLI + +=== "Homebrew" + + ```bash + brew tap agntcy/dir https://github.com/agntcy/dir/ + brew install dirctl + ``` + +=== "Release binaries" + + ```bash + curl -L https://github.com/agntcy/dir/releases/latest/download/dirctl-linux-amd64 -o dirctl + chmod +x dirctl + sudo mv dirctl /usr/local/bin/ + ``` + +=== "Source" + + ```bash + git clone https://github.com/agntcy/dir + cd dir + task cli:compile + ``` + +=== "Container" + + ```bash + docker pull ghcr.io/agntcy/dir-ctl:latest + docker run --rm ghcr.io/agntcy/dir-ctl:latest --help + ``` + +## Start a local Directory + +The built-in daemon runs a full local Directory with no external dependencies: + +```bash +dirctl daemon start +``` + +This listens on `localhost:8888` and stores state under `~/.agntcy/dir/`. See +[Local Deployment](dir-deployment-local.md) for configuration, Docker Compose, and platform +details. + +For Kubernetes or production-style deployments, see [Deploy](dir-deployment-kubernetes.md) +guides instead of the daemon. + +## Publish a record + +1. Create a minimal OASF record (or use the + [OASF Record Sample generator](https://schema.oasf.outshift.com/sample/objects/record)): + + ```bash + cat <<'EOF' > record.json + { + "name": "https://example.com/agents/quickstart-agent", + "version": "v1.0.0", + "description": "Quickstart example agent", + "schema_version": "1.0.0", + "skills": [ + { + "id": 201, + "name": "images_computer_vision/image_segmentation" + } + ], + "authors": ["Quickstart"], + "created_at": "2025-08-11T16:20:37.159072Z", + "locators": [ + { + "type": "source_code", + "urls": ["https://github.com/agntcy/oasf/blob/main/record"] + } + ] + } + EOF + ``` + +1. Store the record locally and capture its CID: + + ```bash + CID=$(dirctl push record.json --output raw) + echo "Stored: $CID" + ``` + +1. Announce it on the network for discovery: + + ```bash + dirctl routing publish "$CID" + ``` + +## Discover records + +Search the network by skill, then pull a result: + +```bash +dirctl routing search --skill "images_computer_vision" --limit 5 +dirctl pull "$CID" +``` + +For local-only listings, use `dirctl routing list`. See +[Features and Usage Scenarios](scenarios.md) for signing, sync, import, export, and other +workflows. + +## Authenticate to a remote Directory + +For production or federated gateways, log in with OIDC before using remote servers: + +```bash +dirctl auth login \ + --oidc-issuer "https://prod.idp.ads.outshift.io" \ + --oidc-client-id "dirctl" +``` + +See [OIDC Authentication](directory-oidc-authentication.md) for the auth model and +[CLI Reference](directory-cli-reference.md#global-options) for command details. + +## Next steps + +- [Features and Usage Scenarios](scenarios.md) — capability tour and CLI workflows +- [Architecture](architecture.md) — how Directory fits together +- [Local](dir-deployment-local.md) / [Kubernetes](dir-deployment-kubernetes.md) / + [Production](prod-deployment.md) deployment +- [Federation](federation-overview.md) — join or run a federated network +- [SDKs](directory-sdk.md) — Go, Python, and JavaScript clients +- [CLI Reference](directory-cli-reference.md) — full `dirctl` command reference +- [API Reference](dir-api-reference.md) — gRPC/protobuf protocol surface diff --git a/docs/dir/directory-sdk.md b/docs/dir/dir-sdk.md similarity index 82% rename from docs/dir/directory-sdk.md rename to docs/dir/dir-sdk.md index e9eccd9..16ced0f 100644 --- a/docs/dir/directory-sdk.md +++ b/docs/dir/dir-sdk.md @@ -1,6 +1,22 @@ # Directory SDK -The Directory SDK provides comprehensive libraries and tools for interacting with the Directory system, including storage, routing, search, and security operations. +Libraries for interacting with Directory over gRPC: push records to the store, publish for +routing, and search or pull by skill. All three SDKs target the same workflow; pick the +language that fits your stack. + +## Publish and discover (all SDKs) + +After pointing the client at a running Directory (`localhost:8888` for the local daemon): + +1. **Push** an OASF record JSON to obtain a CID. +2. **Publish** the CID to the routing layer for network discovery. +3. **Search** by skill and **pull** matching records. + +Use [Quickstart](quickstart.md) to run `dirctl daemon start` locally. Remote servers require +[OIDC](directory-oidc-authentication.md) or SPIFFE configuration per SDK docs below. + +Protocol definitions: [buf.build/agntcy/dir](https://buf.build/agntcy/dir) and +[API Reference](dir-api-reference.md). ## JavaScript SDK diff --git a/docs/dir/validation.md b/docs/dir/dir-validation.md similarity index 100% rename from docs/dir/validation.md rename to docs/dir/dir-validation.md diff --git a/docs/dir/directory-cli.md b/docs/dir/directory-cli.md deleted file mode 100644 index 41eaa7c..0000000 --- a/docs/dir/directory-cli.md +++ /dev/null @@ -1,668 +0,0 @@ -# Directory CLI Guide - -The Directory CLI (`dirctl`) provides comprehensive command-line tools for interacting with the Directory system, including storage, routing, search, and security operations. - -This guide provides an overview of how to get started with the CLI, how to use its features, as well as common workflows and usage examples. - -For detailed reference information, see the [Directory CLI Reference](directory-cli-reference.md). - -## Installation - -The Directory CLI can be installed in the following ways: - -=== "Using Homebrew" - - ```bash - brew tap agntcy/dir https://github.com/agntcy/dir/ - brew install dirctl - ``` - -=== "Using Release Binaries" - - ```bash - # Download from GitHub Releases - curl -L https://github.com/agntcy/dir/releases/latest/download/dirctl-linux-amd64 -o dirctl - chmod +x dirctl - sudo mv dirctl /usr/local/bin/ - ``` - -=== "Using Source" - - ```bash - git clone https://github.com/agntcy/dir - cd dir - task cli:compile - ``` - -=== "Using Container Image" - - ```bash - docker pull ghcr.io/agntcy/dir-ctl:latest - docker run --rm ghcr.io/agntcy/dir-ctl:latest --help - ``` - -## Quick Start - -### Local Daemon (No External Dependencies) - -The fastest way to get a fully functional local directory is to run the built-in daemon: - -```bash -# Start the daemon (runs apiserver + reconciler in one process) -dirctl daemon start - -# Or start with a custom config file -dirctl daemon start --config /path/to/config.yaml -``` - -This starts a gRPC server on `localhost:8888` with embedded SQLite and a filesystem OCI store. All data is stored under `~/.agntcy/dir/` by default. No PostgreSQL, Docker, or external registry required. Without `--config`, built-in defaults are used; when provided, the file is read as the complete configuration. - -Once the daemon is running, use any `dirctl` command against it: - -```bash -dirctl --server-addr localhost:8888 push my-agent.json -``` - -To stop the daemon: - -```bash -dirctl daemon stop -``` - -### Using an Existing Server - -The following example demonstrates how to store, publish, search, and retrieve a record using the Directory CLI: - -1. Store a record - - ```bash - dirctl push my-agent.json - ``` - - Returns: `baeareihdr6t7s6sr2q4zo456sza66eewqc7huzatyfgvoupaqyjw23ilvi` - -1. Publish for network discovery - - ```bash - dirctl routing publish baeareihdr6t7s6sr2q4zo456sza66eewqc7huzatyfgvoupaqyjw23ilvi - ``` - -1. Search for records - - ```bash - dirctl routing search --skill "AI" --limit 10 - ``` - -1. Retrieve a record - - ```bash - # Pull by CID - dirctl pull baeareihdr6t7s6sr2q4zo456sza66eewqc7huzatyfgvoupaqyjw23ilvi - - # Or pull by name (if the record has a verifiable name) - dirctl pull cisco.com/agent:v1.0.0 - ``` - -!!! note "Name-based References" - - The CLI supports Docker-style name references in addition to CIDs. Records can be pulled using formats like `name`, `name:version`, or `name:version@cid` for hash-verified lookups. See [Name Verification](#name-verification) for details. - -!!! note "Authentication for remote Directory servers" - - When accessing a remote Directory server, authenticate first with `dirctl auth login`. For the overall auth model, IdP options, and how OIDC relates to SPIFFE/SPIRE, see [OIDC Authentication for Directory](directory-oidc-authentication.md). See [Authentication](#authentication) below for CLI command usage. - -## Common Workflows - -### Publishing Workflow - -The following workflow demonstrates how to publish a record to the network: - -1. Store your record - - ```bash - # Using --output raw for clean scripting - CID=$(dirctl push my-agent.json --output raw) - echo "Stored with CID: $CID" - ``` - -1. Publish for discovery - - ```bash - dirctl routing publish $CID - ``` - -1. Verify the record is published - - ```bash - # Use JSON output for programmatic verification - dirctl routing list --cid $CID --output json - ``` - -1. Check routing statistics - - ```bash - dirctl routing info - ``` - -### Discovery Workflow - -The following workflow demonstrates how to discover records from the network: - -1. Search for records by skill - - ```bash - # Use JSON output to process results - dirctl routing search --skill "AI" --limit 10 --output json - ``` - -1. Search with multiple criteria - - ```bash - dirctl routing search --skill "AI" --locator "docker-image" --min-score 2 --output json - ``` - -1. Pull discovered records - ```bash - # Extract CIDs and pull records - dirctl routing search --skill "AI" --output json | \ - jq -r '.[].record_ref.cid' | \ - xargs -I {} dirctl pull {} - ``` - -### Synchronization Workflow - -The following workflow demonstrates how to synchronize records between remote directories and your local instance: - -1. Create sync with remote peer - - ```bash - # Using --output raw for clean variable capture - SYNC_ID=$(dirctl sync create https://peer.example.com --output raw) - echo "Sync created with ID: $SYNC_ID" - ``` - -1. Monitor sync progress - - ```bash - # Use JSON output for programmatic monitoring - dirctl sync status $SYNC_ID --output json - ``` - -1. List all syncs - - ```bash - # Use JSONL output for streaming results - dirctl sync list --output jsonl - ``` - -1. Clean up when done - - ```bash - dirctl sync delete $SYNC_ID - ``` - -### Advanced Synchronization: Search-to-Sync Pipeline - -Automatically sync records that match specific criteria from the network: - -```bash -# Search for AI-related records and create sync operations -dirctl routing search --skill "AI" --output json | dirctl sync create --stdin - -# This creates separate sync operations for each remote peer found, -# syncing only the specific CIDs that matched your search criteria -``` - -### Import Workflow - -Import records from external registries (e.g. MCP registry) with optional signing and rate limiting: - -```bash -# 1. Preview import with dry run -dirctl import --type=mcp \ - --url=https://registry.modelcontextprotocol.io/v0.1 \ - --limit=10 \ - --dry-run - -# 2. Perform actual import with debug output -dirctl import --type=mcp \ - --url=https://registry.modelcontextprotocol.io/v0.1 \ - --filter=updated_since=2025-08-07T13:15:04.280Z \ - --debug - -# 3. Force reimport to update existing records -dirctl import --type=mcp \ - --url=https://registry.modelcontextprotocol.io/v0.1 \ - --limit=10 \ - --force - -# 4. Import with signing enabled -dirctl import --type=mcp \ - --url=https://registry.modelcontextprotocol.io/v0.1 \ - --limit=5 \ - --sign - -# 5. Import with rate limiting for LLM API calls -dirctl import --type=mcp \ - --url=https://registry.modelcontextprotocol.io/v0.1 \ - --enrich-rate-limit=5 \ - --debug - -# 6. Search imported records -dirctl search --query "module=runtime/mcp" -``` - -### Export Workflow - -Export records from the Directory into formats consumable by external tools and agentic CLIs: - -```bash -# 1. Export a single record as an A2A AgentCard -dirctl export my-agent:1.0 --format=a2a --output-file=./agent-card.json - -# 2. Export a single record as a SKILL.md for Cursor, Claude Code, etc. -dirctl export my-agent:1.0 --format=agent-skill --output-file=./SKILL.md - -# 3. Export a single record as a GitHub Copilot MCP config -dirctl export my-agent:1.0 --format=mcp-ghcopilot --output-file=./mcp.json -``` - -Batch export uses `--output-dir` with search filters to export multiple records at once. Each format handles batch output differently: - -```bash -# Batch export A2A records — one JSON file per record -dirctl export --output-dir=./exports/ --format=a2a --module "integration/a2a" -# Result: ./exports/my-agent.json, ./exports/other-agent.json, ... - -# Batch export skills — one subdirectory per skill with SKILL.md -dirctl export --output-dir=./exports/ --format=agent-skill --module "core/language_model/agentskills" -# Result: ./exports/code-review/SKILL.md, ./exports/testing/SKILL.md, ... - -# Batch export MCP servers — all merged into a single config file -dirctl export --output-dir=./exports/ --format=mcp-ghcopilot --module "integration/mcp" -# Result: ./exports/mcp.json (contains all matched servers) -``` - -!!! note - By default, when multiple versions of the same record exist, only the latest semver version is exported. Use `--all-versions` to export every version (the version is appended to the filename to avoid collisions). - -### Event Streaming Workflow - -Listen to directory events and process them (e.g. filter by type or labels): - -```bash -# Listen to all events (human-readable) -dirctl events listen - -# Stream events as JSONL for processing -dirctl events listen --output jsonl | jq -c . - -# Filter and process specific event types -dirctl events listen --types RECORD_PUSHED --output jsonl | \ - jq -c 'select(.type == "EVENT_TYPE_RECORD_PUSHED")' | \ - while read event; do - CID=$(echo "$event" | jq -r '.resource_id') - echo "New record pushed: $CID" - done - -# Monitor events with label filters -dirctl events listen --labels /skills/AI --output jsonl | \ - jq -c '.resource_id' >> ai-records.log - -# Extract just resource IDs from events -dirctl events listen --output raw | tee event-cids.txt -``` - -### Context Workflow - -Starting with Directory v1.4.0, `dirctl` can store reusable client contexts for multiple Directory endpoints. A context bundles the server address, authentication mode, OIDC settings, and TLS/SPIFFE settings that would otherwise be repeated with flags or environment variables. - -Contexts live in `~/.config/dirctl/config.yaml` by default, or under `$XDG_CONFIG_HOME/dirctl/config.yaml` when `XDG_CONFIG_HOME` is set. - -```yaml -current_context: dev -contexts: - dev: - server_address: dev.gateway.example.com:443 - auth_mode: oidc - oidc_issuer: https://dev.idp.example.com - oidc_client_id: dirctl - prod: - server_address: prod.gateway.example.com:443 - auth_mode: oidc - oidc_issuer: https://prod.idp.example.com - oidc_client_id: dirctl -``` - -Use `dirctl context` to inspect and switch the persisted active context: - -```bash -# List configured contexts; the active persisted context is marked with '*' -dirctl context list - -# Print the persisted active context -dirctl context current - -# Switch the persisted active context -dirctl context set prod - -# Show the effective context with sensitive values redacted -dirctl context show - -# Validate one or all configured contexts -dirctl context validate -dirctl context validate prod -``` - -For one command, use `--context` instead of changing `current_context`: - -```bash -dirctl --context prod search --skill "natural_language_processing" -``` - -Context values can still be overridden by environment variables or explicit root flags such as `--server-addr`, `--auth-mode`, or `--oidc-issuer`. Prefer environment variables or a secret manager for bearer tokens instead of storing long-lived `auth_token` values in the config file. - -## Output Formats - -All `dirctl` commands support multiple output formats via the `--output` (or `-o`) flag, making it easy to switch between human-readable output and machine-processable formats. - -### Available Formats - -| Format | Description | Use Case | -|--------|-------------|----------| -| `human` | Human-readable, formatted output with colors and tables (default) | Interactive terminal use | -| `json` | Pretty-printed JSON with indentation | Debugging, single-record processing | -| `jsonl` | Newline-delimited JSON (compact, one object per line) | Streaming, batch processing, logging | -| `raw` | Raw values only (e.g., CIDs, IDs) | Shell scripting, piping to other commands | - -### Usage - -```bash -# Human-readable output (default) -dirctl routing list - -# JSON output (pretty-printed) -dirctl routing list --output json -dirctl routing list -o json - -# JSONL output (streaming-friendly) -dirctl events listen --output jsonl - -# Raw output (just values) -dirctl push my-agent.json --output raw -``` - -### Piping and Processing - -Structured formats (`json`, `jsonl`, `raw`) automatically route data to **stdout** and metadata messages to **stderr**, enabling clean piping to tools like `jq`: - -```bash -# Process JSON output with jq -dirctl routing search --skill "AI" -o json | jq '.[] | .cid' - -# Stream events and filter by type -dirctl events listen -o jsonl | jq -c 'select(.type == "EVENT_TYPE_RECORD_PUSHED")' - -# Capture CID for scripting -CID=$(dirctl push my-agent.json -o raw) -echo "Stored with CID: $CID" - -# Chain commands -dirctl routing list -o json | jq -r '.[].cid' | xargs -I {} dirctl pull {} -``` - -### Format Selection Guidelines - -- **`human`**: Default for terminal interaction, provides context and formatting -- **`json`**: Best for debugging or when you need readable structured data -- **`jsonl`**: Ideal for streaming events, logs, or processing large result sets line-by-line -- **`raw`**: Perfect for shell scripts and command chaining where you only need the value - -## Authentication - -Authentication is required when accessing remote Directory servers. This section focuses on how `dirctl` authenticates and how to use the relevant CLI commands. - -For the broader model, including `Envoy` and `ext_authz`, IdP-agnostic OIDC support, Dex as an optional broker, and how external OIDC access differs from internal SPIFFE/SPIRE trust, see [OIDC Authentication for Directory](directory-oidc-authentication.md). - -| Command | Description | -|---------|-------------| -| `dirctl auth login` | Authenticate via OIDC (browser PKCE, headless, or device flow) | -| `dirctl auth logout` | Clear cached authentication credentials | -| `dirctl auth status` | Show current authentication status | - -### OIDC Authentication - -OIDC is the default authentication model for remote Directory access. The main CLI usage patterns are: - -- **Interactive login** (PKCE) via `dirctl auth login` -- **Headless login** via `dirctl auth login --no-browser` -- **Device flow** via `dirctl auth login --device` (no browser needed on this machine) -- **Pre-issued token** via `--auth-token` / `DIRECTORY_CLIENT_AUTH_TOKEN` (CI, scripts, service users) - -#### Interactive login (`dirctl auth login`) - -Authenticate as a human user using OIDC Authorization Code + PKCE. - -```bash -# Using flags -dirctl auth login \ - --oidc-issuer "https://prod.idp.ads.outshift.io" \ - --oidc-client-id "dirctl" - -# Or using environment variables -export DIRECTORY_CLIENT_OIDC_ISSUER="https://prod.idp.ads.outshift.io" -export DIRECTORY_CLIENT_OIDC_CLIENT_ID="dirctl" -dirctl auth login -``` - -What happens: - -1. The CLI opens browser-based login against your OIDC issuer -2. You authenticate with your credentials -3. The CLI caches the token at `~/.config/dirctl/auth-token.json` -4. Subsequent commands can reuse the cached token (auto-detect or `--auth-mode=oidc`) - -```bash -# Force re-login even if already authenticated -dirctl auth login --force - -# Headless: show URL only, do not open browser automatically -dirctl auth login --no-browser -``` - -#### Device flow login (`dirctl auth login --device`) - -Authenticate without a browser on the current machine. Useful for SSH sessions, containers, or remote servers. - -```bash -dirctl auth login --device \ - --oidc-issuer "https://prod.idp.ads.outshift.io" \ - --oidc-client-id "dirctl" -``` - -The same environment variables from interactive login apply (`DIRECTORY_CLIENT_OIDC_ISSUER`, `DIRECTORY_CLIENT_OIDC_CLIENT_ID`). - -What happens: - -1. The CLI displays a code and a URL -2. You open the URL on any device (phone, another computer) and enter the code -3. You authenticate with your credentials -4. The CLI polls until authorization completes, then caches the token - -#### `dirctl auth status` - -Check your current authentication status. - -```bash -dirctl auth status -``` - -Example output: - -``` -Status: Authenticated - Provider: oidc - Subject: johndoe - Issuer: https://prod.idp.ads.outshift.io - Email: johndoe@example.com - Principal type: human - Cached at: 2026-01-15T10:30:00+00:00 - Token: Valid ✓ - Expires: 2026-01-15T11:30:00+00:00 - Cache file: /home/johndoe/.config/dirctl/auth-token.json -``` - -#### `dirctl auth logout` - -Clear cached authentication credentials. - -```bash -dirctl auth logout -``` - -#### Using Authenticated Commands - -Once authenticated, cached credentials are automatically detected and used: - -```bash -# Push to remote Directory server (auto-detects and uses cached OIDC credentials) -dirctl push my-agent.json - -# Search remote Directory server (auto-detects authentication) -dirctl --server-addr=prod.gateway.ads.outshift.io:443 search --skill "natural_language_processing" - -# Pull from remote Directory server (auto-detects authentication) -dirctl pull baeareihdr6t7s6sr2q4zo456sza66eewqc7huzatyfgvoupaqyjw23ilvi -``` - -**Authentication mode behavior:** - -- **No `--auth-mode` flag (default)**: Auto-detects authentication in this order: SPIFFE (if available in Kubernetes/SPIRE environment), OIDC (explicit token or cached token), then insecure (for local development). -- **Explicit `--auth-mode=oidc`**: Forces OIDC authentication. -- **Other modes**: Use `--auth-mode=x509`, `--auth-mode=jwt`, or `--auth-mode=tls` for specific authentication methods. - -```bash -# Force OIDC auth even if SPIFFE is available -dirctl --auth-mode=oidc push my-agent.json -``` - -#### Choosing the Gateway Endpoint - -With `oidc-gateway` v1.1.1, operators may expose two hostnames from one gateway deployment: - -- an OIDC/JWT hostname (`ingress.oidc`) for `--auth-mode=oidc`, `--auth-mode=jwt`, cached OIDC login, pre-issued OIDC tokens, and GitHub Actions OIDC tokens -- an mTLS hostname (`ingress.mtls`) for `--auth-mode=x509` or `--auth-mode=tls`, where the gateway must see the client certificate - -Use the hostname that matches the credential you send. Bearer JWT traffic should target the OIDC/JWT endpoint; X.509-SVID mTLS traffic should target the mTLS endpoint. In v1.1.1, the downstream mTLS listener advertises HTTP/2 (`h2`) with ALPN so modern gRPC clients can complete the TLS handshake. - -```bash -# OIDC/JWT endpoint: Envoy validates the bearer token with jwt_authn -dirctl --server-addr "prod.gateway.ads.outshift.io:443" \ - --auth-mode=oidc \ - search --skill "natural_language_processing" - -# mTLS endpoint: Envoy validates the client certificate and ext_authz authorizes the SPIFFE principal -dirctl --server-addr "prod.gateway-mtls.ads.outshift.io:443" \ - --auth-mode=x509 \ - search --skill "natural_language_processing" -``` - -#### Pre-issued Tokens (CI and Service Users) - -For CI/CD pipelines and automation, pass a pre-issued JWT token directly: - -```bash -# GitHub Actions OIDC -dirctl search --name "*" \ - --server-addr "prod.gateway.ads.outshift.io:443" \ - --auth-mode=oidc \ - --auth-token "" \ - --output json - -# Service user with pre-generated token -export DIRECTORY_CLIENT_AUTH_TOKEN="" -export DIRECTORY_CLIENT_SERVER_ADDRESS="prod.gateway.ads.outshift.io:443" -dirctl search --auth-mode=oidc -``` - -### Other Authentication Modes - -| Mode | Description | Use Case | -|------|-------------|----------| -| `oidc` | OIDC bearer/JWT auth | Human login, pre-issued tokens, and CI workload identity | -| `x509` | SPIFFE X.509 certificates | Kubernetes workloads with SPIRE | -| `jwt` | SPIFFE JWT tokens | Service-to-service authentication | -| `token` | SPIFFE token file | Pre-provisioned credentials | -| `tls` | mTLS with certificates | Custom PKI environments | -| `insecure` / `none` | No auth, skip auto-detect | Testing, local development | -| (empty) | Auto-detect: SPIFFE → OIDC → insecure | Default behavior (recommended) | - -## Configuration - -### Server Connection - -```bash -# Connect to specific server -dirctl --server-addr localhost:8888 routing list - -# Use environment variable -export DIRECTORY_CLIENT_SERVER_ADDRESS=localhost:8888 -dirctl routing list - -# Use a reusable client context -dirctl --context dev routing list -``` - -### Authentication - -```bash -# OIDC authentication (most common) -export DIRECTORY_CLIENT_OIDC_ISSUER="https://prod.idp.ads.outshift.io" -export DIRECTORY_CLIENT_OIDC_CLIENT_ID="dirctl" -dirctl auth login - -# Pre-issued token (CI/service users) -export DIRECTORY_CLIENT_AUTH_TOKEN="" -dirctl --auth-mode=oidc routing list - -# SPIFFE Workload API (Kubernetes) -dirctl --spiffe-socket-path /run/spire/sockets/agent.sock routing list -``` - -## Command Organization - -The CLI follows a clear service-based organization: - -- **Daemon**: Local directory server (`daemon start`, `daemon stop`, `daemon status`). -- **Auth**: OIDC authentication (`auth login`, `auth logout`, `auth status`). -- **Context**: Reusable client contexts (`context list`, `context current`, `context set`, `context show`, `context validate`). -- **Storage**: Direct record management (`push`, `pull`, `delete`, `info`). -- **Import**: Batch imports from external registries (`import`). -- **Export**: Export records to external formats (`export`). -- **Routing**: Network announcement and discovery (`routing publish`, `routing list`, `routing search`). -- **Search**: General content search (`search`). -- **Security**: Signing, verification, and validation (`sign`, `verify`, `validate`, `naming verify`). -- **Sync**: Peer synchronization (`sync`). - -Each command group provides focused functionality with consistent flag patterns and clear separation of concerns. - -## Getting Help - -Use the following commands to get help with the CLI: - -- General help - ```bash - dirctl --help - ``` - -- Command group help - ```bash - dirctl routing --help - ``` - -- Specific command help - ```bash - dirctl routing search --help - ``` - -For more advanced usage, troubleshooting, and development workflows, see the [AGNTCY documentation](https://docs.agntcy.org/dir/overview/). diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index b15cef0..eb8d63e 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -53,8 +53,10 @@ plugins: redirects: redirect_maps: 'how-to-guides/identity-quickstart/index.md': 'identity/identity-quickstart.md' - 'how-to-guides/agent-directory/index.md': 'dir/dir-getting-started.md' - 'dir/getting-started.md': 'dir/dir-getting-started.md' + 'how-to-guides/agent-directory/index.md': 'dir/quickstart.md' + 'dir/getting-started.md': 'dir/quickstart.md' + 'dir/dir-getting-started.md': 'dir/quickstart.md' + 'dir/directory-cli.md': 'dir/directory-cli-reference.md' 'messaging/slim-core.md': 'slim/overview.md' 'messaging/slim-a2a.md': 'slim/slim-a2a.md' 'messaging/slim-authentication.md': 'slim/slim-authentication.md' From 97760ce88970b29b7c5a1868501c35d0a1cd26e5 Mon Sep 17 00:00:00 2001 From: Aron Kerekes Date: Thu, 21 May 2026 19:23:07 +0200 Subject: [PATCH 2/3] chore: updatind filenames Signed-off-by: Aron Kerekes --- docs/csit/csit.md | 2 +- docs/dir/.index | 42 +++++++++---------- docs/dir/dir-api-reference.md | 30 ++++++++++++- docs/dir/dir-architecture.md | 17 ++++++++ docs/dir/dir-cli-guide.md | 6 +-- docs/dir/dir-cli-reference.md | 6 +-- docs/dir/dir-component-event-streaming.md | 6 +-- docs/dir/dir-component-oidc-authentication.md | 12 +++--- docs/dir/dir-component-records-validation.md | 2 +- docs/dir/dir-component-routing.md | 10 ++--- docs/dir/dir-component-runtime-discovery.md | 2 +- docs/dir/dir-component-store.md | 8 ++-- docs/dir/dir-component-trust-model.md | 10 ++--- docs/dir/dir-deployment-kubernetes.md | 4 +- docs/dir/dir-features-scenarios.md | 6 +-- docs/dir/dir-federation-aws-eks.md | 12 +++--- docs/dir/dir-federation-overview.md | 18 ++++---- docs/dir/dir-federation-profiles.md | 2 +- docs/dir/dir-federation-setup.md | 10 ++--- docs/dir/dir-federation-troubleshooting.md | 4 +- docs/dir/dir-getting-started.md | 6 +-- docs/dir/dir-overview.md | 10 ++--- docs/dir/dir-prod-deployment.md | 10 ++--- docs/dir/dir-quickstart.md | 18 ++++---- docs/dir/dir-sdk.md | 4 +- docs/identity/arch_diagrams.md | 2 +- docs/index.md | 2 +- mkdocs/mkdocs.yml | 31 ++++++++++++-- 28 files changed, 179 insertions(+), 113 deletions(-) diff --git a/docs/csit/csit.md b/docs/csit/csit.md index 8230575..d5eaaaa 100644 --- a/docs/csit/csit.md +++ b/docs/csit/csit.md @@ -1,6 +1,6 @@ # Continuous System Integration Testing -The Agncty Continuous System Integration Testing (CSIT) system design needs to meet the continuously expanding requirements of Agntcy projects, such as the [Agent Directory Service](../dir/overview.md). +The Agncty Continuous System Integration Testing (CSIT) system design needs to meet the continuously expanding requirements of Agntcy projects, such as the [Agent Directory Service](../dir/dir-overview.md). Tests can be run locally using taskfile or in GitHub Actions. diff --git a/docs/dir/.index b/docs/dir/.index index 210a7c0..7bb06cf 100644 --- a/docs/dir/.index +++ b/docs/dir/.index @@ -1,32 +1,32 @@ nav: - Get Started: - - Overview: overview.md - - Features and Usage Scenarios: scenarios.md - - Quickstart: quickstart.md + - Overview: dir-overview.md + - Features and Usage Scenarios: dir-features-scenarios.md + - Quickstart: dir-quickstart.md - Concepts: - - Architecture: architecture.md - - Records: records-validation.md - - Store: store.md - - Routing: routing.md - - Trust Model: trust-model.md - - Federation: federation-overview.md + - Architecture: dir-architecture.md + - Records: dir-component-records-validation.md + - Store: dir-component-store.md + - Routing: dir-component-routing.md + - Trust Model: dir-component-trust-model.md + - Federation: dir-federation-overview.md - Extensions: - - Runtime Discovery: runtime.md - - Event Streaming: events.md - - MCP Server: directory-mcp.md - - GUI: directory-gui.md + - Runtime Discovery: dir-component-runtime-discovery.md + - Event Streaming: dir-component-event-streaming.md + - MCP Server: dir-component-mcp-server.md + - GUI: dir-component-gui.md - Deploy: - Local Deployment: dir-deployment-local.md - Kubernetes Deployment: dir-deployment-kubernetes.md - - Production Deployment: prod-deployment.md + - Production Deployment: dir-prod-deployment.md - Federation Deployment: - - Federation on Amazon EKS: federation-aws-eks.md - - Running a Federated Directory Instance: partner-prod-federation.md - - Profiles: federation-profiles.md - - Best Practices and Troubleshooting: federation-troubleshooting.md - - OIDC Authentication: directory-oidc-authentication.md + - Federation on Amazon EKS: dir-federation-aws-eks.md + - Running a Federated Directory Instance: dir-federation-setup.md + - Profiles: dir-federation-profiles.md + - Best Practices and Troubleshooting: dir-federation-troubleshooting.md + - OIDC Authentication: dir-component-oidc-authentication.md - SDKs: - - SDK Overview: directory-sdk.md + - SDK Overview: dir-sdk.md - Reference: - - CLI Reference: directory-cli-reference.md + - CLI Reference: dir-cli-reference.md - API Reference: dir-api-reference.md diff --git a/docs/dir/dir-api-reference.md b/docs/dir/dir-api-reference.md index 06cdb45..8b541c0 100644 --- a/docs/dir/dir-api-reference.md +++ b/docs/dir/dir-api-reference.md @@ -1,2 +1,28 @@ -# Directory API Reference -The Directory API reference is available at [buf.build/agntcy/dir](https://buf.build/agntcy/dir). +# API Reference + +Directory exposes a **gRPC** API defined with Protocol Buffers. Generated clients and the +canonical schema live on [buf.build/agntcy/dir](https://buf.build/agntcy/dir). + +## Protocol surface + +| Area | Description | +|------|-------------| +| **Storage** | Push, pull, and manage OASF records in the OCI-backed store | +| **Routing** | Publish skill announcements, list local records, search the network | +| **Search** | Structured queries over the local index | +| **Security** | Signing, verification, naming, and validation | +| **Sync** | Peer synchronization between directory instances | +| **Events** | Streaming directory events ([Events API](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1)) | +| **Runtime** | Runtime discovery for containerized workloads | + +Use the Buf schema browser for message types, RPC names, and versioned packages. The +[Architecture](dir-architecture.md) page describes how these APIs map to Directory components. + +## Clients + +- **CLI** — [Directory CLI Reference](dir-cli-reference.md) (`dirctl`) +- **SDKs** — [Go, Python, and JavaScript](dir-sdk.md) libraries +- **MCP** — [MCP Server](dir-component-mcp-server.md) for tool-based access + +For HTTP/gateway access patterns and OIDC, see +[OIDC Authentication](dir-component-oidc-authentication.md). diff --git a/docs/dir/dir-architecture.md b/docs/dir/dir-architecture.md index d00facf..445e8c6 100644 --- a/docs/dir/dir-architecture.md +++ b/docs/dir/dir-architecture.md @@ -2,6 +2,10 @@ The architecture of the Agent Directory Service (ADS) is designed to support a scalable, secure, and efficient way to manage and distribute agent directory records across a distributed network of servers. +Directory’s gRPC APIs and protobuf schemas are published on +[buf.build/agntcy/dir](https://buf.build/agntcy/dir). See the [API Reference](dir-api-reference.md) +for an overview of the protocol surface. + ## Components - **Records**: The fundamental units of information in the ADS, representing individual agents and their capabilities. Each record is uniquely identified and contains metadata describing the agent's skills, attributes, and constraints. @@ -20,6 +24,19 @@ The architecture of the Agent Directory Service (ADS) is designed to support a s - **Security and Trust Mechanisms**: Features that ensure the integrity and authenticity of directory records and nodes, including cryptographic signing, verification of claims, secure communication protocols, and access controls. +### Core vs extensions + +Per the [Directory specification](https://github.com/agntcy/dir-spec), **Records**, **Store**, and +**Routing** are the defining core components. They are documented at depth in +[Records](dir-component-records-validation.md), [Store](dir-component-store.md), and +[Routing](dir-component-routing.md). + +Optional **extensions** include +[Runtime Discovery](dir-component-runtime-discovery.md), +[Event Streaming](dir-component-event-streaming.md), the +[MCP Server](dir-component-mcp-server.md), and the [GUI](dir-component-gui.md). External access +via [OIDC](dir-component-oidc-authentication.md) is configured at deployment time. + ## Principles - **Scalability**: The ADS is designed to handle a large number of servers and records, with the ability to scale horizontally by adding more directory servers to the network. diff --git a/docs/dir/dir-cli-guide.md b/docs/dir/dir-cli-guide.md index 8b2d7d3..f4f3fbf 100644 --- a/docs/dir/dir-cli-guide.md +++ b/docs/dir/dir-cli-guide.md @@ -2,6 +2,6 @@ The CLI guide has been reorganized: -- **Installation and first publish/discover flow** — [Quickstart](quickstart.md) -- **Workflow examples** (sync, import, export, events) — [Features and Usage Scenarios](scenarios.md) -- **Command reference** — [Directory CLI Reference](directory-cli-reference.md) +- **Installation and first publish/discover flow** — [Quickstart](dir-quickstart.md) +- **Workflow examples** (sync, import, export, events) — [Features and Usage Scenarios](dir-features-scenarios.md) +- **Command reference** — [Directory CLI Reference](dir-cli-reference.md) diff --git a/docs/dir/dir-cli-reference.md b/docs/dir/dir-cli-reference.md index a4832b1..cfacd82 100644 --- a/docs/dir/dir-cli-reference.md +++ b/docs/dir/dir-cli-reference.md @@ -1,7 +1,7 @@ # Directory CLI Command Reference -Command-line reference for `dirctl`. Install the CLI in the [Quickstart](quickstart.md) -only; workflow examples live in [Features and Usage Scenarios](scenarios.md). +Command-line reference for `dirctl`. Install the CLI in the [Quickstart](dir-quickstart.md) +only; workflow examples live in [Features and Usage Scenarios](dir-features-scenarios.md). ## Global options @@ -37,7 +37,7 @@ dirctl --context dev routing list # see Context Operations below For remote servers, authenticate with OIDC before running commands. The full auth model, gateway endpoints, and SPIFFE/SPIRE integration are documented in -[OIDC Authentication](directory-oidc-authentication.md). +[OIDC Authentication](dir-component-oidc-authentication.md). | Command | Description | |---------|-------------| diff --git a/docs/dir/dir-component-event-streaming.md b/docs/dir/dir-component-event-streaming.md index e163ad5..51a5056 100644 --- a/docs/dir/dir-component-event-streaming.md +++ b/docs/dir/dir-component-event-streaming.md @@ -500,6 +500,6 @@ DIRECTORY_SERVER_EVENTS_LOG_PUBLISHED_EVENTS=false ## See Also - [Events API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1) - Protocol buffer definitions and message formats -- [CLI Reference](directory-cli-reference.md) — `dirctl events listen` and related commands -- [SDK Overview](directory-sdk.md) — language-specific SDK usage -- [Quickstart](quickstart.md) — install CLI and start a local Directory +- [CLI Reference](dir-cli-reference.md) — `dirctl events listen` and related commands +- [SDK Overview](dir-sdk.md) — language-specific SDK usage +- [Quickstart](dir-quickstart.md) — install CLI and start a local Directory diff --git a/docs/dir/dir-component-oidc-authentication.md b/docs/dir/dir-component-oidc-authentication.md index 6458f94..ab8e76c 100644 --- a/docs/dir/dir-component-oidc-authentication.md +++ b/docs/dir/dir-component-oidc-authentication.md @@ -85,7 +85,7 @@ This keeps token handling and policy enforcement at the edge rather than spreadi Human users typically authenticate with `dirctl auth login`, using browser-based PKCE, headless login, or device flow. This is the best fit for operators and developers who need interactive CLI access to a remote Directory. -Use the [CLI Reference](directory-cli-reference.md#global-options) for command examples and token cache behavior. +Use the [CLI Reference](dir-cli-reference.md#global-options) for command examples and token cache behavior. ### Service Users and Non-Interactive Automation @@ -155,7 +155,7 @@ In both cases, the Directory-facing model is the same: the edge validates tokens The two main operator touchpoints are: -- [CLI Reference](directory-cli-reference.md#global-options) for `dirctl auth login`, `dirctl auth status`, `--auth-mode=oidc`, and pre-issued token usage +- [CLI Reference](dir-cli-reference.md#global-options) for `dirctl auth login`, `dirctl auth status`, `--auth-mode=oidc`, and pre-issued token usage - deployment configuration for Envoy and the `ext_authz` layer that trusts one or more issuers and maps verified identities to principals and roles When documenting or configuring this feature, it helps to think in three layers: @@ -369,7 +369,7 @@ Client identity -> Envoy validation -> `ext_authz` canonical principal mapping - ## Further Reading -- [CLI Reference](directory-cli-reference.md) for command-level usage -- [Quickstart](quickstart.md) and [Deploy](dir-deployment-local.md) for deployment entry points -- [Production Deployment](prod-deployment.md) for production topology and external endpoints -- [Running a Federated Directory Instance](partner-prod-federation.md) for network federation guidance +- [CLI Reference](dir-cli-reference.md) for command-level usage +- [Quickstart](dir-quickstart.md) and [Deploy](dir-deployment-local.md) for deployment entry points +- [Production Deployment](dir-prod-deployment.md) for production topology and external endpoints +- [Running a Federated Directory Instance](dir-federation-setup.md) for network federation guidance diff --git a/docs/dir/dir-component-records-validation.md b/docs/dir/dir-component-records-validation.md index 56f4161..2a6869b 100644 --- a/docs/dir/dir-component-records-validation.md +++ b/docs/dir/dir-component-records-validation.md @@ -21,7 +21,7 @@ Records must include a `name` field with a domain-based identifier that enables - The domain must host a JWKS file at `:///.well-known/jwks.json`. - Records signed with a private key associated with a public key present in that JWKS file can be verified as authorized by the domain. -See [Features and Usage Scenarios — Name Verification](scenarios.md#name-verification) and the [CLI Reference](directory-cli-reference.md#security-verification) for name verification workflows. +See [Features and Usage Scenarios — Name Verification](dir-features-scenarios.md#name-verification) and the [CLI Reference](dir-cli-reference.md#security-verification) for name verification workflows. ### Example Email Agent diff --git a/docs/dir/dir-component-routing.md b/docs/dir/dir-component-routing.md index f16d569..5dc631d 100644 --- a/docs/dir/dir-component-routing.md +++ b/docs/dir/dir-component-routing.md @@ -24,8 +24,8 @@ reflect cached announcements and may be stale or incomplete until peers replicat ## Related documentation -- [Architecture](architecture.md) — full system design and diagram -- [Records](records-validation.md) — skill taxonomy and record structure -- [Features and Usage Scenarios — Announce / Discover](scenarios.md#announce) — CLI walkthroughs -- [CLI Reference — Routing Operations](directory-cli-reference.md#routing-operations) — `routing publish`, `list`, `search` -- [Federation](federation-overview.md) — multi-instance routing across federated directories +- [Architecture](dir-architecture.md) — full system design and diagram +- [Records](dir-component-records-validation.md) — skill taxonomy and record structure +- [Features and Usage Scenarios — Announce / Discover](dir-features-scenarios.md#announce) — CLI walkthroughs +- [CLI Reference — Routing Operations](dir-cli-reference.md#routing-operations) — `routing publish`, `list`, `search` +- [Federation](dir-federation-overview.md) — multi-instance routing across federated directories diff --git a/docs/dir/dir-component-runtime-discovery.md b/docs/dir/dir-component-runtime-discovery.md index ce3efab..e88bfc9 100644 --- a/docs/dir/dir-component-runtime-discovery.md +++ b/docs/dir/dir-component-runtime-discovery.md @@ -265,7 +265,7 @@ Discovered workloads have a `services` field that holds metadata extracted by re The OASF resolver requires Directory client configuration via environment variables. These are the same as those used by the Directory client library, e.g. `DIRECTORY_CLIENT_SERVER_ADDRESS`. -Refer to the [Directory Go SDK](./directory-sdk.md#go-sdk) for all available options. +Refer to the [Directory Go SDK](./dir-sdk.md#go-sdk) for all available options. When a workload has the configured OASF resolver label, the resolver attempts to fetch the corresponding record from Directory and validate its signature before attaching it to the workload. diff --git a/docs/dir/dir-component-store.md b/docs/dir/dir-component-store.md index a166af2..a63a0a6 100644 --- a/docs/dir/dir-component-store.md +++ b/docs/dir/dir-component-store.md @@ -19,10 +19,10 @@ Docker-style name references (`name`, `name:version`, `name:version@cid`). Directory supports OCI-compatible registries including [Zot](https://github.com/project-zot/zot) (default for local deployments), GitHub Container Registry, and Docker Hub. The server selects the backend via store configuration (see [Local Deployment](dir-deployment-local.md) and -[Production Deployment](prod-deployment.md)). +[Production Deployment](dir-prod-deployment.md)). ## Related documentation -- [Records](records-validation.md) — OASF record model, CIDs, and validation -- [Features and Usage Scenarios — Store](scenarios.md#store) — CLI examples and registry configuration -- [CLI Reference — Storage Operations](directory-cli-reference.md#storage-operations) — `push`, `pull`, `delete`, `info` +- [Records](dir-component-records-validation.md) — OASF record model, CIDs, and validation +- [Features and Usage Scenarios — Store](dir-features-scenarios.md#store) — CLI examples and registry configuration +- [CLI Reference — Storage Operations](dir-cli-reference.md#storage-operations) — `push`, `pull`, `delete`, `info` diff --git a/docs/dir/dir-component-trust-model.md b/docs/dir/dir-component-trust-model.md index b7cde23..1a6e382 100644 --- a/docs/dir/dir-component-trust-model.md +++ b/docs/dir/dir-component-trust-model.md @@ -108,7 +108,7 @@ flowchart LR - SPIRE Servers exchange bundles to establish federation - Enables secure, authenticated communication between workloads in different domains -For step-by-step federation setup with the public Directory network, see [Running a Federated Directory Instance](partner-prod-federation.md). For technical details on federation profiles (https_web vs https_spiffe), see [Federation Profiles](federation-profiles.md). +For step-by-step federation setup with the public Directory network, see [Running a Federated Directory Instance](dir-federation-setup.md). For technical details on federation profiles (https_web vs https_spiffe), see [Federation Profiles](dir-federation-profiles.md). ```mermaid flowchart TD @@ -147,11 +147,11 @@ as a standalone service, providing flexibility for different infrastructure setu - **Federation Support**: Federation is enabled to allow cross-domain trust relationships between different SPIRE deployments. If the federation is not required, it can be left disabled. -See [Running a Federated Directory Instance](partner-prod-federation.md) for configuration. +See [Running a Federated Directory Instance](dir-federation-setup.md) for configuration. - **Bundle Endpoint**: Exposes a bundle endpoint that enables federation by allowing other SPIRE servers to exchange trust bundles. -See [Federation Profiles](federation-profiles.md) for profile options (https_web, https_spiffe). +See [Federation Profiles](dir-federation-profiles.md) for profile options (https_web, https_spiffe). ```bash # Set the trust domain @@ -285,7 +285,7 @@ task test:spire:cleanup For more details, see: -- [Running a Federated Directory Instance](partner-prod-federation.md) - Connect to the public Directory network -- [Federation Profiles](federation-profiles.md) - https_web vs https_spiffe configuration +- [Running a Federated Directory Instance](dir-federation-setup.md) - Connect to the public Directory network +- [Federation Profiles](dir-federation-profiles.md) - https_web vs https_spiffe configuration - [SPIRE Documentation](https://spiffe.io/docs/latest/spiffe-about/overview/) - [SPIRE Federation Guide](https://spiffe.io/docs/latest/spire-helm-charts-hardened-advanced/federation/) diff --git a/docs/dir/dir-deployment-kubernetes.md b/docs/dir/dir-deployment-kubernetes.md index 6cb3d80..4c1b3cc 100644 --- a/docs/dir/dir-deployment-kubernetes.md +++ b/docs/dir/dir-deployment-kubernetes.md @@ -3,7 +3,7 @@ Deploy Directory with SPIRE in a Kind cluster for development and testing. Uses `example.org` as the trust domain (local only—cannot federate with the public network). For production AWS EKS deployment, see -[Production Deployment](prod-deployment.md). +[Production Deployment](dir-prod-deployment.md). ## Prerequisites @@ -295,4 +295,4 @@ The Agent Directory Service can be deployed using Helm or GitOps / Argo CD. Helm See [dir-staging](https://github.com/agntcy/dir-staging) for full configuration and customization options. !!! important "Trust domain" - This Quick Start uses `example.org` for local testing only. To federate with the public Directory network, you need a unique trust domain. See [Production Deployment](prod-deployment.md) and [Running a Federated Directory Instance](partner-prod-federation.md). + This Quick Start uses `example.org` for local testing only. To federate with the public Directory network, you need a unique trust domain. See [Production Deployment](dir-prod-deployment.md) and [Running a Federated Directory Instance](dir-federation-setup.md). diff --git a/docs/dir/dir-features-scenarios.md b/docs/dir/dir-features-scenarios.md index 1cfba58..272bc74 100644 --- a/docs/dir/dir-features-scenarios.md +++ b/docs/dir/dir-features-scenarios.md @@ -7,13 +7,13 @@ scenarios. All code snippets below are tested against the Directory `v1.0.0` rel Although the following example is shown for a CLI-based usage scenario, the same functionality can be performed using language-specific SDKs. -The Agent Directory Service is 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 [MCP Server documentation](directory-mcp.md) for more information. +The Agent Directory Service is 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 [MCP Server documentation](dir-component-mcp-server.md) for more information. ## Prerequisites The following prerequisites are required to follow the examples below: -- Directory CLI (`dirctl`) — install via [Quickstart](quickstart.md) +- Directory CLI (`dirctl`) — install via [Quickstart](dir-quickstart.md) - Running Directory API server — start with `dirctl daemon start` or see [Local Deployment](dir-deployment-local.md) / [Kubernetes Deployment](dir-deployment-kubernetes.md) @@ -653,7 +653,7 @@ dirctl export --output-dir=./exports/ --format=a2a --module "integration/a2a" ``` By default, only the latest semver version is exported; use `--all-versions` to export every -version. See [CLI Reference — Export Operations](directory-cli-reference.md#export-operations). +version. See [CLI Reference — Export Operations](dir-cli-reference.md#export-operations). ## gRPC Error Codes diff --git a/docs/dir/dir-federation-aws-eks.md b/docs/dir/dir-federation-aws-eks.md index 20a0fac..44017d8 100644 --- a/docs/dir/dir-federation-aws-eks.md +++ b/docs/dir/dir-federation-aws-eks.md @@ -17,10 +17,10 @@ It makes the following choices for you: If you want the reference material behind this guide, see the following guides: - - [Production Deployment](prod-deployment.md) - - [Running a Federated Directory Instance](partner-prod-federation.md) - - [Federation Bundle Profiles](federation-profiles.md) - - [Federation Best Practices and Troubleshooting](federation-troubleshooting.md) + - [Production Deployment](dir-prod-deployment.md) + - [Running a Federated Directory Instance](dir-federation-setup.md) + - [Federation Bundle Profiles](dir-federation-profiles.md) + - [Federation Best Practices and Troubleshooting](dir-federation-troubleshooting.md) This document is intentionally narrow. It does not try to cover GitOps, Azure, GCP, on-premises deployment, or the `https_spiffe` profile. The goal is to give first-time operators one concrete path that they can follow end to end. @@ -658,7 +658,7 @@ This guide does not try to provision the AWS infrastructure from zero in the mai # Expected: Error: record not found ``` - If you want a fuller post-deployment smoke test against your own Directory, use the CLI workflows in [Features and Usage Scenarios](scenarios.md) and the [CLI Reference](directory-cli-reference.md): + If you want a fuller post-deployment smoke test against your own Directory, use the CLI workflows in [Features and Usage Scenarios](dir-features-scenarios.md) and the [CLI Reference](dir-cli-reference.md): - `dirctl push record.json` - `dirctl info ` @@ -675,7 +675,7 @@ If you get stuck, check these first: - `Pending` PVCs: your EBS CSI setup or StorageClass defaulting is incomplete. - prod rejects your trust domain after local federation works: your `dir-staging` onboarding pull request has not been merged or rolled out yet. -For in-depth troubleshooting, see [Federation Best Practices and Troubleshooting](federation-troubleshooting.md). +For in-depth troubleshooting, see [Federation Best Practices and Troubleshooting](dir-federation-troubleshooting.md). ## Appendix: Best-Effort AWS Provisioning Notes diff --git a/docs/dir/dir-federation-overview.md b/docs/dir/dir-federation-overview.md index 63da7b8..52ae875 100644 --- a/docs/dir/dir-federation-overview.md +++ b/docs/dir/dir-federation-overview.md @@ -20,17 +20,17 @@ Federation is configured at deploy time. Choose the guide that matches your envi | Guide | Use case | |-------|----------| -| [Federation on Amazon EKS](federation-aws-eks.md) | End-to-end AWS deployment into the public network | -| [Running a Federated Directory Instance](partner-prod-federation.md) | Connect an existing instance to production federation | -| [Profiles](federation-profiles.md) | Federation profile configuration | -| [Best Practices and Troubleshooting](federation-troubleshooting.md) | Operations and debugging | +| [Federation on Amazon EKS](dir-federation-aws-eks.md) | End-to-end AWS deployment into the public network | +| [Running a Federated Directory Instance](dir-federation-setup.md) | Connect an existing instance to production federation | +| [Profiles](dir-federation-profiles.md) | Federation profile configuration | +| [Best Practices and Troubleshooting](dir-federation-troubleshooting.md) | Operations and debugging | -Also see [Production Deployment](prod-deployment.md) and -[OIDC Authentication](directory-oidc-authentication.md) for gateway and external access when +Also see [Production Deployment](dir-prod-deployment.md) and +[OIDC Authentication](dir-component-oidc-authentication.md) for gateway and external access when federating user-facing endpoints. ## Concepts -- [Trust Model](trust-model.md) — signing, verification, and SPIFFE/SPIRE identity -- [Routing](routing.md) — how skill-based discovery works within and across peers -- [Architecture](architecture.md) — Directory components and trust boundaries +- [Trust Model](dir-component-trust-model.md) — signing, verification, and SPIFFE/SPIRE identity +- [Routing](dir-component-routing.md) — how skill-based discovery works within and across peers +- [Architecture](dir-architecture.md) — Directory components and trust boundaries diff --git a/docs/dir/dir-federation-profiles.md b/docs/dir/dir-federation-profiles.md index f8a2d2b..a05596b 100644 --- a/docs/dir/dir-federation-profiles.md +++ b/docs/dir/dir-federation-profiles.md @@ -2,7 +2,7 @@ Directory supports two federation bundle profiles for secure trust bundle exchange between SPIRE servers. Each profile implements distinct security models, infrastructure requirements, and operational characteristics. This document provides technical guidance to assist in profile selection and implementation. -For step-by-step federation setup with the public Directory network, see [Running a Federated Directory Instance](partner-prod-federation.md). +For step-by-step federation setup with the public Directory network, see [Running a Federated Directory Instance](dir-federation-setup.md). ## Profile Comparison diff --git a/docs/dir/dir-federation-setup.md b/docs/dir/dir-federation-setup.md index a7640d6..1c381f0 100644 --- a/docs/dir/dir-federation-setup.md +++ b/docs/dir/dir-federation-setup.md @@ -1,6 +1,6 @@ # Running a Federated Directory Instance -This guide explains how to federate your Directory instance (`partner.io`) with the public production Directory at `prod.ads.outshift.io`. The prod instance uses the `https_web` bundle endpoint profile (Let's Encrypt, standard HTTPS). Your instance must use `https_web` as well for compatibility. If you want a single AWS EKS happy path instead of a generic federation reference, start with [Federation on Amazon EKS](federation-aws-eks.md). +This guide explains how to federate your Directory instance (`partner.io`) with the public production Directory at `prod.ads.outshift.io`. The prod instance uses the `https_web` bundle endpoint profile (Let's Encrypt, standard HTTPS). Your instance must use `https_web` as well for compatibility. If you want a single AWS EKS happy path instead of a generic federation reference, start with [Federation on Amazon EKS](dir-federation-aws-eks.md). Partnering with the Production Directory involves two trust domains. `partner.io` is your instance's trust domain and `prod.ads.outshift.io` is the production Directory's trust domain. @@ -300,11 +300,11 @@ Assumptions: ## Use Cases -See [Features and Usage Scenarios](scenarios.md) for sample applications and workflows. +See [Features and Usage Scenarios](dir-features-scenarios.md) for sample applications and workflows. ## Next Steps - Publish agents: Use `dirctl push` or the SDK to publish records to the public Directory. -- Deploy your own instance: See [Production Deployment](prod-deployment.md) for AWS EKS and federation. -- Explore scenarios: [Features and Usage Scenarios](scenarios.md) for build, store, sign, discover, and search workflows. -- Federation issues: See [Federation Best Practices and Troubleshooting](federation-troubleshooting.md) for operational guidance and common errors. +- Deploy your own instance: See [Production Deployment](dir-prod-deployment.md) for AWS EKS and federation. +- Explore scenarios: [Features and Usage Scenarios](dir-features-scenarios.md) for build, store, sign, discover, and search workflows. +- Federation issues: See [Federation Best Practices and Troubleshooting](dir-federation-troubleshooting.md) for operational guidance and common errors. diff --git a/docs/dir/dir-federation-troubleshooting.md b/docs/dir/dir-federation-troubleshooting.md index 18b5e24..f051a3b 100644 --- a/docs/dir/dir-federation-troubleshooting.md +++ b/docs/dir/dir-federation-troubleshooting.md @@ -1,6 +1,6 @@ # Federation Best Practices and Troubleshooting -This page covers operational best practices and troubleshooting for Directory federation. It applies to both [https_web and https_spiffe](federation-profiles.md#profile-comparison) profiles. For profile selection and configuration details, see [Federation Bundle Profiles](federation-profiles.md). +This page covers operational best practices and troubleshooting for Directory federation. It applies to both [https_web and https_spiffe](dir-federation-profiles.md#profile-comparison) profiles. For profile selection and configuration details, see [Federation Bundle Profiles](dir-federation-profiles.md). ## Operational Best Practices @@ -205,7 +205,7 @@ kubectl logs -n dir-spire -l app.kubernetes.io/name=server -c spire-server | \ **Root Cause:** Bootstrap bundle is missing, stale, or incorrectly formatted. -**Resolution:** Obtain a fresh bundle from your federation partner, validate it, and update `trustDomainBundle` in your federation resource. See [Bootstrap Bundle Exchange Process](federation-profiles.md#bootstrap-bundle-exchange-process-https_spiffe) for extraction and validation steps: +**Resolution:** Obtain a fresh bundle from your federation partner, validate it, and update `trustDomainBundle` in your federation resource. See [Bootstrap Bundle Exchange Process](dir-federation-profiles.md#bootstrap-bundle-exchange-process-https_spiffe) for extraction and validation steps: ```bash # Obtain fresh bundle from federation partner diff --git a/docs/dir/dir-getting-started.md b/docs/dir/dir-getting-started.md index 9b1824a..b730599 100644 --- a/docs/dir/dir-getting-started.md +++ b/docs/dir/dir-getting-started.md @@ -1,10 +1,10 @@ # Getting Started -Onboarding content has moved to [Quickstart](quickstart.md). +Onboarding content has moved to [Quickstart](dir-quickstart.md). Deployment guides: - [Local Deployment](dir-deployment-local.md) - [Kubernetes Deployment](dir-deployment-kubernetes.md) -- [Production Deployment](prod-deployment.md) -- [Federation](federation-overview.md) +- [Production Deployment](dir-prod-deployment.md) +- [Federation](dir-federation-overview.md) diff --git a/docs/dir/dir-overview.md b/docs/dir/dir-overview.md index 907bdcb..b29841b 100644 --- a/docs/dir/dir-overview.md +++ b/docs/dir/dir-overview.md @@ -64,7 +64,7 @@ ADS leverages [Content Identifiers](https://github.com/multiformats/cid) for naming directory records. CIDs provide a self-describing, content-addressed naming scheme that ensures data integrity and immutability. -In addition to CID-based addressing, ADS supports verifiable domain-based names that enable human-readable references while maintaining cryptographic verification. See [Features and Usage Scenarios — Name Verification](scenarios.md#name-verification) and the [CLI Reference](directory-cli-reference.md#security-verification) for details. +In addition to CID-based addressing, ADS supports verifiable domain-based names that enable human-readable references while maintaining cryptographic verification. See [Features and Usage Scenarios — Name Verification](dir-features-scenarios.md#name-verification) and the [CLI Reference](dir-cli-reference.md#security-verification) for details. ## Content Routing @@ -141,7 +141,7 @@ sequenceDiagram Ready to get started? Choose your path: -- Run a local instance: follow the [Quickstart](quickstart.md) or see [Local Deployment](dir-deployment-local.md) and [Kubernetes Deployment](dir-deployment-kubernetes.md). -- Configure external user or automation access with OIDC: see [OIDC Authentication for Directory](directory-oidc-authentication.md). -- Connect to the public Directory: use the existing network at `prod.api.ads.outshift.io` to discover and publish agents. See [Running a Federated Directory Instance](partner-prod-federation.md). -- Deploy for production: run your own Directory instance on AWS EKS and optionally federate with the network. See [Production Deployment](prod-deployment.md). +- Run a local instance: follow the [Quickstart](dir-quickstart.md) or see [Local Deployment](dir-deployment-local.md) and [Kubernetes Deployment](dir-deployment-kubernetes.md). +- Configure external user or automation access with OIDC: see [OIDC Authentication for Directory](dir-component-oidc-authentication.md). +- Connect to the public Directory: use the existing network at `prod.api.ads.outshift.io` to discover and publish agents. See [Running a Federated Directory Instance](dir-federation-setup.md). +- Deploy for production: run your own Directory instance on AWS EKS and optionally federate with the network. See [Production Deployment](dir-prod-deployment.md). diff --git a/docs/dir/dir-prod-deployment.md b/docs/dir/dir-prod-deployment.md index 5866d28..8b4476f 100644 --- a/docs/dir/dir-prod-deployment.md +++ b/docs/dir/dir-prod-deployment.md @@ -1,6 +1,6 @@ # Production Deployment -This guide documents production deployment of Directory on AWS EKS. For a single opinionated AWS walkthrough that carries the deployment all the way into public federation, see [Federation on Amazon EKS](federation-aws-eks.md). For local development and testing, see [Quickstart](quickstart.md) and [Local Deployment](dir-deployment-local.md). For connecting to the public Directory network or federating your instance, see [Federation](federation-overview.md) and [Running a Federated Directory Instance](partner-prod-federation.md). +This guide documents production deployment of Directory on AWS EKS. For a single opinionated AWS walkthrough that carries the deployment all the way into public federation, see [Federation on Amazon EKS](dir-federation-aws-eks.md). For local development and testing, see [Quickstart](dir-quickstart.md) and [Local Deployment](dir-deployment-local.md). For connecting to the public Directory network or federating your instance, see [Federation](dir-federation-overview.md) and [Running a Federated Directory Instance](dir-federation-setup.md). !!! important "Trust Domain Selection" Choose your **trust domain** carefully before deployment—it cannot be changed later. A trust domain is a permanent identifier for your SPIRE deployment (e.g., `acme.com`, `engineering.acme.com`). @@ -142,7 +142,7 @@ Create DNS records for your domain. Example with `your-domain.com`: | **SPIRE Federation** | spire.your-domain.com | 443 (TLS termination) | | **SPIRE OIDC** | oidc-discovery.spire.your-domain.com | 443 (TLS termination) | -If you also want authenticated access for external users, `dirctl`, or automation, pair the production deployment with the optional OIDC gateway pattern described in [OIDC Authentication for Directory](directory-oidc-authentication.md). This is separate from SPIRE OIDC discovery used for federation. +If you also want authenticated access for external users, `dirctl`, or automation, pair the production deployment with the optional OIDC gateway pattern described in [OIDC Authentication for Directory](dir-component-oidc-authentication.md). This is separate from SPIRE OIDC discovery used for federation. ## Verification @@ -218,6 +218,6 @@ kubectl rollout restart deployment/ -n Date: Thu, 21 May 2026 19:32:54 +0200 Subject: [PATCH 3/3] chore: fixing links Signed-off-by: Aron Kerekes --- docs/dir/dir-component-mcp-server.md | 2 +- docs/dir/dir-sdk.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dir/dir-component-mcp-server.md b/docs/dir/dir-component-mcp-server.md index 04cc71d..75d0a10 100644 --- a/docs/dir/dir-component-mcp-server.md +++ b/docs/dir/dir-component-mcp-server.md @@ -105,4 +105,4 @@ Using the Directory MCP Server, you can access the following tools: - `agntcy_dir_verify_record` - Verifies the digital signature of a record in the Directory by its CID (server-side integrity and authenticity). - `agntcy_dir_verify_name` - Verifies that a record's name is owned by the domain it claims (by CID or name; optional version). Checks that the record was signed with a key published in the domain's well-known JWKS file. -For a full list of tools and usage examples, see the [Directory MCP Server documentation](https://github.com/agntcy/dir/blob/main/mcp/README.md). +For a full list of tools and usage examples, see the [Directory MCP Server GitHub repository](https://github.com/agntcy/dir-mcp). diff --git a/docs/dir/dir-sdk.md b/docs/dir/dir-sdk.md index e86a084..373b709 100644 --- a/docs/dir/dir-sdk.md +++ b/docs/dir/dir-sdk.md @@ -20,7 +20,7 @@ Protocol definitions: [buf.build/agntcy/dir](https://buf.build/agntcy/dir) and ## JavaScript SDK -Documentation for the JavaScript SDK can be found on [GitHub](https://github.com/agntcy/dir/tree/main/sdk/dir-js). The SDK supports both JavaScript and TypeScript applications. The package is published on [npm](https://www.npmjs.com/package/agntcy-dir). +Documentation for the JavaScript SDK can be found on [GitHub](https://github.com/agntcy/dir-sdk-javascript). The SDK supports both JavaScript and TypeScript applications. The package is published on [npm](https://www.npmjs.com/package/agntcy-dir). !!! note @@ -73,7 +73,7 @@ const spiffeClient = new Client(config, transport); ## Python SDK -Documentation for the Python SDK can be found on [GitHub](https://github.com/agntcy/dir/tree/main/sdk/dir-py). +Documentation for the Python SDK can be found on [GitHub](https://github.com/agntcy/dir-sdk-python). The SDK supports Python 3.10+ applications. The package is published on [PyPI](https://pypi.org/project/agntcy-dir/). ### Installation