Configuration

Two JSON files, one env namespace. Every config the SDK and CLI care about lives in one of these places.

File locations

File	Used by	Purpose
<project>/agent.config.json	zynd agent run, ZyndAIAgent	Per-agent metadata, server, registry, pricing
<project>/service.config.json	zynd service run, ZyndService	Per-service metadata
<project>/.env	The agent / service runtime	API keys, runtime overrides
~/.zynd/config.json	The CLI	Default registry URL
~/.zynd/developer.json	The CLI / SDK	Developer Ed25519 keypair
~/.zynd/agents/<name>/keypair.json	The SDK	Agent's HD-derived Ed25519 keypair
~/.zynd/services/<name>/keypair.json	The SDK	Service's HD-derived Ed25519 keypair
<project>/.well-known/agent-card.json	The SDK / clients	Auto-generated signed card; rebuilt on each run

agent.config.json

Fields generated by the scaffold and read by the SDK on zynd agent run.

Field	Type	Default	Description
name	string	required	Display name; slug used in FQAN
description	string	""	Short summary published in the card
version	string	"0.1.0"	Semver
category	string	"general"	Discovery category
tags	string[]	[]	Discovery tags
registry_url	string	"https://zns01.zynd.ai"	The registry to register on
server_host	string	"0.0.0.0"	Webhook bind host
server_port	number	5000	Webhook port
auth_mode	"permissive" | "strict"	"permissive"	Inbound message signature policy
entity_index	number	auto	HD derivation index — auto-allocated by zynd agent init
skills	object[]	one default	Capability blocks; each {id, name, description, tags, examples}
entity_url	string	from runtime	Override the public URL written into the registry record
keypair_path	string	from ZYND_AGENT_KEYPAIR_PATH	Override the keypair location
entity_pricing	object	absent	x402 pricing block (see x402)
price	string	absent	Convenience alias for a per_request block (e.g. "$0.01")
fqan	string	absent	Pre-claimed FQAN if you have a handle
webhook_port	number	absent	Legacy alias for server_port — both work, prefer server_port

A complete fresh-scaffold config:

{
  "name": "my-agent",
  "description": "my-agent agent",
  "version": "0.1.0",
  "category": "general",
  "tags": [],
  "registry_url": "https://zns01.zynd.ai",
  "server_host": "0.0.0.0",
  "server_port": 5000,
  "auth_mode": "permissive",
  "entity_index": 190,
  "skills": [
    {
      "id": "default",
      "name": "my-agent",
      "description": "my-agent's primary capability — replace this with what your agent actually does.",
      "tags": [],
      "examples": []
    }
  ]
}

service.config.json

Same fields as agent.config.json plus two service-only fields:

Field	Type	Default	Description
service_endpoint	string	absent	Override the public service endpoint advertised in the card if it differs from entity_url
openapi_url	string	absent	Optional OpenAPI URL for clients that introspect

.env (project root)

The scaffold writes a minimal .env. Add API keys for the LLM (or other tools) you use.

ZYND_AGENT_KEYPAIR_PATH=/home/dillu/.zynd/agents/my-agent/keypair.json

OPENAI_API_KEY=sk-...
TAVILY_API_KEY=tvly-...

Don't commit .env

Add .env to .gitignore. The scaffold does this for you on TypeScript projects (which ship a .gitignore); on Python add the line yourself.

Environment variables

Anything the SDK or CLI reads from the environment.

Where Zynd reads from

Variable	Default	Read by	Purpose
ZYND_HOME	~/.zynd	CLI / SDK	Override the config directory
ZYND_REGISTRY_URL	https://zns01.zynd.ai	CLI / SDK	Override the registry
ZYND_AGENT_KEYPAIR_PATH	~/.zynd/agents/<name>/keypair.json	SDK	Override the agent keypair location
ZYND_SERVICE_KEYPAIR_PATH	~/.zynd/services/<name>/keypair.json	SDK	Override the service keypair location
ZYND_ENTITY_URL	bound host:port	SDK	Override the public URL written into the registry record
ZYND_SERVER_PORT	from config	SDK	Override the webhook port
ZYND_PAYMENT_NETWORK	base-sepolia	SDK	EVM network for x402 (base, base-sepolia, optimism, etc.)

What you provide

Variable	When you set it
OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.	The LLM your framework calls
TAVILY_API_KEY	If you use Tavily search as a tool
Provider-specific credentials	Whatever your tools need

~/.zynd/config.json

A small CLI-only file:

{
  "registry_url": "https://zns01.zynd.ai"
}

Used as the default --registry for every command. Override per-command with --registry <url>.

~/.zynd/developer.json

Created by zynd init or zynd auth login. Treat as a private key.

{
  "public_key": "<base64>",
  "private_key": "<base64>"
}

The CLI uses it to sign every developer-scoped action; the SDK derives agent keys from it.

~/.zynd/agents/<name>/keypair.json

Created by zynd agent init (or zynd keys derive). HD-derived from the developer key.

{
  "public_key": "<base64>",
  "private_key": "<base64>",
  "derived_from": {
    "developer_public_key": "ed25519:<base64>",
    "index": 190
  }
}

derived_from is what lets the SDK rebuild a developer_proof for POST /v1/entities.

~/.zynd/services/<name>/keypair.json

Same shape as the agent keypair, under the services namespace.

.well-known/agent-card.json

Auto-generated by zynd agent run (and zynd card build). Don't edit manually — edit agent.config.json and re-run.

{
  "_note": "Auto-generated by `zynd agent run` from agent.config.json. Do not edit manually — edit agent.config.json instead."
}

After a successful run the file fills with the signed card. See Agent Cards for the schema.

Precedence

When the SDK reads a setting, it picks the first that's defined:

1. CLI flag (where applicable, e.g., --port, --registry).
2. Environment variable (e.g., ZYND_SERVER_PORT, ZYND_REGISTRY_URL).
3. agent.config.json / service.config.json.
4. ~/.zynd/config.json (CLI only).
5. Built-in default (e.g., 5000 for the port, https://zns01.zynd.ai for the registry).

See also

• CLI Reference — every command and flag.
• Python SDK API / TypeScript SDK API — how the SDK consumes these configs.
• Identity & Cryptography — the keypair files in detail.