> ## 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

<Tip>
  You can try out CoralOS right away with some pre-built agents using [Coral Cloud](https://coralcloud.ai/).

  The operation of Coral Cloud is very similar, though currently it doesn't support using your own agents.

  For a deep dive on using Coral Cloud, see [this guide](/cloud/using-api)
</Tip>

<Steps titleSize="h2">
  <Step titleSize="h3" title="Run the server" id="run-the-server">
    Running the server is easy:

    You will need a Coral Cloud API key in order for the server to proxy LLM requests to any of the supported LLM providers.
    More details on this can be found [here](/reference/server/cloud).

    ```bash git + gradle theme={null}
    # Start server (logs show in this terminal)
    git clone https://github.com/Coral-Protocol/coral-server
    cd coral-server
    ./gradlew run --args="--auth.keys=dev --cloud.api-key=coral..."
    ```

    <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 coral-koog-agent
          ./gradlew hydrate my-first-agent
          ```
        </CodeGroup>

        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](/configuration/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">
    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:

    ```bash theme={null}
    cd my-first-agent
    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)
          </Step>

          <Step title="Create a new template" id="console-create-template">
            Click on 'Templates' under 'Workbench', then create a new template

            <img src="https://mintcdn.com/23turtles/STEllokoEWINfJfD/images/console/create-template.png?fit=max&auto=format&n=STEllokoEWINfJfD&q=85&s=c840e041026d0a7b7533ad08a7751acc" alt="Create template UI" width="797" height="380" data-path="images/console/create-template.png" />
          </Step>

          <Step title="Add your agent" id="console-add-agent">
            Click `Add an agent` to add an agent to the template
          </Step>

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

          <Step title="Click 'Save template'" id="console-save-template">
            Optionally, save the template you just created
          </Step>

          <Step title="Run the template" id="console-run-template">
            Run the template you just created to start a new session with your agent
          </Step>

          <Step title="Observe the agents" id="console-observe-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>
        </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 all endpoints. We set our auth key to `dev` in [Step 1](#run-the-server), so we must use the header `Authorization: Bearer dev`.
        <Note>In the case of Coral Cloud, it must be an API key you create from your [account settings](https://coralcloud.ai/account).</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!