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

# Set up Cadenya from a coding agent

> From no account to a working app: a person creates a free account at app.cadenya.com/signup and copies an API key from app.cadenya.com/account/apiKeys, then a coding agent installs the CLI, trusts the Tool Set hosts, writes the config files, and runs cadenya config apply.

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:

1. Create a free account at app.cadenya.com/signup. The Free plan needs no card.
2. Copy an API key from the [API keys page](https://app.cadenya.com/account/apiKeys), 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](https://cadenya.com/docs/api-keys.md) 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`.)

**1. Install the CLI**

Homebrew covers macOS and Linux. Chocolatey covers Windows:

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

```powershell Chocolatey theme={null}
choco install cadenya
```

No package manager? Download the archive for your platform from the [releases page](https://github.com/cadenya/cadenya-cli/releases). Then check the install:

```bash theme={null}
cadenya --version
```

You should see:

```
cadenya version 1.11.0 (api 1.0)
```

**2. Find your workspace ID**

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

```bash theme={null}
set -a; . ./.env; set +a
```

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

```bash theme={null}
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:

```bash .env theme={null}
CADENYA_API_KEY=your-api-key
CADENYA_WORKSPACE_ID=workspace_01KZ950VTH0TJ2ZKF503VX1QPN
```

Then export it for the CLI:

```bash theme={null}
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:

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

**3. 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:

```bash theme={null}
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:

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

**4. 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:

```text theme={null}
cadenya.yaml
.cadenya/
  toolSets/
    petstore.yaml
  agents/
    petstore-agent.yaml
    petstore-agent/
      default.yaml
```

The settings name the workspace and the bundle key:

```yaml cadenya.yaml theme={null}
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:

```yaml .cadenya/toolSets/petstore.yaml theme={null}
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:

```yaml .cadenya/agents/petstore-agent.yaml theme={null}
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:

```yaml .cadenya/agents/petstore-agent/default.yaml theme={null}
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](https://cadenya.com/docs/config-files.md) has every rule.)

**5. Check the plan, then apply**

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

```bash theme={null}
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:

```bash theme={null}
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
```

> [!WARNING]
>
> 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:

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

**6. Dispatch an objective from your app**

Install the SDK for your language:

```bash TypeScript theme={null}
npm install @cadenya/cadenya
```

```bash Python theme={null}
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):

```typescript TypeScript theme={null}
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);
```

```python Python theme={null}
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)
```

```bash cURL theme={null}
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:

```bash theme={null}
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:
>
> 1. Create a free account at app.cadenya.com/signup. The Free plan needs no card.
> 2. 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](https://cadenya.com/docs/guides/the-basics/objectives.md) shows how to stream them, continue them, and approve their tool calls.


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