coral-toml-format

name	coral-toml-format
description	Use when working with coral-agent.toml files, Edition 3 TOML format, coral marketplace agent manifests, or coral agent publishing configuration

Coral Agent TOML Format (Edition 3)

Edition 3 is the required format for publishing agents to Coral Marketplace.

Complete Template

edition = 3

[agent]
name = "my-agent"
version = "1.0.0"
description = "What this agent does"
capabilities = ["resources", "tool_refreshing"]

[marketplace]
slug = "my-agent"
short_description = "Brief summary for marketplace listing"
developer = "Developer Name"
license = "MIT"
maintainer = "[e-mail]"
website = "https://github.com/user/repo"
icon_url = "https://example.com/icon.png"
pricing_description = "Pay per review based on complexity"
readme = """
# My Agent
Full readme content in markdown...
"""

[marketplace.price_per_run]
min = 0.001
max = 0.01
currency = "USD"

[marketplace.identity]
erc8004 = true
agent_wallet = "SolanaBase58Pubkey..."
endpoints = [
  { name = "api", endpoint = "https://agent.example.com/api" }
]

[options.API_KEY]
type = "string"
required = true
secret = true
transport = "env"

[options.API_KEY.display]
label = "API Key"
description = "Your API key"

[options.API_KEY.validation]
min_length = 10

[runtimes.executable]
command = ["python", "agent.py"]

[runtimes.docker]
image = "myagent:latest"
command = ["python", "-u", "agent.py"]

Required Fields

Field	Section	Notes
edition = 3	top-level	Must be exactly 3 for marketplace publishing
name	[agent]	Display name, cannot be empty
version	[agent]	Valid semver: MAJOR.MINOR.PATCH (e.g., 1.0.0, 0.1.0-beta)
slug	[marketplace]	Unique identifier (see slug rules below)
At least one runtime	[runtimes]	[runtimes.executable] and/or [runtimes.docker]

Optional Fields

Field	Section	Type	Notes
description	[agent]	string	Full description
capabilities	[agent]	string[]	MCP capabilities: resources, tools, tool_refreshing, prompts
short_description	[marketplace]	string	Brief listing text
developer	[marketplace]	string	Developer or organization name
license	[marketplace]	string	OSI license identifier (MIT, Apache-2.0, etc.)
maintainer	[marketplace]	string	Contact info
website	[marketplace]	string	Project URL
icon_url	[marketplace]	string	Agent icon URL
pricing_description	[marketplace]	string	Human-readable pricing text
readme	[marketplace]	string	Full markdown README (use triple-quoted strings)
price_per_run	[marketplace.price_per_run]	object	min (f64), max (f64), currency (string, defaults to "USD")
identity	[marketplace.identity]	object	Solana on-chain identity (planned)
erc8004	[marketplace.identity]	bool	Enable on-chain registry publishing
agent_wallet	[marketplace.identity]	string	Solana Base58 pubkey
endpoints	[marketplace.identity]	array	{ name, endpoint } objects

Slug Validation Rules

• Length: 1-32 characters (required for coral-escrow compatibility)
• Lowercase alphanumeric and hyphens only
• Must start and end with alphanumeric character
• No consecutive hyphens (--)
• Pattern: [a-z0-9]([a-z0-9-]*[a-z0-9])?

Valid: my-agent, code-reviewer-v2, translator, a1 Invalid: -agent, agent-, My-Agent, agent--v2, agent_name, test.agent

Version Format

Must be valid semantic versioning (semver):

• 1.0.0, 0.1.0, 2.3.1 (standard)
• 1.0.0-beta, 2.0.0-rc.1 (pre-release)
• NOT valid: v1.0.0 (no v prefix), 1.2 (needs patch), 1.2.3.4 (too many parts)

Options (Passthrough)

Options are stored as opaque JSON and passed through to coral-server. The marketplace does not validate option types. Common option fields:

[options.OPTION_NAME]
type = "string"          # string, bool, byte, short, int, long, float, double, blob, list
required = true          # whether the option must be provided
secret = true            # if true, value is masked in UI
default = "value"        # default value
transport = "env"        # "env" (environment variable) or "fs" (file system)

[options.OPTION_NAME.display]
label = "Display Label"
description = "Help text for this option"
group = "Authentication"

[options.OPTION_NAME.validation]
min_length = 10
max_length = 100

Runtimes

At least one runtime is required. Both can coexist:

[runtimes.executable]
command = ["python", "agent.py"]       # Command to run the agent

[runtimes.docker]
image = "myagent:latest"               # Docker image
command = ["python", "-u", "agent.py"] # Command inside container

Publishing API

Publish by POSTing raw TOML to the marketplace:

curl -X POST https://marketplace.coralprotocol.ai/api/v1/agents \
  -H "Authorization: Bearer coral_..." \
  -H "Content-Type: text/plain" \
  --data-binary @coral-agent.toml

Success response: {"slug": "my-agent", "version": "1.0.0"}