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

# Introduction

> Cadenya. The Agent Runtime.

export const Asset = ({id, caption, alt}) => {
  const assets = {
    "videos/guides/getting-started/create-tool-set": {
      "url": "https://assets.cadenya.com/dotcom/videos/guides/getting-started/create-tool-set.9be9e1a903c8.mp4",
      "type": "video/mp4",
      "width": 1920,
      "height": 1030
    },
    "videos/guides/the-basics/agent-webhook": {
      "url": "https://assets.cadenya.com/dotcom/videos/guides/the-basics/agent-webhook.2a9c1538cca4.mp4",
      "type": "video/mp4",
      "width": 1920,
      "height": 1226
    },
    "videos/guides/the-basics/configure-variation-model": {
      "url": "https://assets.cadenya.com/dotcom/videos/guides/the-basics/configure-variation-model.2525e84673eb.mp4",
      "type": "video/mp4",
      "width": 1816,
      "height": 1080
    },
    "videos/guides/the-basics/configure-variation-toolset": {
      "url": "https://assets.cadenya.com/dotcom/videos/guides/the-basics/configure-variation-toolset.283859ee975e.mp4",
      "type": "video/mp4",
      "width": 1816,
      "height": 1080
    },
    "videos/guides/the-basics/memory-layer-assignment": {
      "url": "https://assets.cadenya.com/dotcom/videos/guides/the-basics/memory-layer-assignment.61fdf8b0729e.mp4",
      "type": "video/mp4",
      "width": 1920,
      "height": 1168
    },
    "videos/guides/the-basics/memory-tool-usage": {
      "url": "https://assets.cadenya.com/dotcom/videos/guides/the-basics/memory-tool-usage.09350e7a5f41.mp4",
      "type": "video/mp4",
      "width": 1920,
      "height": 1168
    }
  };
  const asset = assets[id];
  if (!asset) {
    return <div style={{
      border: "2px solid #dc2626",
      borderRadius: 8,
      padding: 12,
      color: "#dc2626",
      fontFamily: "monospace"
    }}>
        Unknown asset key: {id}. Run <code>just upload-assets</code> and check <code>assets/manifest.json</code>.
      </div>;
  }
  const isVideo = asset.type.startsWith("video/");
  const media = isVideo ? <video autoPlay muted loop playsInline controls src={asset.url} width={asset.width} height={asset.height} /> : <img src={asset.url} alt={(alt ?? caption) ?? ""} width={asset.width} height={asset.height} />;
  return caption ? <Frame caption={caption}>{media}</Frame> : <Frame>{media}</Frame>;
};

Before you start, you need:

* A Cadenya account
* About 15 minutes and a positive attitude

If videos are your thing, here's Robert with a \~10 minute video end-to-end configuring an agent and dispatching an objective for it.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/zNPn19oVxrk" title="Cadenya walkthrough" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Create An Account

If you haven't, create an account at [https://app.cadenya.com/signup](https://app.cadenya.com/signup). After signing up and paying your initial monthly fee, you'll gain access to the Cadenya platform and API. There's no waiting.

<Callout icon="check" color="#165b41" iconType="regular">
  **Cadenya does not have a free plan.** The level of effort to abuse free accounts has been greatly reduced in the past few years, and we avoid playing free tier whack-a-mole by requiring a minimum fee of \$20.00 USD for all accounts.
</Callout>

Your account will be created with two workspaces: **Development** and **Production**. Workspaces are isolated from each other in Cadenya, so you can configure them independently.

Cadenya provisions an [OpenRouter](https://openrouter.com) key for you with a max budget of **\$5** to immediately try the product. After that, you need to grant Cadenya access to your own LLM provider. Cadenya does not provide inference.

## Install Cadenya's Skills

Cadenya comes with multiple skills for your coding agents to make use of. You can install them with:

```bash theme={null}
npx skills add https://cadenya.com/docs
```

## Install the CLI

<CodeGroup>
  ```bash Homebrew theme={null}
  brew install cadenya/tools/cadenya
  ```

  ```shell Chocolatey theme={null}
  choco install cadenya
  ```
</CodeGroup>

<Info>Cadenya's CLI is notarized for MacOS installations so you know it's from us. It was a pain to do, and we can't go through that without humble bragging.</Info>

## Login with the CLI

This guide assumes you're using a coding assistant such as Claude Code or OpenAI's Codex. Cadenya can be fully driven via our user interface, but leveraging the CLI makes getting started much faster.

Once installed, you can initialize the account pairing with:

<Steps>
  <Step title="Login">
    ```bash theme={null}
    cadenya auth login
    ```
  </Step>

  <Step title="Authorize the workspace">
    A browser window should open to an authorization page which will allow you to select which workspaces to give the CLI access to. Select your **Development** workspace. You can add others later by going through the same process.

    <Frame caption="Authorize the CLI">
      <img src="https://mintcdn.com/cadenya/hN8a0e17vbUjzqGa/images/guides/getting-started/cli-auth.png?fit=max&auto=format&n=hN8a0e17vbUjzqGa&q=85&s=93ebadc8b54f029a42dd20ae8a5fee8f" style={{height: "500px", width: "auto"}} width="1016" height="1653" data-path="images/guides/getting-started/cli-auth.png" />
    </Frame>
  </Step>

  <Step title="Test the CLI">
    Once you've authorized your workspace, you may close the window. The CLI in your terminal should show a successful authorization.

    Try the CLI with:

    ```bash theme={null}
    cadenya auth status
    ```

    You should see something like:

    ```
    ~/Code/cadenya.com % cadenya auth status
    Profile "default": logged in.
      workspace: workspace_01KZ950VTH0TJ2ZKF503VX1QPN
    ```
  </Step>

  <Step title="Self-five yourself">
    You may now self-five yourself while no one is looking. 🙏
  </Step>
</Steps>

## Nomenclature

Cadenya has a few terms that you'll see everywhere. You'll understand them more as you use the product, but in general:

<table>
  <tbody>
    <tr>
      <td style={{width: "20%"}}>**Tool Sets**</td>
      <td>Configures a group of OpenAPI, MCP, HTTP, or Bare tools. Handles tool filtering, approval rules, and overlays to manage context from tool calls an LLM makes.</td>
    </tr>

    <tr>
      <td>**Agents**</td>
      <td>Agents have at-least-one variation that can be assigned an objective. Variations can be given Tool Sets, tools, or **other agents** for the behavior.</td>
    </tr>

    <tr>
      <td>**Objectives**</td>
      <td>Objectives are dispatched from your code (or schedules) using the Cadenya SDK and will initiate your agentic loop with the assigned tools. Compaction, approvals, and more are tied to objectives. Some products call this a session. We like objective.</td>
    </tr>

    <tr>
      <td>**Memory Layers**</td>
      <td>Memory layers are optional types that can be assigned to agent variations and be used to store documents, skills, or other facts. Memories can be created by an agent that has **episodic memory** enabled.</td>
    </tr>

    <tr>
      <td>**Widgets**</td>
      <td>Widgets are how you can use your Agents in Cadenya in your own webapp with minimal backend interaction. Custom domains. CORS. And React Components. All pre-built.</td>
    </tr>
  </tbody>
</table>

## Your First Tool Set, Agent, and Objective

There are two flavors to the rest of this guide. You either are here to see what Cadenya is all about, or you've created your account and you're ready to rock and roll with the CLI. Here's how you can decide:

* **CLI Docs** - You're here to speed run to dispatching an objective.
* **UI Docs** - You're here to visualize Cadenya before buying.

<Tabs>
  <Tab title="CLI Docs">
    <Steps>
      <Step title="Create the Tool Set">
        With your CLI authenticated, we can now use it to create a Tool Set.

        ```bash theme={null}
        cadenya tool-sets create --display extended \
          --workspace-id "development" \
          --metadata '{"name":"Petstore","externalId":"petstore"}' \
          --spec '{
            "description": "Swagger Petstore v3",
            "adapter": {
              "type": "openapi",
              "openapi": {
                "type": "url",
                "url": "https://petstore3.swagger.io/api/v3/openapi.json",
                "baseUrl": "https://petstore3.swagger.io/api/v3"
              }
            }
          }'
        ```

        You should see something like this in your stdout

        ```
        -[ RECORD 1 ]-
        ID      | toolset_01M08DTBR03YX7CH93WYHF13S3
        NAME    | Petstore
        CREATED | 2026-08-17T17:55:26.080514869Z
        STATE   | STATE_ACTIVE
        ```
      </Step>

      <Step title="Create an Agent">
        Now we can create an Agent

        ```bash theme={null}
        cadenya agents create --display extended \
          --workspace-id "development" \
          --metadata '{"name":"Petstore Agent","externalId":"petstore-agent"}' \
          --spec '{
            "description": "Answers questions about pets in the Swagger Petstore",
            "variationSelectionMode": "VARIATION_SELECTION_MODE_RANDOM"
          }'
        ```
      </Step>

      <Step title="Attach a variation">
        Now we can give our Agent a new variation that assigns the model and default prompts.

        ```bash theme={null}
        cadenya agents variations create petstore-agent \
          --display extended \
          --workspace-id "development" \
          --metadata '{"name":"default","externalId":"petstore-agent-default"}' \
          --spec '{
            "description": "Haiku-backed default variation",
            "systemPromptTemplate": "You are a helpful assistant for the Swagger Petstore. Use the available tools to look up pets, inventory, and orders. Do not invent pet data.",
            "firstUserMessageTemplate": "List inventory",
            "modelConfig": {
              "modelId": "getting-started-key.anthropic-claude-haiku-latest",
              "temperature": 0.2
            },
            "constraints": {
              "maxToolCalls": 25,
              "inactivityTimeout": "3600s"
            }
          }'
        ```

        And we can compose our new variation with our Tool Set from earlier (The one that actually defines the Petstore tools).

        ```bash theme={null}
        cadenya agents variations add-assignment \
          petstore-agent \
          petstore-agent-default \
          --workspace-id "development" \
          --tool-set-id petstore \
          --display json
        ```

        Before an Agent can be used to dispatch an Objective, we need to mark it as published.

        ```bash theme={null}
        cadenya agents publish petstore-agent \
          --display extended \
          --workspace-id "development"
        ```

        Now let's kick off an Objective.
      </Step>

      <Step title="Dispatch an objective">
        Now you have a Tool Set, an Agent, and an Agent Variation. Last stop: **Objective town.**

        ```bash theme={null}
        cadenya objectives create \
          --agent-id petstore-agent \
          --metadata '{"externalId":"petstore-run-001","labels":{"source":"cli"}}' \
          --system-prompt-data '{}' \
          --first-user-message 'Find all pets with status available and summarize them by category.'
        ```

        You should see:

        ```
        ID                              CREATED                         STATE
        obj_01M08HAWG66MQ3M0P4DDFH6PS0  2026-08-17T18:56:53.254341617Z  STATE_PENDING
        ```
      </Step>

      <Step title="See the event log">
        Now that you have an objective, you can list its events as well. There are endpoints for streaming events, too. But for quick-start purposes we're going to skip those for now.

        ```
        cadenya objectives list-events petstore-agent
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="UI Docs">
    <Steps>
      <Step title="Copy the spec">
        ```
        https://free.cadenya.com/faker-mcp
        ```
      </Step>

      <Step title="Create a Tool Set">
        * Navigate to [Tool Sets](https://app.cadenya.com/w/development/toolSets) in your workspaces navigation.
        * Click "Create Tool Set"
        * Fill in the name "Faker MCP"
        * Select "MCP" for the adapter type
        * Set the URL to `https://free.cadenya.com/faker-mcp` (from your clipboard if you copied it)
        * Disable "Just-in-time" loading (for now, you'll use it later)
        * Save the Tool Set

        <Asset id="videos/guides/getting-started/create-tool-set" caption="Assigning a tool set" />
      </Step>

      <Step title="Go to Agents" />
    </Steps>
  </Tab>
</Tabs>