Introduction

A coral-agent.toml contains all the information that the Coral server needs to orchestrate a Coral agent. You cannot have a Coral agent without a coral-agent.toml file; similar to a package.json file for a Node project. TOML is the syntax used in this configuration file.

Example

edition = 3

[agent]
name = "my-agent"
version = "0.0.1"
description = "Has access to company databases"

[runtimes.docker]
image = "myusername/myagent"

[options.OPENAI_API_KEY]
type = "string"
required = true

File format reference

edition

The current latest edition is 3

edition must be set to 3. Earlier editions are not supported in v1.1.0+.

edition = 3

The edition field is a number describing the format of the coral-agent.toml file.

Third edition

The current edition of Coral agent definitions is edition = 3. This edition is mandatory for all new agents, and versions of the Coral server from v1.1.0+ only support this edition. Changelog compared to earlier editions:

Mandatory Edition: edition = 3 is required.
Improved Types: Added support for various numeric and list types.
Removed Deprecated Types: The number and secret types are deprecated and replaced by more specific types.
Advanced Transport: Standardized the fs (file system) transport for large values.

Second edition

The second edition (edition = 2) is no longer supported in the latest version of the Coral server. Agents using this edition should be updated to edition = 3.

First edition

The first edition (edition = 1) is no longer supported. Any agent still using this edition must be updated to edition = 3 to be valid in the Coral server registry.

Migration to Edition 3

Set edition = 3 at the top of the agent definition.
For secret types, use type = "string" and add secret = true.
For number types, use type = "f64" or a more appropriate numeric type.
Move description on options to display.description.

agent

[agent]
name = "..."
version = "0.0.0"
description = "..."
capabilities = ["resources"]

Agent table, containing name, version, description and capabilities fields.

name

[agent]
name = "my name..."

Agent names are validated by the server. Requirements:

Must be 1–32 characters long
Must start with a lowercase letter a-z
May contain lowercase letters a-z, digits 0-9, and hyphens -
Kebab-case only; underscores _ and uppercase letters are not allowed

Examples of valid names: search, my-agent, agent1, my-long-agent-name Examples of invalid names: MyAgent (uppercase), my_agent (underscore), 1agent (does not start with a letter)

version

[agent]
version = "0.0.0"

The version must be a valid Semantic Version (SemVer), for example 1.2.3 or 1.2.3-beta.1. The server enforces SemVer parsing and a maximum length of 24 characters. See also version recommendations for the marketplace.

description

[agent]
description = "Access to GitHub MCP tooling"

Agents in a Coral server have descriptions that are given to other agents in the graph to identify them. This field specifies the default description for this agent in the graph. It is possible that the consumer of this agent changes the description specified here. A description is “external”, other agents in the graph use an agent’s description to identify its purpose, but the agent itself doesn’t use its description to describe itself. Do not put prompting for your agent in the description.

capabilities

The capabilities field is not yet fully implemented

[agent]
capabilities = ["resources", "tool_refreshing"]

Some features of Coral require implementation from the agent. The capabilities field is used to describe what optional features of Coral the agent supports. Supported capabilities:

resources
- The agent supports MCP resources fully. Fully supporting MCP resources requires that any given MCP resource is fetched per agent iteration
tool_refreshing
- The agent will check for new tools per iteration

runtimes

[runtimes.docker]
image = "myuser/myimage"

[runtimes.executable]
path = "./my-agent.exe"
arguments = ["--some-argument"]

[runtimes.function]
# No fields required in TOML; used for built-in/test function runtime

Runtimes specify how the Coral server should orchestrate the agent. The supported runtimes are docker, executable, and function.

docker

[runtimes.docker]
image = "myuser/myimage"
# Optional: override runtime transport (see "Runtime transport")
# transport = "streamable_http" # default

docker is the preferred runtime for an agent. The docker runtime is required for agents on the marketplace and ensures that the agent is portable.

Do not set a tag when using the docker runtime. The agent’s version will be appended to the end of the image.It is important that running an older version of your agent runs a matching older version of your agent’s Docker image.

The following example will request myuser/myimage:1.1.0 from Dockerhub:

[agent]
name = "my-agent"
version = "1.1.0"

[runtimes.docker]
image = "myuser/myimage"

Make sure you tag your images with the correct version before pushing them to Dockerhub!

executable

The executable runtime should only be used for agent testing or development.Agents with only a executable runtime defined will not be accepted into the marketplace.

[runtimes.executable]
path = "./launch"
arguments = ["my-agent"]
# Optional: override runtime transport (see "Runtime transport")
# transport = "sse" # default is "streamable_http"

The specified command will be run on the server in the same directory as the coral-agent.toml file, taking the following directory for example:

agents/
├─ my-agent/
│  ├─ coral-agent.toml
│  ├─ src/
│  │  ├─ main.py

Your executable runtime could be:

[runtimes.executable]
path = "python"
arguments = ["src/main.py"]

function

[runtimes.function]
# No additional fields

The function runtime is a server-side runtime intended for internal/debug agents and tests. It does not launch an external process; instead, the server invokes a provided function. This is not intended for marketplace agents.

Runtime transport

Agents communicate with the Coral server using MCP over HTTP. Two transport modes are supported by all runtimes:

streamable_http (default)
sse (legacy Server‑Sent Events)

Each runtime accepts an optional transport field to select the mode. If omitted, the default is streamable_http. Examples:

[runtimes.docker]
image = "myuser/myimage"
transport = "streamable_http" # default

[runtimes.executable]
path = "./launch"
arguments = ["my-agent"]
transport = "sse" # opt into SSE if your agent expects it

At launch, the server provides connection details via environment variables that your agent reads to connect back:

CORAL_CONNECTION_URL — the MCP endpoint (matches the selected transport)
CORAL_AGENT_ID, CORAL_AGENT_SECRET, CORAL_SESSION_ID
CORAL_API_URL, CORAL_RUNTIME_ID

See the Writing Agents guide for full CORAL_* variable details.

options

[options.MY_OPTION_1]
type = "string"
required = false
secret = true
default = "..."
base64 = false
transport = "env"

[options.MY_OPTION_1.display]
label = "My first option"
description = "Set this option to make my agent do something cool"
group = "My options"
multiline = false

[options.MY_OPTION_1.validation]
variants = ["value1", "value2"]
min_len = 1
max_len = 100
regex = "$value[0-9]^"

[options.MY_OPTION_2]
type = "i32"
# etc...

[options.MY_OPTION_2.display]
label = "My second option"
# etc...

[options.MY_OPTION_1.validation]
variants = [10, 20]
min = 1
max = 100

Agent options define variables that the server will set for the agent when it is orchestrated. Options allow for more generic development of agents and fine-tuning by agent consumers. Options are commonly used to:

Provide API keys for services the agent needs access to
Configure LLM parameters, for example:
- The model provider (OpenAI, Anthropic, etc)
- The model used (GPT-4, Claude 3.5, etc)
- Maximum tokens
- Hyperparameters

See here for more information on how options are sent to the agent.

type

An option type controls valid values for an option and how the option will be encoded. The type will be verified by the server. The server will never orchestrate an agent with a value for an option that is of the wrong type.

Numeric types

type	value	`transport = "env"`	`transport = "fs"`
i8	127	`127`	`0x7F`
i16	-15234	`-15234`	`0xC47E`
i32	1589473628	`1589473628`	`0x5EB8E15C`
i64	7234567890123456789	`7234567890123456789`	`0x6451780B5FE68D15`
u8	203	`203`	`0xCB`
u16	5432	`5432`	`0xD431`
u32	3141592653	`3141592653`	`0xBB40E64D`
u64	12345678901234567890	`"12345678901234567890"`	`0xAB54A98CEB1F0AD2`
f32	3.14159274	`3.14159274`	`0x40490FDB`
f64	2.718281828459045	`2.718281828459045`	`0x4005BF0A8B145769`

For JSON compatibility type = "u64" must be specified as a string, both as a default to an option in coral-agent.toml and as a value give to the Coral server.

When transport = "fs" all numeric types are written in big-endian byte order.

Other types

type	value	`transport = "env"`	`transport = "fs"`
bool	true	`1`	`0x01`
string	Hello World!	`Hello World!`	`Hello World!` (utf8)
blob	[164, 145, 163, 164]	`dGVzdA==` (base64)	`0x74657374` (raw bytes)

When transport = "fs":

Bool values will be written as a u8 byte; 1 for true and 0 for false.
A string’s base64 setting will be ignored. The string will always be written in a UTF-8 encoding

When transport = "env":

Bool values will be 1 for true and 0 for false.
String values can be passed with base64 encoding if base64 = true is set
Blob values will always be passed as base64

List types

All types except for the bool type have a matching list type, for example:

list[i32]
list[string]
list[blob]

List types will always default to an empty list. If no value is given for an option, the server will provide an empty list as a value for that option.Warnings will be generated for list types when required = true.

When transport = "fs":An environment variable will be set for this option containing a list of files, one file for every value specified.The list of paths will be separated using the operating-system-dependant path separator:

; on Windows
: on Unix-like operating systems

For example:

[options.MY_OPTION]
type = "list[string]"
transport = "env"
default = ["one", "two"]

Windows environment:

$env:MY_OPTION = "C:\path\to\file1.opt;C:\path\to\file2.opt"

Unix environment:

MY_OPTION = "/path/to/file1.opt:/path/to/file2.opt"

File content (identical on Windows and Unix):

$ cat /path/to/file1.opt
one

$ cat /path/to/file2.opt
two

When transport = "env":The values will be sent as a comma-separated list. If you expect a large value (that your OS might not fit into an environment variable) consider using the transport = "fs" transport instead.If you’re using a type = list[string] and expect commas to exist in the strings, it is recommended to use base64 = true or transport = "fs".

Edition 1 types

Edition 1 types are deprecated

Type	Description	Notes
`number`	Previously used for numbers	converted to a `f64` type
`secret`	Previously used hidden strings	converted to a `string` type with `secret = true`

transport

The default value of transport is env

Transport is either env or fs. The env transport should be used in 90% of cases. The fs transport exists mostly to support potentially large (strings, string lists, blob or blob list) options. Encoding varies by type. See the type section for examples of how different types are encoded with different transports.

required

The default value of required is false

[options.MY_OPTION]
type = "string"
required = true

Options with required = true must be specified to the server. The server will not orchestrate an agent with an unspecified required value. This should be used for options that the agent cannot run without.

Setting a default value for an option and setting required = true will produce a warning. required = true should only be set when you need the user to specify a value for an option.

secret

Only valid on type = "string" or type = "list[string]"

The default value of secret is false

[options.MY_OPTION]
type = "string"
secret = true

Strings with secret = true will be censored in logs and input fields in the UI. This should be used for options with sensitive input, like API keys.

base64

Only valid on type = "string" or type = "list[string]" and when transport = "env"

The default value of base64 is false

[options.MY_OPTION]
type = "string"
base64 = true

Encodes strings (type = "string" or type = "list[string]") in base64. No effect on options with transport = "fs". It is recommended to set base64 = true on list of strings that may contain commas.

default

[options.MY_OPTION]
type = "string"
default = "test"

The default value for this option.

The value of the default must match the given type!For example:

[options.STRING_OPTION]
type = "string"
default = "test"

[options.INT_OPTION]
type = "i32"
default = 123

[options.BOOLEAN_OPTION]
type = "bool"
default = true

[options.INT_LIST_OPTION]
type = "list[i32]"
default = [123, 123, 123]

[options.STRING_LIST_OPTION]
type = "list[string]"
default = ["test", "test", "test"]

u64 types must be represented as a string! See numeric types.

display

The optional display table contains fields that are used to customize how this option is displayed in user interfaces, such as Coral Console.

label

The default value of display.label is the key given for the option in the options table

[options.MY_OPTION]
type = "string"
display.label = "My option"

A optional friendly display name for the option

description

[options.MY_OPTION]
type = "string"
display.description = "My option is used to my make my agent ..."

A human-readable description for this option.

In first edition agents, the description field was placed top level in the option:

[options.MY_OPTION]
type = "string"
description = "My option is used to my make my agent ..."

This syntax is not valid in second edition agents.

group

[options.MY_OPTION]
type = "string"
display.group = "My options"

[options.MY_OPTION2]
type = "string"
display.group = "My options"

[options.MY_OPTION3]
type = "string"
display.group = "Other options"

The group that this option should be in, displayed as an Accordion in Coral Console. All options with the same group name will be combined.

multiline

The default value of display.multiline is false

display.multiline = true has no effect on type = "bool" options

If display.multiline = true then the user input dialog for this field will span multiple lines. Useful for options that contain LLM prompts or partial prompts.

validation

The optional validation table contains fields that are used to validate the potential value given for this option by an agent consumer. The server will reject requests for agents that contain invalid values for options.

The validation table cannot be specified on type = "bool" options

If you do not want to perform a validation on the option’s value you must leave it unspecified!TOML does not support null values.

variants

[options.STRING_OPTION]
type = "string"
validation.variants = ["my value 1", "my value 2", "my value 3"]

[options.INT_OPTION]
type = "i32"
validation.variants = [1, 2, 3]

[options.INT_LIST_OPTION]
type = "list[i32]"
validation.variants = [
    [123, 123, 123],
    [321, 321, 321]
]

[options.STRING_LIST_OPTION]
type = "list[string]"
validation.variants = [
    ["my value 1", "my value 2", "my value 3"],
    ["my value 4", "my value 5", "my value 6"]
]

If specified, only values contained in this array are valid values for this option.

The value of validation.variants cannot be an empty array

The value of the validation.variants must match the given type!

min

Only valid on numeric types

[options.MIN_TOKENS]
type = "i32"
validation.min = 3000

The minimum accepted value for this option. Note that the value given to min must be the same numeric type of the option, this means you cannot specify a negative min value for an unsigned numeric type.

max

Only valid on numeric types

[options.AGENT_ITERATION_COUNT]
type = "i32"
validation.max = 200

The maximum accepted value for this option. Note that the value given to max must be the same numeric type of the option, this means you cannot specify a value of 500 for a type = "u8" option.

min_len

Only valid on type = "string" or type = "list[string]"

[options.SYSTEM_PROMPT]
type = "string"
validation.min_len = 100

The minimum number of characters required for the value of this option.

max_len

Only valid on type = "string" or type = "list[string]"

[options.SYSTEM_PROMPT]
type = "string"
validation.max_len = 2000

The maximum number of characters accepted for the value of this option.

regex

Only valid on type = "string" or type = "list[string]"

TOML parses the \ character, so you will need to escape backslashes in your regular expression with another backslash. See the example TOML below.

[options.EMAIL]
type = "string"
validation.regex = "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"

A regular expression used to validate the value given for this option. Partial matches will be accepted. You can use anchors if you need to control this behaviour.

min_size

Only valid on type = "blob" or type = "list[blob]"

[options.IMAGE]
type = "blob"
validation.min_size = { size = 1.0, unit = "KiB" }

Specifies a minimum size for a blob or list of blobs. Available units:

Unit	Name	Size in Bytes
b	BYTE	1
KiB	KIBIBYTE	1,024
MiB	MEBIBYTE	1,048,576
GiB	GIBIBYTE	1,073,741,824
TiB	TEBIBYTE	1,099,511,627,776
kB	KILOBYTE	1,000
MB	MEGABYTE	1,000,000
GB	GIGABYTE	1,000,000,000
TB	TERABYTE	1,000,000,000,000

max_size

[options.IMAGE]
type = "blob"
validation.max_size = { size = 5.0, unit = "MiB" }

Specifies a maximum size for a blob or list of blobs. Available units:

Unit	Name	Size in Bytes
b	BYTE	1
KiB	KIBIBYTE	1,024
MiB	MEBIBYTE	1,048,576
GiB	GIBIBYTE	1,073,741,824
TiB	TEBIBYTE	1,099,511,627,776
kB	KILOBYTE	1,000
MB	MEGABYTE	1,000,000
GB	GIGABYTE	1,000,000,000
TB	TERABYTE	1,000,000,000,000

Overview

Guides

Concepts

Configuration

Features

Examples

Help

Coral Cloud

​Introduction

​Example

​File format reference

​edition

​Third edition

​Second edition

​First edition

​agent

​name

​version

​description

​capabilities

​runtimes

​docker

​executable

​function

​Runtime transport

​options

​type

​Numeric types

​Other types

​List types

​Edition 1 types

​transport

​required

​secret

​base64

​default

​display

​label

​description

​group

​multiline

​validation

​variants

​min

​max

​min_len

​max_len

​regex

​min_size

​max_size

Introduction

Example

File format reference

edition

Third edition

Second edition

First edition

agent

name

version

description

capabilities

runtimes

docker

executable

function

Runtime transport

options

type

Numeric types

Other types

List types

Edition 1 types

transport

required

secret

base64

default

display

label

description

group

multiline

validation

variants

min

max

min_len

max_len

regex

min_size

max_size