Quickstart

CoralOS Quickstart

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/ecosystem.

Think of CoralOS as the “Kubernetes for agents”: you have a HTTP API, like a control plane, that lets you spin up a graph of agents with fully controlled lifecycles.

What makes an agent a CoralOS agent?

The basic requirements for an agent to run via Coral and be fully interoperable with the ecosystem are:

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

With just those met, a whole host of things become possible:

• 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?

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
• 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 (in-flight manipulation features coming soon)

Getting started

Start by running Coral Server locally, then add your agents. Use Coral Console for development and debugging, and the API to create sessions from your application.

1. Run the server

   Running the server is easy:

   Build and run the server with JDK 24 and Git installed. Docker is also required for agents using the Docker runtime.

   git + gradle

   git clone --branch v1.5.0 https://github.com/Coral-Protocol/coral-server
   cd coral-server
   

   Choose how your local server accesses language models. Both options work with your own Coral Server; Coral Console is available locally for development and debugging.

   Your own LLM provider keys

   Configure providers directly in config.toml. For example:

   config.toml

   [[llm-proxy.providers]]
   name = "OpenAI"
   format.type = "OpenAI"
   api_key = "YOUR_OPENAI_API_KEY"
   base_url = "https://api.openai.com"
   models = ["gpt-4.1-mini", "gpt-5-mini"]
   
   [[llm-proxy.providers]]
   name = "Anthropic"
   format.type = "Anthropic"
   api_key = "YOUR_ANTHROPIC_API_KEY"
   base_url = "https://api.anthropic.com"
   models = ["claude-opus-4-6", "claude-sonnet-4-0"]
   

   Keep the providers you use and include the models your agents request. See LLM provider configuration for more options.

   CONFIG_FILE_PATH="$PWD/config.toml" ./gradlew run --args="--auth.keys=dev"
   

   Coral Cloud LLM proxy

   For convenience, a Coral Cloud API key automatically configures supported LLM providers and models. Your server and console still run locally; only model requests use the Cloud proxy.

   ./gradlew run --args="--auth.keys=dev --cloud.api-key=coral..."
   

   Built-in debug agents do not need an LLM provider. To start a server without model access:

   ./gradlew run --args="--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.

   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

   npm create koog -- my-first-agent --agentName=my-first-agent --packageName=com.example.myfirstagent --keepWorkflows=true --keepPublishJvm=true --keepPublishNative=true --keepReleasePlease=true
   

   Check the template’s own README for its JDK requirement; it can differ from Coral Server’s JDK 24 requirement.

   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)	Low	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

   Open a terminal in your generated my-first-agent directory, then link it so servers on that machine can discover it:

   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. The screenshots show Console v0.3.18; to select this version, start the server with --console.console-release-version=v0.3.18.

   2. Create a session request

      Open Workbench and choose New file. Give the session request a name.

      
   3. Add your agent

      In the Agents panel, find your agent and click Add. Select it in the diagram or Outline, then use Inspector to configure its options.

   4. Fill out necessary agent options and session TTL

      Configure the required agent options in Inspector. In Groups, put agents that need to communicate in the same group.

      Use the Session panel to set the budget and TTL (time-to-live), which determines how long the session can run before it is automatically terminated.

   5. Save the request

      Optionally, click Save request to save the configuration for reuse.

   6. Create the session

      Click Create session to start your agents.

   7. Observe the agents

      1. Expand the session you just started under Sessions in the sidebar.
      2. Expand Agents, select an agent, and inspect its status and Logs.
      3. Expand Threads to inspect the conversation.

   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 application REST endpoints. We set our auth key to dev in Step 1, so use the header Authorization: Bearer dev. The documentation endpoints are public, while agents use their own MCP URLs and agent RPC credentials.

   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.

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