Set up Cadenya from a coding agent

By the end of this page, your app dispatches objectives to a Cadenya Agent. You do two things in a browser. Your coding agent (Claude Code, Codex, Cursor, or whichever one you’ve adopted) does the rest from a terminal, with the Cadenya CLI and a few YAML files.

The two steps you do

Both happen in a browser, and both need a person:

Create a free account at app.cadenya.com/signup. The Free plan needs no card.
Copy an API key from the API keys page, then put it in your project’s .env as CADENYA_API_KEY.

Cadenya creates a default key when you sign up, and it reaches every workspace in your account. The CLI and the SDKs read CADENYA_API_KEY from the environment, so nothing else needs a login. (API keys covers scopes, and keys for a single workspace.) Put the key in .env or your shell, not in a chat message, so it stays out of your coding agent’s transcript. Transcripts get shared. Keys shouldn’t.

What your coding agent does

Everything from here runs in a terminal at the root of your project. (Agents that use skills can also pick up Cadenya’s with npx skills add https://cadenya.com/docs.)

Install the CLI

Homebrew covers macOS and Linux. Chocolatey covers Windows:

brew install cadenya/tools/cadenya

choco install cadenya

No package manager? Download the archive for your platform from the releases page. Then check the install:

cadenya --version

You should see:

cadenya version 1.11.0 (api 1.0)

Find your workspace ID

The CLI reads the environment, not .env. So load the file into the shell first:

set -a; . ./.env; set +a

Every account starts with two workspaces: Development and Production. List them:

cadenya workspaces list

You should see (trimmed to the Development row):

ID                                    EXTERNAL ID  NAME         CREATED
workspace_01KZ950VTH0TJ2ZKF503VX1QPN  development  Development  -

Add the Development ID to .env for your app:

.env

CADENYA_API_KEY=your-api-key
CADENYA_WORKSPACE_ID=workspace_01KZ950VTH0TJ2ZKF503VX1QPN

Then export it for the CLI:

export CADENYA_WORKSPACE_ID=workspace_01KZ950VTH0TJ2ZKF503VX1QPN

With an API key, the CLI takes the workspace from CADENYA_WORKSPACE_ID, so export it before any command that works inside a workspace. The external ID works too, so development does the same job. In a script, this prints the ID and nothing else:

cadenya workspaces list --display json \
  | jq -r '.items[] | select(.metadata.externalId == "development") | .metadata.id'

Trust the hosts your Tool Sets call

Cadenya sends Tool Set requests only to hosts on your account’s trusted endpoints. That way, a Tool Set’s credentials never reach a host you didn’t pick. The Swagger Petstore lives at petstore3.swagger.io, so trust it:

cadenya trusted-endpoints create --name "Swagger Petstore" --host petstore3.swagger.io

Then check the exact URL the Tool Set reads, and look for RESULT_TRUSTED in the result:

cadenya trusted-endpoints verify --display json \
  --url https://petstore3.swagger.io/api/v3/openapi.json

Trust only the hosts your own Tool Sets call, because every Tool Set in the account can reach a trusted host. The list belongs to the account, so one entry covers every workspace.

Describe the setup in config files

The whole setup lives in your repository: a cadenya.yaml for settings, and a .cadenya/ directory with one YAML file per resource. Here’s the layout for an Agent with the Swagger Petstore as its Tool Set:

cadenya.yaml
.cadenya/
  toolSets/
    petstore.yaml
  agents/
    petstore-agent.yaml
    petstore-agent/
      default.yaml

The settings name the workspace and the bundle key:

cadenya.yaml

bundleKey: petstore-app
workspaceId: development

The bundle key marks every resource this repository owns, so give each repository its own. The next step shows why.The Tool Set reads the Petstore’s OpenAPI spec from a URL:

.cadenya/toolSets/petstore.yaml

metadata:
  name: Swagger Petstore
spec:
  description: Find pets, place orders, and manage the store inventory
  adapter:
    type: openapi
    openapi:
      type: url
      url: https://petstore3.swagger.io/api/v3/openapi.json
      baseUrl: https://petstore3.swagger.io/api/v3

The Agent is published, so objectives can use it:

.cadenya/agents/petstore-agent.yaml

state: published
metadata:
  name: Petstore Agent
spec:
  description: Answers questions about pets in the Swagger Petstore

And its variation picks the model and the prompt, then gets the Tool Set:

.cadenya/agents/petstore-agent/default.yaml

metadata:
  name: Default
spec:
  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.
  modelConfig:
    modelId: getting-started-key.anthropic-claude-haiku-latest
    temperature: 0.2
  assignments:
    - type: toolSetId
      toolSetId: external_id:petstore

A modelId is two external IDs joined by a dot: your AI provider key’s, then the model’s. Every account starts with a provider key called getting-started-key, and cadenya models list shows what your workspace can run. Each file’s external ID comes from its filename, which is why the Agent is petstore-agent. (Config files has every rule.)

Check the plan, then apply

Validate first. It runs offline, so it costs nothing:

cadenya config validate

You should see:

Valid bundle petstore-app: 3 resources

But validate can’t see your workspace. So ask Cadenya what would change there:

cadenya config plan

You should see (log lines trimmed):

create    toolSet petstore
create    agent petstore-agent
create    agentVariation petstore-agent/default
publish   agent petstore-agent
Plan: 3 create, 0 update, 0 delete, 0 detach, 1 state change

Apply deletes every resource that carries your bundle key and has no file in .cadenya/. If another repository or teammate uses the same key, their resources show up as delete lines in the plan. Read every delete line before you apply, and leave --allow-empty off unless you mean to delete the whole bundle.

When the plan matches what you expect, apply it:

cadenya config apply

Once the Tool Set exists, Cadenya syncs the Petstore’s operations into it as tools. cadenya tool-sets tools list external_id:petstore lists them.

Dispatch an objective from your app

Install the SDK for your language:

npm install @cadenya/cadenya

pip install cadenya

Then create an objective for the Agent. Both SDKs read CADENYA_API_KEY and CADENYA_WORKSPACE_ID from the environment, so run your app in the shell where you loaded .env (or let your framework’s .env loader handle it):

import Cadenya from "@cadenya/cadenya";

const client = new Cadenya();

const objective = await client.objectives.create({
  agentId: "external_id:petstore-agent",
  firstUserMessage: "Find all pets with status available and summarize them by category.",
});

console.log(objective.metadata.id);

from cadenya import Cadenya

with Cadenya() as client:
    objective = client.objectives.create(
        agent_id="external_id:petstore-agent",
        first_user_message="Find all pets with status available and summarize them by category.",
    )
    print(objective.metadata.id)

curl --request POST \
  "https://api.cadenya.com/v1/workspaces/${CADENYA_WORKSPACE_ID}/objectives" \
  --header "Authorization: Bearer ${CADENYA_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "external_id:petstore-agent",
    "firstUserMessage": "Find all pets with status available and summarize them by category."
  }'

The call returns the new objective at once, and the Agent gets to work in Cadenya. Watch it from the terminal with the ID your app printed:

cadenya objectives stream-events obj_01M08HAWG66MQ3M0P4DDFH6PS0

Each line is one event as JSON: toolCalled when the Agent calls a Petstore tool, assistantMessage when it answers. Press Ctrl-C to stop watching. The objective keeps running (it doesn’t need an audience).

The note your coding agent leaves

Sometimes the code is ready before the account is. Or the agent works somewhere it can’t reach Cadenya. Either way, its last message becomes your setup guide. A useful one names the two browser steps, with both addresses, and ends with the commands that finish the job:

Cadenya needs two steps from you:

Create a free account at app.cadenya.com/signup. The Free plan needs no card.

Copy an API key from app.cadenya.com/account/apiKeys and put it in .env as CADENYA_API_KEY.

Then run cadenya workspaces list, put the Development ID in .env as CADENYA_WORKSPACE_ID, trust petstore3.swagger.io with cadenya trusted-endpoints create, and run cadenya config plan and cadenya config apply.

The sign-up address and the API keys page are the two lines the note can’t leave out. The key doesn’t exist until a person signs up, and no agent can do that part for you.

Where to go next

Your Agent runs objectives now. The objectives guide shows how to stream them, continue them, and approve their tool calls.

Getting Started

The Basics

Account and platform

Set up Cadenya from a coding agent

The two steps you do

What your coding agent does

The note your coding agent leaves

Where to go next

​The two steps you do

​What your coding agent does

​The note your coding agent leaves

​Where to go next

The two steps you do

What your coding agent does

The note your coding agent leaves

Where to go next