---
name: anlyon-setup
description: Sets up Anlyon in a codebase so an AI agent's writes to third-party APIs run as governed actions, under limits and approvals, with a receipt, while the agent never holds the provider credential. Use when the user wants to add Anlyon to a project, run anlyon init, install @anlyonhq/sdk or the anlyon Python package, choose or check Anlyon API keys and scopes, connect Claude Code, Cursor or Codex to the Anlyon MCP server, keep guardrails in anlyon.yaml, or make and verify a test governed call.
license: MIT
metadata:
  author: Anlyon
  version: "1.1.0"
  docs: https://docs.anlyon.com/skills/anlyon-setup
---

# Setting up Anlyon

Anlyon sits between an agent and the APIs it changes things in. An **action** is defined once: method, URL, headers that reference a vaulted credential, and an input schema. The agent invokes it by name with input. Anlyon resolves the credential, checks policies and limits, waits for a person when a policy says so, makes the call, and records a receipt.

## Start here: `anlyon init`

In the project's root, run:

```bash
npx @anlyonhq/cli init --yes --json
```

It signs the user in through the browser (they can sign up there), writes an agent key to `.env` (`.env.local` for Next.js) without printing it, adds `.env*` to `.gitignore`, installs the SDK with the project's package manager, adds the hosted MCP server to `.mcp.json`, `.cursor/mcp.json` and `.codex/config.toml` without touching other servers, and makes one governed read with the new key. Read the JSON report and tell the user the outcome and the receipt id. Running it again is safe.

- Add `--pack github` (or another catalogue integration) to install that integration's actions and connect its account. For an integration that takes a key, the user runs `anlyon connections add <integration>` in their own terminal; never ask for the key.
- Exit 15 or a `signOffUrl` in the report: adding an action loosens the guardrails, so a person approves it at that link. Give the user the link. Run init again after they approve, or pass `--wait 15m`.
- Exit 10: `.env` holds a key for another environment. Ask the user before changing it.
- The browser is for signing in, a provider's consent page, a sign-off and payment. Everything else is done from the terminal.
- To keep actions, policies, limits and budgets in the repository: `anlyon pull` writes `anlyon.yaml`, `anlyon plan` shows changes as tightening or loosening, `anlyon apply --yes` applies them. See https://docs.anlyon.com/cli/config-as-code.md.
- Plan and billing: `anlyon billing status`; `anlyon billing upgrade --plan starter` opens the checkout page for the user.

Use the manual steps below when `init` cannot run (no Node, no browser for the user) or when the project needs separate operator and agent keys.

## Rules

- Read keys from environment variables. Never print, log, echo or commit an Anlyon key, a provider token or a secret value, and never paste one into a file, a test or a chat reply. `.env.example` gets variable names with empty values.
- Outside `anlyon init`, you cannot create keys. Ask the user to create them in the console (https://console.anlyon.com, **Settings → API keys**) and set the variables themselves. Each key is shown once.
- Keep two kinds of key apart. The key that stores credentials and defines actions never runs in the agent's process. See [references/keys-and-scopes.md](references/keys-and-scopes.md).
- Do not guess endpoints or fields. Any docs page is available as Markdown: append `.md` to its URL, for example https://docs.anlyon.com/quickstart.md. The index is https://docs.anlyon.com/llms.txt.

## Workflow

Copy this checklist and tick it off:

```
- [ ] 1. Decide whose accounts the agent acts in
- [ ] 2. Keys and environment variables
- [ ] 3. Install the SDK
- [ ] 4. Check the key at startup
- [ ] 5. Define a test governed action (operator key)
- [ ] 6. Invoke it and read the receipt (agent key)
- [ ] 7. Add the Anlyon block to the project's agent rules file
```

### 1. Whose accounts?

- **The product's users' own accounts** (each user's GitHub or Notion): the server names the user on every call. Do steps 2 to 4 here, then follow the `anlyon-end-users` skill if it is installed, or https://docs.anlyon.com/guides/act-for-your-users.md.
- **The company's own accounts**: workspace connections. This skill covers it.
- **A coding agent that should call actions while you work** (Claude Code, Cursor, Codex): connect it over MCP. See [references/mcp-clients.md](references/mcp-clients.md).

### 2. Keys and environment variables

| Variable | Used by | Scopes |
| --- | --- | --- |
| `ANLYON_OPERATOR_KEY` | Setup scripts and deploy jobs that store secrets and define actions | `secrets:write`, `secrets:read`, `actions:write` (add `policies:write`, `impact-limits:write` when code creates policies or limits) |
| `ANLYON_AGENT_KEY` | The agent's process | The **Standard** preset: it includes `actions:invoke`, `actions:read` and `approvals:read` |
| `ANLYON_API_KEY` | A product server acting for its users | Standard plus `end-users:read`, `end-users:write` and `end-users:approvals`, with **Require a user** on |

A key belongs to one environment and its scopes are fixed when it is created. Use a staging environment's keys outside production.

### 3. Install

```bash
npm install @anlyonhq/sdk        # or: pnpm add / yarn add / bun add
pip install anlyon               # or: uv add anlyon / poetry add anlyon
```

For the Vercel AI SDK, also `npm install @anlyonhq/ai-sdk` (needs `ai` v7 and Node 22+). The client calls `https://api.anlyon.com`; pass `baseUrl` (TypeScript) for another API host.

### 4. Check the key at startup

Fail fast when a key is missing a scope, or holds one the agent must not have:

```typescript
import { Client } from '@anlyonhq/sdk';

const anlyon = new Client({ apiKey: process.env.ANLYON_AGENT_KEY! });
await anlyon.auth.requireScopes(['actions:invoke', 'actions:read'], {
  forbidden: ['secrets:write', 'policies:write', 'approvals:decide', 'impact-limits:write'],
});
```

```python
import os
from anlyon import Client

anlyon = Client(api_key=os.environ["ANLYON_AGENT_KEY"])
anlyon.auth.require_scopes(
    ["actions:invoke", "actions:read"],
    forbidden=["secrets:write", "policies:write", "approvals:decide", "impact-limits:write"],
)
```

A `ScopeCheckError` lists `missing` and `forbidden`. Report the names to the user; never the key.

### 5. Define a test governed action

Run once, with the operator key, from a setup script. `governed: true` makes every call create a receipt. The target echoes the request and changes nothing.

```typescript
// scripts/anlyon-setup.mts  (run: npx tsx scripts/anlyon-setup.mts)
import { Client } from '@anlyonhq/sdk';

const ops = new Client({ apiKey: process.env.ANLYON_OPERATOR_KEY! });

await ops.actions.create({
  name: 'anlyon-smoke-test',
  description: 'Echo the input. Changes nothing. Used to check the Anlyon setup.',
  method: 'POST',
  urlTemplate: 'https://httpbin.org/anything',
  inputSchema: {
    type: 'object',
    properties: { orderId: { type: 'string' }, amount: { type: 'integer', minimum: 0 } },
    required: ['orderId', 'amount'],
  },
  governed: true,
});
```

A real action stores its credential from an environment variable and limits where it may be sent:

```typescript
await ops.secrets.put('STRIPE_KEY', {
  value: process.env.STRIPE_KEY!,
  allowedHosts: ['api.stripe.com'],
});
// then reference it in headers as 'Bearer {{secret:STRIPE_KEY}}'
```

For impact, read-backs, approval policies, limits, packs and OpenAPI import, use the `anlyon-governed-actions` skill, or https://docs.anlyon.com/execution/actions.md.

### 6. Invoke it and read the receipt

```typescript
const anlyon = new Client({ apiKey: process.env.ANLYON_AGENT_KEY! });

const { data } = await anlyon.actions.invoke('anlyon-smoke-test', { orderId: 'test_order_1', amount: 100 });
console.log(data!.id, data!.status, data!.grade); // inv_…, succeeded, acknowledged

const { data: receipt } = await anlyon.actions.effect(data!.effectId!);
console.log(receipt!.outcome, receipt!.grade);
```

Expected: `status` `succeeded`, `responseStatus` `200`, `grade` `acknowledged` (the provider accepted it and no read-back is declared). Report the invocation id to the user.

If the call fails, read `error.code` and use the `anlyon-troubleshooting` skill, or https://docs.anlyon.com/advanced/error-handling.md. Common at setup: `401 AUTHENTICATION_ERROR` (wrong or revoked key), `403 AUTHORIZATION_ERROR` (the message names the missing scope), `404` (the key belongs to another environment), `402 PAYMENT_REQUIRED` (an admin chooses a plan under **Settings → Plan & billing**).

To remove the test action, call `ops.actions.delete('anlyon-smoke-test')`. Deleting archives it, and the name stays taken in that environment.

### 7. Agent rules file

Append this block to the project's rules file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/anlyon.mdc` or `.github/copilot-instructions.md`). Append; do not overwrite.

```markdown
## Anlyon
- Agent side effects go through Anlyon actions (`actions.invoke`), not direct provider API calls.
- Keys come from `ANLYON_AGENT_KEY` / `ANLYON_OPERATOR_KEY`. Never print, log or commit a key or a provider credential.
- Actions reference credentials as `{{secret:NAME}}` or `{{connection:<integration>}}`; Anlyon resolves them at dispatch.
- `pending_approval`: wait for the decision, do not invoke again. `unknown`: may have happened, never retry; tell a person.
- Docs: https://docs.anlyon.com/llms.txt (append `.md` to any page URL)
```