PaperClipAI/doc/agent-configuration-yaml.md

Agent configuration YAML

Status: v1, compact editor updated October 29, 2026.

The Advanced tab at /:companyPrefix/agents/:agentRef/advanced edits an agent's settings as one YAML document. It covers the configuration tabs through their existing APIs. The database and resource services remain authoritative; this is not a file on the agent's computer or a harness-specific format.

Coverage

Settings surface	YAML location	Save behavior
Agent identity / profile	spec.name, role, title, icon, appearance, reportsTo, capabilities, metadata	Existing agent update, including avatar appearance and reporting relationships.
Harness / Runtime	spec.adapterType, adapterConfig, runtimeConfig, defaultEnvironmentId, budgetMonthlyCents	Existing adapter, environment, AI connection, heartbeat, run-policy and budget validation. Adapter-specific extensions are preserved.
Instructions	spec.instructions	Bundle mode, root, entry file, and editable text files. Managed files and entry revisions enforce concurrency preconditions; omitted files are preserved; null deletes a named file. Legacy prompt templates stay in Instructions unless explicitly supplied.
Skills	spec.skills	Desired skill keys and version pins, synchronized through the skills API.
Secrets & variables	spec.adapterConfig.env, adapterConfig["access.<ALIAS>"], spec.secrets	Environment values, secret references, API-delivery bindings, creation, rotation, metadata/status updates, and proposal decisions.
Tools	spec.tools	Direct connection installs, profile bindings and definitions, and agent-scoped policies. Inherited access remains in the Tools tab.
Channels	spec.channels, spec.channelOperations	Existing endpoint settings, communication instructions, execution defaults, resource selection, setup/credentials and lifecycle actions, creation, and identity revocation.
Permissions / Trust	spec.permissions	Agent creation, skill creation, task assignment, trust preset and full authorization policy, including allowed projects in authorizationPolicy.trustBoundary.projectIds.
API Keys	spec.apiKeys	Explicit create and revoke operations; key metadata remains in the API Keys tab. New tokens appear once outside the YAML.
Revisions	spec.revisions.restore	Restore an existing revision, as the only operation in a save; history remains in the Revisions tab.

Read-only information stays read-only: organization-wide inherited access, immutable history, binary instruction assets, live status/spend, and provider connection state. Interactive provider login/OAuth and approval flows still use their normal UI. The YAML can select existing accounts/connections and configure channel credentials; it cannot synthesize provider consent or export stored credential values. AgentMail provisioning remains owned by its connection flow.

Document contract

apiVersion: paperclip/v1
kind: Agent
spec:
  name: Codie
  role: engineer
  adapterType: codex_local
  adapterConfig:
    model: gpt-5
    cwd: /workspace/project
    env:
      SERVICE_TOKEN:
        type: secret_ref
        secretId: 11111111-1111-4111-8111-111111111111
        version: latest
  runtimeConfig:
    heartbeat:
      enabled: true
      intervalSec: 3600
  budgetMonthlyCents: 10000
  instructions:
    mode: managed
    entryFile: AGENTS.md
  skills:
    - paperclip
  tools:
    profiles:
      - profileKey: engineering

This illustrates the compact format; model, paths, and references depend on the installation. The default editor contains agent-specific settings and references. It does not embed company catalogs, inherited profile definitions, history, credential metadata, or instruction file contents. Empty commands, unset nullable fields, zero budget, empty maps/lists, and standard permission defaults are omitted. Unpinned skills use their key strings. Non-default values remain explicit.

apiVersion, kind, and spec are required. All settings inside spec are optional when editing an existing agent. Omission preserves the saved value, including omitted instruction files, tool subsections, channel settings, and permissions. To clear a value, supply its supported empty value explicitly: title: null, skills: [], tools: { profiles: [] }, or adapterConfig: {}. An explicit list replaces that list. An explicit adapter/runtime/metadata map replaces that map. The one adapter exception is hidden legacy promptTemplate: omission preserves it, and an explicit empty string clears it.

All settings remain expressible. Add an optional section when needed. Use the owning settings tabs to inspect instruction contents, available profiles, inherited access, API key metadata, secret proposals, and revision history. A supplied legacy observed block is read-only; remove it before editing an old export. Unknown fields remain errors. Open adapter/runtime/metadata maps retain their existing extension contracts. Future incompatible changes require a new API version.

Executable contracts: core document and resource sections. Resource inputs reuse the owning APIs' validators, including trust-policy, secret, channel, skill, and tool validators.

Resource semantics

Instructions and skills

instructions.mode is managed, external, or null for an unconfigured bundle. external requires an absolute rootPath. File names and entryFile are relative paths; traversal and absolute file names are rejected. File contents are omitted from the default YAML. The Instructions tab owns normal content editing. To edit a file inline, add files: { workflow.md: "text" } under instructions; only named files are changed. Each text value supports up to 1 MiB. Use files: { workflow.md: null } to delete that file. Omitted files and an empty files: {} are preserved. The entry file cannot be removed. Binary/read-only/virtual files remain visible in Instructions. A legacy virtual prompt template can still be edited explicitly with adapterConfig.promptTemplate. It is hidden by default and preserved when another adapter setting changes. Managed root paths are assigned by Paperclip and omitted from the default YAML.

Changing the mode, root, or entry file is a separate save from editing file contents. That save loads the destination files without writing the old YAML's contents over them. The native bundle service may seed an empty destination or a missing entry file from the previous bundle. Review the freshly loaded files before editing them. A managed root is assigned by Paperclip; choose external mode to select another directory.

Skills accept a key string or { key, versionId }; versionId: null follows the current version. An empty list unassigns skills through the normal sync API. These keys are organization-library references, not embedded skill source.

The instructionsBundleMode, instructionsRootPath, instructionsEntryFile, instructionsFilePath, and paperclipSkillSync adapter keys are represented by the dedicated sections. Direct edits to those adapter keys are rejected so two sections cannot disagree about the same setting.

Tools

tools.connections contains only selected direct agent installations. Each row has connectionId; omitted installed means true. Use installed: false or remove a row from an explicitly supplied list to uninstall. Inherited company installations remain in Tools. Removing a direct installation row has the same effect as installed: false. Saves preserve other agents' installations. Company installations cannot be overridden here. The installation service can add an access profile and binding for an installed connection. The compact reload references those generated profiles by key.

Existing profiles normally use a reference: { profileKey: engineering }. profileId is also accepted. If both are provided, they must identify the same company profile. Optional priority and metadata affect only this binding; omission preserves an existing binding or uses 100/null for a new one. A reference never updates the shared definition. Omit tools.profiles to preserve bindings; use profiles: [] to unbind all direct profiles.

To create a profile or explicitly edit its definition, supply:

profileId: null # null creates a profile; an existing ID binds/edits it
updateSharedDefinition: false
priority: 100
metadata: null
configuration:
  profileKey: engineering
  name: Engineering
  description: null
  status: active
  defaultAction: deny
  metadata: null
  entries:
    - selectorType: tool_name
      effect: include
      toolName: get_repository

The profile configuration uses the native profile/entry schema. Profiles can be shared: editing a profile's definition affects every binding to that profile. When other targets share it, changes to the definition require explicitly setting updateSharedDefinition: true. The flag resets after reload; changing only the flag does not write anything. Binding an unchanged shared definition does not require the flag. Use profileId: null for a separate profile. Removing a profile row from an explicitly supplied list only unbinds it from this agent. Available profile definitions remain in Tools.

Keep existing profile and policy fields explicit. Removing a field from an existing definition is rejected because the native PATCH would otherwise preserve its old value. Use the field's supported empty value to clear it.

Policies use { id, configuration }, with id: null creating a policy. Configuration includes name, description, policyType, priority, enabled, selectors, conditions, and config. Policies in this section must target only this agent; newly created policies are scoped to it. Removing a row deletes that agent-scoped policy. Shared/inherited policies remain read-only in Tools.

Channels

Each channels row has immutable id; provider can be omitted or must match the saved provider. Omitted settings and resources preserve their saved values. Settings follow the native endpoint update contract: executionDefaults, communicationInstructions, allowUnlinkedPeople, allowDirectMessages, requireAtMention, allowGroupChats, slackApp, and slackSetupMethod, where applicable. Omitted settings fields are preserved; an explicit empty value clears a field where its native API supports it. Resources contain { id, enabled, executionDefaults }; removing a resource row disables it. Removing a channel row removes the endpoint using its existing setup API.

channelOperations.create accepts the native creation fields (provider, optional applicationId, name, slackApp, slackSetupMethod); the current agent ID is supplied by the editor. Save creation first to obtain its endpoint ID before adding setup commands. setup accepts { id, input }, where input has an action (configure, verify, pause, resume, reconnect, remove) and optional credentials or Photon configuration. revokeIdentityLinks accepts { endpointId, principalId }. Provider authorization is still enforced by the channel service. IDs, resources, linked people, and state are available in the Channels tab.

An endpoint cannot be removed and also edited, configured, or have its identities revoked in the same save. Duplicate setup commands and identity revocations are rejected before any writes.

Secrets, API keys, and revisions

Use secret_ref and user_secret_ref bindings for existing credentials. secrets.create accepts { secret, bind: { env: [], api: [] } }; secret follows the create-secret contract (name/key, provider, value or external reference, provider configuration and metadata). After creation, bind can attach its ID to environment names or API aliases. An empty bind creates without attaching. rotate and update accept { id, input } using their native contracts. proposals accepts { id, decision: approve|reject, reason? }; rejection requires a reason. Secrets and pending proposals remain in Secrets & variables.

New secrets must use distinct binding targets. A target cannot also be edited in adapterConfig in the same save. Binding targets are checked again before creation and before the revision-guarded binding update. If creation succeeds but binding fails, the receipt identifies the created secret; reload before deciding how to bind it.

apiKeys.create accepts { name, scope }; scope uses the existing agent key schema, with { kind: standard } as the default. apiKeys.revoke contains key IDs. Tokens returned by creation appear outside the YAML and are not stored in the configuration query cache. Copy them before leaving the page. Previously issued tokens cannot be retrieved. Duplicate creation names within one save are rejected.

revisions.restore accepts an existing revision ID or null. Restore must be the only change in that save. It uses the same rollback operation as the Revisions tab and restores only the fields covered by that revision; it is not a rollback of all external resources.

Empty operation lists are omitted after a successful save/reload. Commands are not replayed from history. Read-only history and catalogs are excluded from YAML. Lifecycle commands for the agent itself (pause, resume, terminate) are actions outside configuration.

YAML, secrets, and save guarantees

The parser accepts one YAML 1.2 mapping containing JSON-compatible values. Duplicate keys, multiple documents, aliases, anchors, explicit tags, merge keys, non-string mapping keys, non-finite numbers, and prototype-related keys are rejected. Documents are limited to 8 MiB and 50 levels of nesting. Syntax errors include a location; schema errors identify a field path. There is no interpolation, shell evaluation, include directive, or parser file access. Comments and formatting are not persisted; saving/reloading regenerates YAML. Changing only comments or mapping order does not write resources. The editor shows No configuration changes and keeps Save disabled when the operation plan is empty, including when an optional section is omitted.

The initial core read checks configuration access before related resources are loaded. Failed reads are shown as errors, never substituted with empty resource lists. The editor validates document structure, known references, explicit clears, and conflicting operations before enabling Save. Expand the change summary to review the ordered operations, including removals and shared profile edits. Domain-specific authorization, validation, and normalization still run at each API write; not every server rejection can be predicted in the browser.

Saving refreshes the snapshot before the first mutation. A changed core revision or an edited resource section that has changed elsewhere rejects the save. Concurrent changes to untouched resource sections are preserved. These are preflight checks, not a transaction spanning all resources.

Core changes use PATCH /api/agents/:id with expectedConfigurationRevision, checked again under the row lock. Removing an adapter key uses replaceAdapterConfig: true. The opaque revision uses a domain-separated HMAC with the instance's private signing key. Credential edits invalidate an open draft without exposing a public credential digest. Rotating the signing key requires reloading open editors. Server processes for one instance must share that key. File-based rotation takes effect on the next revision calculation without a server restart. Managed instruction files and entry revisions enforce hash/revision preconditions. External supporting file writes/deletions do not enforce these preconditions. Other resources retain their own API guarantees; changes between preflight and an unversioned resource write are not atomically protected. Every mutation uses its existing company/actor authorization, approval, validation, audit and revision behavior.

A multi-resource save runs sequentially and is not atomic. On an interrupted save, the editor retains the draft, reports completed steps and the failing step, preserves any credential receipts, and disables Save until Reload saved. Reload reveals current state and clears pending operations so retrying cannot blindly duplicate a successful creation. A network failure may mean the last operation committed even when its response did not arrive. No writes are automatically retried. Double-clicking Save starts one operation, the editor and Reload are disabled during saving, and agent navigation is held until it settles. Dirty drafts use the agent page's unsaved-navigation guard. Closing the browser cannot cancel or roll back requests already sent.

A successful save reloads canonical state, clears command lists, and displays any normalization warnings returned by the server. CEO agents and agents that can create agents must explicitly retain task assignment authority.

Stored inline credentials use ***REDACTED***. An unchanged marker at its original location preserves its saved value. Removing the key removes that setting; replacing the full value supplies a new value under normal validation. For revision-guarded core saves, the server restores unchanged masked subtrees before validation; moved/partially edited redactions are rejected. Secret references are never resolved into values. New secret/channel credential inputs are one-time commands and disappear after canonical reload. This document is an editable settings view, not a portable credential backup.

No background polling, database migration, or new authorization bypass is introduced by the editor.

Verification

Run the browser acceptance suite against its disposable checkout instance:

pnpm exec playwright test --config tests/e2e/playwright.config.ts tests/e2e/agent-configuration.spec.ts

The suite checks compact output with large company catalogs and instruction files, sparse saves, profile-key bindings, resource saves and explicit clears, one-time key receipts, secret redaction, stale drafts, a lost creation response, instruction relocation, and revision restore through real APIs. It enables and restores the Beta skills and chat connector flags. Its local MCP fixture provides a connection target; it does not qualify provider login or agent execution.

The lifecycle regressions can use a dedicated external PostgreSQL database when embedded PostgreSQL is unavailable. Set PAPERCLIP_AGENT_LIFECYCLE_TEST_DATABASE_URL to a database ending in _test before running server/src/modules/agent-lifecycle/__tests__/lifecycle.test.ts.