Skip to main content

​
What is CoralOS?

CoralOS is a platform for deploying and orchestrating agents that connect easily (with each other, your application, agentic middleware, …) CoralOS consists of the Coral Server and supporting tooling and ecosystem. Think of CoralOS as the “Kubernetes for agents”. There is an HTTP api, like a control plane, that lets you spin up a lifecycle-controlled graph of agents.

​
What makes an agent a CoralOS agent?

The basic requirements for an agent to run via Coral and support all of its capability and interopabiltiy enablements are:
  • it can run in a container
  • it connects to the supplied unique MCP server URL passed to it
With just those requirements met, a whole host of things become possible:
  • Custom tools can be defined by the consuming application
  • Agents can discover and work with the other agents they are in groups with
  • Their lifecycles are handled, with TTL support

​
What are some more advanced features of CoralOS?

CoralOS makes many more interesting things easy:
  • Pushing your agents to a marketplace, where they may be used securely for free or become their own revenue streams
  • Define parameters (Options)
  • Edit agent’s LLM requests in-place, to e.g. patch prompts, add memory to memoryless agents, or change the model used; without touching agent code (coming soon)

​
Quickstart Cloud

Right away you can try out CoralOS with some pre-built agents using Coral Cloud. Or you can skip to [getting started with the local version directly](#Quickstart Local)The operation of Coral Cloud is very similar, though currently it doesn’t support using your own agents.Here is a deepdive on using coral cloud

​
Quickstart Local (Recommended)

​
Tl;dr

1

Start the server

# Start server (logs show in this terminal)
npx coral-server@1.1.0 start --registry.enable-marketplace-agent-registry-source=true --auth.keys=dev
2

Create a kotlin koog agent

# Create a kotlin agent using the koog template (run in separate terminal)
npm create koog my-first-agent
3

Link the agent to your coral server

cd my-first-agent
npx @coral-protocol/coralizer@latest link $(pwd)
4

Run the agent via Coral Console

  1. Navigate to http://localhost:5555/ui/console
  2. Click on “Templates” under “Workbench”, then create a new template
  3. Add your agent
  4. Fill out the necessary option values and set the session’s TTL
  5. Click “Save template”
  6. Run the template
5

Observe the agent's execution and results

  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

​
Step 1) Running the server

All you need to do to get started is to run the server. Running the server is easy: 
# Start server (logs show in this terminal)
npx coral-server@1.1.0 start --registry.enable-marketplace-agent-registry-source=true --auth.keys=dev
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.
The UI shall introduce itself. Feel free to play around. There will be a selection of agents you might like to try.

​
Step 2) Add your own agent

Let’s add an agent from source to the coral server. In this section we’ll use the Kotlin / Koog agent, since it has the same dependencies as the server. Adding other agents in other languages afterwards is easy and CoralOS has no issue running agents from different languages together.

​
Step 2.1) Creating the agent Koog (Kotlin) template

For convenience there is a Koog template. You can create an instance of this agent easily by running this command: 
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 where all coral-related metadata for this agent belongs.
Learn more about coral-agent.toml here

​
See also: Full list of Agent examples

LanguageFrameworkMaturity/updatednessAgent
RustCoral-RS (Rig)Medium-highDeepwiki
KotlinKoogHighkoog agent template
PythonDataLowLangchain agent template
Missing one? Come to our discord and to share your own examples or ask for relevant ones.

​
Step 3) Add the agent to your coral 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 $(pwd)
To remove this agent, you can run `unlink ~/.coral/agents/my-first-agent/(version)

​
Step 4) Run the agent via coral console

Let’s run the agent via the console first
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

Add your agent to the template
4

Fill out the necessary option values and set the session's TTL

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

Click 'Save template'

Save the template you just created
6

Run the template

Run the template you just created to start a new session with your agent
The options an agent has are defined in the coral-agent.toml. This agent template has some sensible options, but you’re free to let the options be whatever makes sense for your use-case.

​
Step 4.1) 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

​
Step 5) Instantiate the session from code

Ultimately it’s intended that coral sessions are instantiated via code. You’ll notice that the console shows the code needed to run a session. Lastly you can copy the most convenient language snippet into your codebase. Authorization headers should be Bearer dev where dev is the auth key. In the case of Coral Cloud, it should be your API key. Naturally, variable substitution and environment variables should be used over hardcoding every option value.

​
Next

That wraps up the CoralOS quickstart! Next, see integrating with your app