Overview

Define your Roark agents, personas, flows, metrics, collectors, and alerts as YAML in git and deploy them with one apply

Config as Code lets you define your Roark resources - agents, personas, simulation flows, custom metrics, collectors, and alerts - as YAML files in your own git repository, then deploy them with a single apply. Your config repo is the source of truth: Roark reconciles the live project to match what you submitted, creating what’s new, updating what changed, and removing what you deleted.

Quickstart

Put each resource in a YAML file under a directory, then apply. Install the CLI and set ROARK_API_BEARER_TOKEN first (the key needs config:apply).

roark/agents/frontdesk.yaml

kind: agent
name: frontdesk

roark config diff ./roark    # preview the changes
roark config apply ./roark   # apply them

That’s the whole loop. Add personas, flows, metrics, collectors, and alerts the same way; each kind has its own reference page below.

---

Config as Code manages resource definitions. It does not run simulations or place calls; you trigger those as usual once the resources exist (see CI/CD to apply config and start a run in one pipeline).

You write only a human-readable name for each resource. Roark derives a stable identity (configKey = <kind>/<name>) and resolves cross-references by name, so there are no UUIDs in your files and no state file to keep in sync.

Use the Roark CLI

The easiest way to run Config as Code. roark config diff ./roark and roark config apply ./roark bundle your directory (resolving file:// prompts) and submit it for you. See the CLI page for install, auth, and a CI example.

---

How it works

You submit the full desired set of resources to a single endpoint. Roark:

1. Parses and validates every resource against the schema.
2. Diffs the submitted set against the resources this project already manages via config.
3. Reconciles: creates new resources, updates changed ones, and (unless you opt out) deletes config-managed resources you removed from the submission.

There are two endpoints:

Endpoint	What it does
POST /v1/config/diff	Dry run. Returns the changes that would be made. No writes.
POST /v1/config/apply	Applies the changes and returns what happened.

Always run diff first to preview the changes, then apply.

---

Prerequisites

• A Roark API key with the config:apply permission. Generate one from API Keys and confirm it carries config:apply.
• A git repository to hold your config files (any layout; Roark reads the files you submit).
• The Roark CLI (recommended): npm install -g @roarkanalytics/cli, or run it on demand with npx @roarkanalytics/cli. The CLI builds the bundle from your config directory and drives diff/apply for you, so it’s the easiest way to deploy. Raw HTTP and the SDKs work too.

The API key is scoped to a single project. Everything you apply lands in that project.

---

Repository layout

One file per resource, discriminated by kind. A conventional layout:

roark/
  agents/frontdesk.yaml
  personas/frustrated-caller.yaml
  flows/frustrated-rebooking.yaml     # improv flow
  flows/booking-scripted.yaml         # scripted-graph flow
  metrics/refund-policy-accuracy.yaml
  collectors/consent-on-frontdesk.yaml
  alerts/high-frustration.yaml        # threshold / event / simulation alert
  prompts/escalates-to-manager.md     # referenced by file://

Add this header to any resource file for editor autocomplete and validation:

# yaml-language-server: $schema=https://roark.ai/roark-config.schema.json

---

Resource kinds

One file per resource, discriminated by kind. Each kind has its own reference page with fields and examples:

Agents

Voice agents and their phone endpoints.

Personas

The simulated caller for a flow.

Flows

Simulation flows: improvised or scripted graphs.

Metrics

Custom LLM-judged metric definitions.

Collectors

Which metrics get collected on which conversations.

Simulation plans

Saved, repeatable simulation runs: agents, flows and the metrics that grade them.

Alerts

Alerts (monitors): threshold, event, and simulation triggers.

For the full field reference of every kind, see the Config DSL reference schema.

---

Deploying

The easiest way to deploy is the Roark CLI. Point it at your config directory and it builds the bundle for you (reading every YAML file and inlining file:// prompts), so there is no JSON body to assemble by hand.

The CLI does the bundling for you: roark config diff ./roark and roark config apply ./roark take the directory directly, resolve file:// prompt references, and submit the result. The raw requests below are what it sends.

1. Authenticate

   Give the CLI the project API key that carries config:apply:

   export ROARK_API_BEARER_TOKEN="<your-config-apply-key>"
   # or store it once: roark auth login
   
2. Preview the changes

   roark config diff ./roark
   

   The CLI reads every resource under ./roark, builds the bundle, and prints one line per change (+ create, ~ update, - delete) with a tally:

     + collector/consent-on-frontdesk
     ~ agent/frontdesk
   
   1 to create, 1 to update, 0 to delete
   

   Resources already in sync are no-ops and aren’t listed, so a project that fully matches your config prints 0 to create, 0 to update, 0 to delete.

3. Apply

   roark config apply ./roark
   

   apply previews the same diff, asks you to confirm, then reconciles and reports what it did. Pass --yes to skip the prompt in CI, and --no-prune for an additive-only apply that never deletes.

Using raw HTTP

If you’d rather call the API directly, bundle your resources into a single JSON body: { "resources": [...], "prune": true }, where each entry is one resource in the same shape as its YAML. POST it to /v1/config/diff first, then /v1/config/apply.

curl -X POST https://api.roark.ai/v1/config/diff \
  -H "Authorization: Bearer $ROARK_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @bundle.json

The response lists each projected change with an op (create, update, or delete) plus a summary; in-sync resources are counted in summary.noop and omitted from changes:

{
  "data": {
    "changes": [
      { "configKey": "collector/consent-on-frontdesk", "kind": "collector", "name": "consent-on-frontdesk", "op": "create" }
    ],
    "summary": { "create": 1, "update": 0, "delete": 0, "noop": 0 }
  }
}

apply takes the same body against /v1/config/apply; each change comes back with a status (applied or failed) and, on success, the resource id.

These endpoints are available in the Node.js and Python SDKs as config.diff and config.apply, taking the same bundle, and in the CLI as roark config diff and roark config apply, taking a directory.

---

Apply semantics

• Identity is by name. Re-submitting an unchanged resource updates it in place; it never creates a duplicate. Renaming a resource is a delete of the old name plus a create of the new one.
• Cross-references resolve by name within the same submission (a flow’s agents:/persona:, a collector’s AGENT filter). The referenced resource must be in the bundle or already config-managed in the project.
• Prune deletes what you removed. By default, config-managed resources absent from the submission are deleted so the project matches your repo exactly. To layer additive changes without deleting, send "prune": false.
• Prompts are code. Any prompt field takes an inline string or file://relative/path.md, resolved relative to your config root and inlined before you submit.
• Idempotent. Applying the same bundle twice converges to the same state. An unchanged resource is a no-op on the next diff/apply, not a rewrite, so a re-run of an in-sync project reports no changes.

With prune enabled (the default), a resource you delete from your repo is deleted from Roark on the next apply. Submit the full desired set every time, or use "prune": false for additive-only applies.

---

Config-managed resources in the UI

A resource created by config is read-only in the dashboard and carries a “managed by config” badge. To change it, edit your config and re-apply.

If you need to hand a resource back to manual UI editing, detach it (from the resource’s menu in the dashboard). Detaching clears its config ownership:

• A later apply that still lists it will re-adopt it.
• A later apply that omits it will simply leave it alone (it is no longer config-managed, so prune won’t touch it).

---

Recommended workflow

1. Keep your roark/ config in a git repo, reviewed via pull requests.
2. In CI, run roark config diff ./roark on every PR and post the output for review.
3. On merge to your main branch, run roark config apply ./roark --yes.

Both CI steps read the API key from ROARK_API_BEARER_TOKEN (store it as a secret with config:apply). This gives you versioned, reviewable, reproducible Roark resources with a full audit trail in git.

For a copy-pasteable GitHub Actions workflow that does exactly this, see Using the CLI in CI.