Agents

Create and update durable Agents by committing a manifest and running ccp apply -f agent.yaml. Keep the manifest as the source of truth.

ccp agent manages existing Agents on the managed-agents service. The server owns all validation — membership, model, tools, reasoning effort — so on a 400 the CLI passes the server's message through unrewritten; read it, it names valid values.

Commands

ccp agent list

ccp agent list [--org-id <org>]

Alias: ccp agent ls.

Lists the organization's agents: id, name, model, version, definition source, and last-updated time. Archived agents still appear, flagged with an archived marker.

ccp agent get

ccp agent get <agent_id> [--version <number>]

Prints the full definition: model, reasoning effort, tools, MCP declarations, metadata, version, definition source, timestamps, and system prompt. Pass --version to render a specific historical snapshot; omit it for the current definition. An archived agent's entry includes an archived marker with its timestamp. Unknown or inaccessible (cross-org) IDs return the server's 404 untouched — the CLI does not need an org context to run get, since the agent is addressed directly by ID.

ccp agent versions

ccp agent versions <agent_id>

Lists every persisted definition snapshot, oldest first, with the latest marked current. Each entry shows the version, name, model, and update time. Like get, it needs no org context.

ccp agent delete

ccp agent delete <agent_id> [--yes]

Permanently deletes an agent, every version, and its dependent runtime history. The command asks for confirmation first; pass --yes to skip the prompt. It works on any customer-owned agent: for an applied agent it also removes the manifest binding, so a later ccp apply of the same file creates a fresh agent id starting at version 1.

ccp apply

ccp apply -f <manifest.yaml> [--org-id <org>] [--dry-run] [--json]

Applies a declarative resource manifest — one Agent document and its optional Deployments and schedules, parsed locally as YAML, JSON, or TOML and sent unchanged to the server, which owns validation and reconciliation. Files ending in .toml are parsed as TOML (malformed TOML never falls back to YAML); every other filename is parsed as YAML/JSON. The server reports whether the Agent was created, updated, or left unchanged, along with its version and (on update) the changed fields, followed by a created, updated, unchanged, or deleted result for each of its Deployments and schedules. --dry-run runs the same validation and diff without persisting anything. --json prints the complete apply receipt as JSON instead of the text summary.

An Agent manifest looks like:

apiVersion: agents.clusterbase.ai/v1
kind: Agent
metadata:
  name: release-notes
spec:
  name: Release Notes
  model: claude-sonnet-5-5
  system: |
    Write concise release notes.
  tools:
    - web_search
  mcp_servers: []
  skills:
    - skill_id: existing-skill-id
      version: 2
  reasoning_effort: low
  metadata:
    team: platform
  deployments:
    - name: weekday-build
      kickoff: Build and test the repository.
      vault_ids:
        - vlt_publisher
      environment:
        type: ephemeral
        template_id: development
        repos:
          - url: octocat/Hello-World
  schedules:
    - name: weekday-summary
      cron: "0 9 * * 1-5"
      timezone: America/Los_Angeles
      deployment: weekday-build
      enabled: true

The same document in TOML uses [metadata] and [spec] tables, with [[spec.deployments]] and [[spec.schedules]] for children.

metadata.name is the stable organization-scoped identity; changing spec.name only changes the display name. It must be a lowercase DNS label — lowercase letters, digits, and dashes, starting and ending with a letter or digit, 1–63 characters — so release-notes is valid while Release Notes and release_notes are rejected with a 400. spec.name is free-form.

Applied agents remain runnable but must be edited by reapplying their manifest, not through imperative patch or archive calls. Additional YAML documents in the file are rejected locally, before any request is made; unknown fields are rejected by the server.

To keep a system prompt in its own Markdown file, replace spec.system with spec.system_file: prompt.md (YAML) or system_file = "prompt.md" under [spec] (TOML). CCP resolves the path relative to the manifest's directory, reads it as UTF-8 verbatim, and sends it as system — the server never sees system_file. Apply and dry-run fail locally, before any request, if the file is missing or unreadable, the path is invalid, or both system and system_file are set. ccp delete drops the local system_file reference without reading the file, so deletion still works after the prompt file is gone.

Deployment and schedule names are stable within the Agent. Omitting spec.deployments leaves existing applied Deployments untouched; a present list is authoritative, and deployments: [] removes them only when no preserved schedule still references one. A Deployment supplies its kickoff, an optional vault_ids list, and either an HTTP-only execution lane (no environment) or a fresh ephemeral VM with an optional validated template and repository list. Saved environment IDs, secret environment variables, and private scheduled-repository credentials are not accepted yet.

vault_ids references private vaults you own — never credential values; credentials resolve server-side when the run executes. IDs are deduplicated and capped like imperative Deployment CRUD, and an unknown or another actor's vault id fails the whole apply with an opaque 404, including on --dry-run. A Deployment with vaults must be applied by the Agent's durable execution owner. Reapplying updates vault bindings atomically with the Deployment and its schedules; omitting vault_ids from a declared Deployment clears its bindings.

Omitting spec.schedules leaves existing applied schedules untouched; a present list is authoritative, and schedules: [] explicitly removes all schedules managed by that Agent manifest. A schedule sets exactly one of kickoff (HTTP-only) or a manifest-local deployment name. Imperative and boot-managed resources are never pruned by apply.

An ephemeral Deployment's environment.template_id accepts development (the default) or desktop, for scheduled work that needs a graphical session; browser isn't available for ephemeral Deployments.

spec.skills pins exact, immutable revisions from the organization's Skills library — up to 16 distinct { "skill_id", "version" } references, each pointing to a version that must exist and be global or belong to the Agent's organization. Omitting skills preserves the Agent's currently selected revisions; an empty skills: [] detaches them; skills: null is rejected. Invalid or inaccessible pins reject the whole apply, including --dry-run, before anything is persisted. A pin change appears as spec.skills in the changed fields and creates a new Agent version; publishing a new library version never changes an already-applied selection.

Local skill directories

Instead of a catalog pin, an entry can package a local directory: spec.skills: [{ path: ./skills/news-writing }] in YAML, or [[spec.skills]] with path = "./skills/news-writing" in TOML. The path is relative to the manifest, must stay inside the manifest directory, and may not contain symlinks. The directory must contain SKILL.md with name and description YAML frontmatter plus instructions; supporting files are included with their executable flags, and nothing is run during packaging. Python caches, .git, and .DS_Store are excluded. Each bundle allows 128 files and 8 MiB, and all bundles together allow 16 MiB. An entry with path can't also carry a catalog pin.

Invalid paths, symlinks, malformed frontmatter, oversized bundles and ambiguous declarations fail locally before any request. --dry-run reports the planned skill IDs, immutable versions and content digests without writing. A real apply previews the bundles first, then saves the skills and Agent pins atomically with the expected versions; a concurrent edit rejects the apply, so preview and retry. Reapplying unchanged files reuses the existing revision, while changed or removed files create a new snapshot. ccp delete doesn't need the local skill files, and immutable revisions stay available to other Agents. Manifest-owned skills can only be changed through ccp apply. Skills grant no tools or credentials.

Memory stores and bindings

spec.memory_stores declares memory stores owned by the manifest, and spec.memory_bindings grants this Agent read-only or read-write access to a declared or existing store:

spec:
  memory_stores:
    - name: knowledge
      description: Research findings retained across runs
  memory_bindings:
    - store: { type: declared, name: knowledge }
      access: read_write
    - store: { type: existing, id: existing-store-id }
      access: read_only

A declared store's name is a lowercase DNS label, unique within the manifest, and doubles as the store's display name — renaming it creates a new declaration and retains the old store rather than renaming in place. Omitting spec.memory_stores or spec.memory_bindings preserves the current declarations and bindings; an explicit [] detaches the manifest's bindings without deleting any documents, and removing an Agent retains its stores so a later apply of the same manifest identity reclaims the same store IDs. A manifest may declare at most 100 stores and bind at most eight. Deleting a store is a separate, explicit operation, and apply never recreates it: re-applying a deleted store's declaration name is rejected, so declare a new name instead.

ccp delete

ccp delete -f <manifest.yaml> [--org-id <org>] [--dry-run]

The declarative counterpart of ccp agent delete, addressed by manifest binding instead of id. --dry-run shows what would be deleted without persisting anything.

Headless use

apply, manifest delete, and list accept --org-id (or the CCP_ORG_ID environment variable) to skip the interactive organization picker. get and versions need no org context — they address the agent by ID directly. agent delete takes --yes to skip the confirmation prompt.

API errors include the server's request_id; quote it when reporting a failure.

Endpoint

Commands talk to the managed-agents service, resolved from CCP_API_URL (production is pinned to https://agents.clusterbase.dev; staging derives managed-agents.<base>). Set CCP_AGENTS_API_URL to override the derivation for bespoke clusters.