Get started with ANS.

Choose a starting point

• Explore the protocol: run the local quickstart to register an agent and verify its receipt on your machine.
• Use an existing registry: follow the CLI quickstart to install ans-cli, configure access, and manage agents from a terminal.
• Build an integration: choose an SDK or use a gateway verifier to authenticate agents in your application’s request path.

Local quickstart

The Go reference implementation includes a Registration Authority, Transparency Log, offline verifier, and development DNS server. The demo registers an agent and verifies a SCITT receipt locally.

Prerequisites: Git, Make, Go 1.26+, OpenSSL, curl, and jq. Check the reference quickstart for current requirements.

git clone https://github.com/agentnameservice/ans
cd ans
make build
scripts/demo/start.sh
scripts/demo/run-lifecycle.sh

Look for VERIFIED in the offline-verification stage. While the services are running, you can browse their API explorers:

• Registration Authority: localhost:18080/docs
• Transparency Log: localhost:18081/docs

Stop the demo afterward:

scripts/demo/stop.sh

Local development only: the default demo uses development keys and a noop DNS verifier. A passing receipt check does not test public DNS, production certificate issuance, or a live deployment. Follow the local DNS testing guide to exercise DNS validation.

Use the CLI

ans-cli provides registration, discovery, certificate management, and Transparency Log queries without writing application code. It is available for macOS, Linux, and Windows.

Start with the CLI quickstart in the Go SDK README. For installation alternatives, configuration, and command flags, see the full CLI guide.

Before registering an agent with a hosted registry, have:

• An agent domain and access to publish its required DNS records.
• The registry API URL and a credential accepted by that operator.
• Your agent’s endpoint details and any protocol metadata it publishes.
• The separate Transparency Log URL when using commands such as badge.

Configure ANS_BASE_URL and ANS_TRANSPARENCY_URL for the selected environment. Use the CLI’s documented environment-variable, token-file, or stdin support for credentials. Follow the registry’s returned DNS requirements and confirm that the registration becomes ACTIVE.

Choose your tools

• Go SDK and CLI: registry and transparency clients, verification, and command-line tools.
• Rust libraries: API clients, shared types, and verification libraries with rustls support.
• Java SDK: registration, discovery, cryptography, and agent client modules.

Use each project’s installation guide and release notes for its supported features and versions. The SDKs have different APIs and coverage.

Integrate verification

1. Choose your authority and trust roots. Configure Registration Authority and Transparency Log endpoints explicitly. Decide which log keys and identities your application trusts.
2. Register and publish. Prove control of your domain, complete the certificate workflow, publish the DNS records returned by your RA, and wait for activation.
3. Verify peers and authenticate callers. Follow the ANS-6 procedures for certificates, identity, status, and possession. Select mTLS or DPoP for your topology and your implementation’s capabilities.
4. Apply authorization. Map the authenticated identity to permitted actions. Test expiration, revocation, replay rejection, certificate rotation, and unavailable verification evidence.

Follow a working example

• Java protocol examples cover A2A, MCP, and HTTP clients and services.
• Go DPoP example demonstrates application-layer proof of possession.
• Rust MCP client demonstrates MCP over mTLS.
• Gateway authentication includes recipes for agentgateway and Agent Router.

Review each example’s configuration and coverage before deployment. For wire-level contracts, use the OpenAPI definitions and schemas.

Get help

Report reproducible problems in the relevant repository: reference implementation, CLI and Go SDK, or the SDK or integration you are using. Include the version, operating system, command or minimal example, and error message. Remove credentials and private keys before sharing logs.