> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coralos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://marketplace.coralprotocol.ai/), where they may be used securely for free or become their own revenue streams
* Agent re-usability via [exposable configuration (options)](/reference/agent/tables/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.

<Steps titleSize="h2">
  <Step titleSize="h3" title="Run the server" id="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.

    ```bash git + gradle theme={null}
    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.

    <Tabs>
      <Tab title="Your own LLM provider keys">
        Configure providers directly in `config.toml`. For example:

        ```toml config.toml theme={null}
        [[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](/reference/server/llm-proxy#providers) for more options.

        ```bash theme={null}
        CONFIG_FILE_PATH="$PWD/config.toml" ./gradlew run --args="--auth.keys=dev"
        ```
      </Tab>

      <Tab title="Coral Cloud LLM proxy">
        For convenience, a [Coral Cloud API key](/reference/server/cloud#api-key) automatically configures supported LLM providers and models. Your server and console still run locally; only model requests use the Cloud proxy.

        ```bash theme={null}
        ./gradlew run --args="--auth.keys=dev --cloud.api-key=coral..."
        ```
      </Tab>
    </Tabs>

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

    ```bash theme={null}
    ./gradlew run --args="--auth.keys=dev"
    ```

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

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

  <Step titleSize="h3" title="Create your own agent" id="create-your-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.

    <Tip>See [this guide](/guides/writing-agents) on writing agents for more information on agent requirements.</Tip>

    <AccordionGroup>
      <Accordion title="Using the Koog template (Kotlin)" defaultOpen="true" id="koog-template">
        <CodeGroup>
          ```bash npm theme={null}
          npm create koog -- my-first-agent --agentName=my-first-agent --packageName=com.example.myfirstagent --keepWorkflows=true --keepPublishJvm=true --keepPublishNative=true --keepReleasePlease=true
          ```

          ```bash git + gradle theme={null}
          git clone https://github.com/Coral-Protocol/coral-koog-agent my-first-agent
          cd my-first-agent
          ./gradlew hydrate my-first-agent
          ```
        </CodeGroup>

        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 <Icon icon="external-link" />](https://docs.koog.ai/)

        You should now have a file structure that looks something like this:

        <Tree>
          <Tree.Folder name="my-first-agent" defaultOpen>
            <Tree.Folder name="src">
              <Tree.File name="..." />
            </Tree.Folder>

            <Tree.File name="build.gradle.kts" />

            <Tree.File name="coral-agent.toml" />

            <Tree.File name="..." />
          </Tree.Folder>
        </Tree>

        <Note>
          `coral-agent.toml` is Coral's entrypoint to this agent, with all relevant agent metadata (runtime, options, etc).

          Learn more about it [here](/reference/agent)
        </Note>
      </Accordion>

      <Accordion title={"Other templates & agent examples"} id="other-examples">
        | Language | Framework | Maturity | Repositories |
        | - | - | - | - |
        | Rust | coral-rs (Rig) | Low | [Deepwiki Agent <Icon icon="external-link" />](https://github.com/Coral-Protocol/agents/blob/main/rust/agent-deepwiki/src/main.rs) |
        | Kotlin | Koog | High | [Template <Icon icon="external-link" />](https://github.com/Coral-Protocol/coral-koog-agent) |
        | Python | LangChain | Low | [Template <Icon icon="external-link" />](https://github.com/Coral-Protocol/langchain-agent) |

        Missing any? Come to [our discord <Icon icon="external-link" />](https://discord.gg/2subZkSWWu) to share your own examples or ask for relevant ones.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step titleSize="h3" title="Add the agent to your server" id="link-agent">
    Open a terminal in your generated `my-first-agent` directory, then link it so servers on that machine can discover it:

    ```bash theme={null}
    npx @coral-protocol/coralizer@latest link .
    ```

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

    <Info>
      This creates a symlink called `~/.coral/agents/my-first-agent/{agentVersion}` pointing to your agent's directory
    </Info>

    To "unlink" this agent, you can run:

    ```bash theme={null}
    unlink ~/.coral/agents/my-first-agent/{version}
    # replace {version} with your agent's version (as seen in the coral-agent.toml)
    ```
  </Step>

  <Step titleSize="h3" title="Create a session in Coral Server" id="create-session">
    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](/api-reference/local/create-session), but for a more convenient experience, you can use Coral Console.

    <AccordionGroup>
      <Accordion title="Coral Console (development / testing)" id="console-create-session">
        <Steps titleSize="h3">
          <Step title="Navigate to the console" id="console-navigate">
            Open your browser and go to [http://localhost:5555/ui/console](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`.
          </Step>

          <Step title="Create a session request" id="console-create-template">
            Open **Workbench** and choose **New file**. Give the session request a name.

            <img src="https://mintcdn.com/23turtles/oTFiGOCfrdlQvBzb/images/console/workbench.png?fit=max&auto=format&n=oTFiGOCfrdlQvBzb&q=85&s=4b81ab3f991f030ebe32b9c2166849be" alt="Coral Console Workbench with a session request and its agents" width="1440" height="960" data-path="images/console/workbench.png" />
          </Step>

          <Step title="Add your agent" id="console-add-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.
          </Step>

          <Step title="Fill out necessary agent options and session TTL" id="console-session-config">
            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.
          </Step>

          <Step title="Save the request" id="console-save-template">
            Optionally, click **Save request** to save the configuration for reuse.
          </Step>

          <Step title="Create the session" id="console-run-template">
            Click **Create session** to start your agents.
          </Step>

          <Step title="Observe the agents" id="console-observe-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.
          </Step>
        </Steps>
      </Accordion>

      <Accordion title="From code (production)" id="code-create-session">
        Ultimately it's intended that Coral sessions are instantiated via code. Coral Console provides the needed JSON payload for the [create session endpoint](/api-reference/local/create-session), 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](#run-the-server), so use the header `Authorization: Bearer dev`. The documentation endpoints are public, while agents use their own MCP URLs and agent RPC credentials.
        <Note>The server's `auth.keys` authenticate these API requests. LLM provider keys, including the Coral Cloud proxy key, are configured separately on the server.</Note>

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

        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.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

That wraps up the CoralOS quickstart! Next, see [Integrating with your app](/guides/integrating-with-your-app).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.