​

What is CoralOS?

​

What makes an agent a CoralOS agent?

• it can run in a container
• it connects to the supplied unique MCP server URL passed to it

• Custom tools can be provided to any agent by the consuming application
• Agents can discover and work with the other agents they are in groups with
• Their lifecycles are fully managed, with configurable time-to-live for cost predictability.

​

What are some more advanced features of CoralOS?

• Pushing your agents to a marketplace, where they may be used securely for free or become their own revenue streams
• Agent re-usability via exposable configuration (options)
• Safely intercept & manipulate LLM requests in-flight, to e.g. patch prompts, add memory to memoryless agents, or change the model used; without touching agent code (coming soon)

​

Getting started

1

Run the server

Running the server is easy:

npx

git + gradle

npx coral-server@1.1.0 start --registry.enable-marketplace-agent-registry-source=true --auth.keys=dev
# Logs will show in this terminal

After the server starts, it prints an address to the Coral Console. You can “login” with the auth key dev or whatever you passed for the auth.keys parameter.

Make sure to use a secure auth key in production, and follow conventional security practices when exposing your Coral Server to the public internet!

2

Create your own agent

Let’s create a new agent from source to use in our server.We will use a template for convenience, but writing agents in any framework (or modifying existing to work with Coral) is also easy.

See this guide on writing agents for more information on agent requirements.

Using the Koog template (Kotlin)

npm

git + gradle

npm create koog my-first-agent

This will create a Kotlin agent using JetBrain’s wonderful Koog framework You should now have a file structure that looks something like this:

my-first-agent

src

build.gradle.kts

coral-agent.toml

...

coral-agent.toml is Coral’s entrypoint to this agent, with all relevant agent metadata (runtime, options, etc).Learn more about it here

Other templates & agent examples

Language	Framework	Maturity	Repositories
Rust	coral-rs (Rig)	Medium-high	Deepwiki Agent
Kotlin	Koog	High	Template
Python	LangChain	Low	Template

Missing any? Come to our discord to share your own examples or ask for relevant ones.

3

Add the agent to your server

Once you have an agent’s source code on your machine, you can “link” it so that any server you run on that machine will have access to it:

cd my-first-agent
npx @coral-protocol/coralizer@latest link .

On Windows, you may need to run as administrator to avoid permission issues creating the symlink

This creates a symlink called ~/.coral/agents/my-first-agent/{agentVersion} pointing to your agent’s directory

To “unlink” this agent, you can run:

unlink ~/.coral/agents/my-first-agent/{version}
# replace {version} with your agent's version (as seen in the coral-agent.toml)

4

Create a session in Coral Server

Now that you have agent(s) in your server, you can create a multi agent session!Creating a session can be done in one POST request, but for a more convenient experience, you can use Coral Console.

Coral Console (development / testing)

1

Navigate to the console

Open your browser and go to http://localhost:5555/ui/console

2

Create a new template

Click on ‘Templates’ under ‘Workbench’, then create a new template

3

Add your agent

Click Add an agent to add an agent to the template

4

Fill out necessary agent options and session TTL

Depending on your agent(s), you may need to fill out some values here.You must also set the session’s TTL (time-to-live), which determines how long the session can run before it is automatically terminated.

5

Click 'Save template'

Optionally, save the template you just created

6

Run the template

Run the template you just created to start a new session with your agent

7

Observe the agents

1. Go to the session you just started under “Session” in the sidebar
2. Check out the agents and their logs
3. Check out what’s going on in the threads

From code (production)

Ultimately it’s intended that Coral sessions are instantiated via code. Coral Console provides the needed JSON payload for the create session endpoint, as well as code snippets that include making the request.Coral Server requires a bearer token for all endpoints. We set our auth key to dev in Step 1, so we must use the header Authorization: Bearer dev.

In the case of Coral Cloud, it must be an API key you create from your account settings.

Make sure to use a secure auth key, and follow conventional security practices when exposing your Coral Server to the public internet!

Naturally, variable substitution and environment variables should be used over hardcoding every option value, since sensitive information like API keys can be passed as agent options.