identity.yaml

identity.yaml defines one identity: its name, the bags packed onto it, its traits and bounds, its harnesses, and references to its secrets. The file sits at the root of the identity’s directory, beside a gitignored .env. barry identity create scaffolds that directory under ~/.barry/identities/<name>/, or at the path --dir names, and writes inherits: base into the new file. Barry still reads a directory whose only config file carries the older name barry.yaml, and prefers identity.yaml when both exist.

The base identity is the identity.yaml at the root of the Barry repository, named base. It packs the foundational bags, sets default traits, and ships optional bounds. An identity that names base, or any other identity, under inherits starts from that parent’s definition and layers its own keys on top. Barry rejects the retired keys env and env_file with an error: declare credentials under secrets instead. See the base identity and the reader.

Overview

Every key identity.yaml accepts, with its type. Each key has its own section under Fields.

id: integer
inherits: string
secrets: map
  "<NAME>": map
    in: string  # required
    item: string
    field: string
    account: string
    key: string
name: string  # default <directory name>
displayName: string
aliases: list of strings
bags: list
  "<bag>": map
    extensions: list of strings
    store: map
    stores: map
    tools: list or map
traits: list
bounds: list
adapters: map
  "<harness>": map
    default: boolean
    model: string
    mode: string
tool_discovery: string  # default barry
bag_grant: string  # default session
status_notify: map
ui: string
bound: map
scope: map
github: map
vault: string

Fields

id

• Type: integer
• Required: no

The persisted numeric key of the identity. It keeps ownership attached to the identity when its name changes. The value must be a positive safe integer. Without it, Barry derives a temporary ID from a hash of the name, so renaming an identity that lacks an id changes its key.

id: 42

inherits

• Type: string
• Required: no

The name of the parent identity. The child starts from the parent’s definition: bags, traits, bounds, and secret declarations combine, adapter settings merge with the child’s winning, and the child’s other keys replace the parent’s. The parent’s vault never carries over. Barry reports an error when the parent does not exist or when inheritance forms a cycle. Without inherits, the file merges no parent definition.

inherits: base

secrets

• Type: map
• Required: no

Credential references, keyed by the environment variable name a session receives. A name starts with an uppercase letter and contains only uppercase letters, digits, and underscores. Each value names a source under in plus the fields that source needs; the file holds references only, never values. A child inherits its parent’s declarations, and a declaration with the same name in the child replaces the parent’s. See Secrets.

secrets:
  EXAMPLE_API_KEY:
    in: vault
    item: EXAMPLE_API_KEY
    field: password

secrets."<NAME>"

• Type: map
• Required: no

One reference. Barry rejects keys that the chosen source does not take.

secrets:
  EXAMPLE_TOKEN:
    in: keychain
    item: example-service
    account: example-account

secrets."<NAME>".in

• Type: string
• Required: yes
• Values: vault, .env, keychain

The source to read. vault reads an item from the identity’s vault, .env reads the .env file in the directory that declares the secret, and keychain reads a login Keychain item. An inherited .env reference reads the parent’s .env, not the child’s.

secrets:
  EXAMPLE_HOST:
    in: .env

secrets."<NAME>".item

• Type: string
• Required: no

The vault item or Keychain item to read. Required when in is vault or keychain.

secrets:
  EXAMPLE_API_KEY:
    in: vault
    item: EXAMPLE_API_KEY
    field: password

secrets."<NAME>".field

• Type: string
• Required: no
• Values: username, password, notes, uri

The field of the vault item to read. Required when in is vault, and accepted only there.

secrets:
  EXAMPLE_API_KEY:
    in: vault
    item: EXAMPLE_API_KEY
    field: password

secrets."<NAME>".account

• Type: string
• Required: no

The account of the Keychain item. Optional, and accepted only when in is keychain.

secrets:
  EXAMPLE_TOKEN:
    in: keychain
    item: example-service
    account: example-account

secrets."<NAME>".key

• Type: string
• Required: no

The entry to read from the .env file when it differs from the secret’s own name. The session still receives the secret under its own name. Optional, accepted only when in is .env, and spelled like a secret name.

secrets:
  EXAMPLE_HOST:
    in: .env
    key: STAGING_HOST

name

• Type: string
• Required: no
• Default: <directory name>

The identifier every command and config file uses for the identity, and the name of its command on PATH. Without it, Barry uses the name of the directory. The names base and barry belong to the base identity Barry ships.

name: bonanza

displayName

• Type: string
• Required: no

A human-readable name for the identity. Barry stores it as the identity’s display name, which a UI shows in place of name.

displayName: Bonanza

aliases

• Type: list of strings
• Required: no

Extra command names the identity answers to. Each one becomes a shim on PATH beside barry, so the identity directory stays self-contained rather than relying on a central registry. barry alias manages them.

aliases:
  - bz

bags

• Type: list
• Required: no

The bags packed onto the identity. Each entry is a bag name, or a mapping from one bag name to its configuration. Name an extension of a bag under its parent’s extensions rather than as <parent>/<name>. An identity combines its parent’s bags with its own. Barry warns about a file that still uses the pre-rename key blocks, because it reads no bags from it. See Packing bags.

bags:
  - memory
  - sessions:
      extensions: [search]

bags."<bag>"

• Type: map
• Required: no

The configuration of one packed bag. Child settings merge over the parent’s for the same bag.

bags:
  - memory:
      tools:
        - memory_search: deferred

bags."<bag>".extensions

• Type: list of strings
• Required: no

Extensions of this bag to pack along with it, by their short names.

bags:
  - sessions:
      extensions: [search]

bags."<bag>".store

• Type: map
• Required: no

Options for the bag’s default store: engine (sqlite), an absolute filepath, a url, and an app_url. filepath and url exclude each other. Declare store or stores, never both.

bags:
  - memory:
      store:
        filepath: /srv/barry/memory.db

bags."<bag>".stores

• Type: map
• Required: no

Store options keyed by store name, for a bag with more than one store. Each value takes the same keys as store.

bags:
  - memory:
      stores:
        default:
          engine: sqlite

bags."<bag>".tools

• Type: list or map
• Required: no
• Values: enabled, deferred, disabled

The visibility of the bag’s tools, keyed by tool name: a mapping, or a list of one-key mappings. disabled hides a tool, and deferred keeps it out of the initial tool list.

bags:
  - memory:
      tools:
        - memory_search: deferred

traits

• Type: list
• Required: no

The traits of the identity. A bare name makes a trait a default for every session, {<name>: {optional: true}} offers it for a session to select, and a name such as bash:no-bash picks a variant a bag ships. A name mapped to trait fields, with a required description, defines a new trait; a definition takes a bare name and cannot reuse a name that the parent or base identity already gives. See Traits.

traits:
  - coding
  - sessions:
      optional: true

bounds

• Type: list
• Required: no

The bounds of the identity, in the same entry forms as traits. A bare name makes every session carry the bound, and optional: true offers it for a session to select. A name mapped to bound fields defines a bound inline; the definition takes every bound field except name and requires description. See Bounds.

bounds:
  - readonly
  - bonanza-files:
      description: Keeps sessions out of key material
      files:
        deny: ["*.pem", "**/.ssh/**"]

adapters

• Type: map
• Required: no

The harnesses the identity runs, keyed by harness ID: antigravity, claude-code, codex, cursor, opencode, or pi, or another installed harness. Barry rewrites an alias of an installed harness to that harness’s ID. With several entries, exactly one sets default: true; with one entry, that entry serves as the default. A child’s settings merge over its parent’s, and a child default replaces the parent’s. Barry warns about the retired keys default_harness, default_coding_agent, default_model, default_model_provider, and allow_native_tools, and barry doctor --fix rewrites them under adapters. See Adapters.

adapters:
  codex:
    default: true
    mode: hosted

adapters."<harness>"

• Type: map
• Required: no

The settings for one harness. Barry rejects any other key. <identity> identity adapters set <harness> writes them.

adapters:
  opencode:
    model: qwen3:8b

adapters."<harness>".default

• Type: boolean
• Required: no

Makes this harness the one a session uses when no flag picks another. At most one harness sets it.

adapters:
  cursor:
    default: true

adapters."<harness>".model

• Type: string
• Required: no

The model this harness runs. A session flag overrides it.

adapters:
  opencode:
    model: qwen3:8b

adapters."<harness>".mode

• Type: string
• Required: no
• Values: hosted, instrumented, guest

The launch mode for this harness. See Session modes.

adapters:
  codex:
    mode: guest

tool_discovery

• Type: string
• Required: no
• Default: barry
• Values: provider, barry

How a session finds deferred tools. Under barry, the tool list leaves deferred tools out, and the agent finds them through tool_search and calls them through call_tool, which works on any MCP client. Under provider, the tool list includes every tool and the client handles deferral. The base identity sets provider, so an identity that inherits it starts there.

tool_discovery: barry

bag_grant

• Type: string
• Required: no
• Default: session
• Values: session, identity

Whether packing a bag grants its tools to every session. Under session, a packed bag offers its trait, and a session must select it. Under identity, the earlier behavior, every packed bag’s trait joins every session, even one that turns off all its traits.

bag_grant: session

status_notify

• Type: map
• Required: no

The default notifier for the record_event tool: tool names the existing tool the agent calls to deliver an event, and the optional target names where it goes, such as a Slack channel. Barry ignores the key when tool is absent. <identity> identity notifier set writes it.

status_notify:
  tool: send_slack_message
  target: "#example-channel"

ui

• Type: string
• Required: no
• Values: btui, web, app, raw, none

The renderer that attaches to a session. The --ui and --no-ui flags and the BARRY_UI variable take precedence over it, and without any of them Barry probes the terminal. The aliases browser, desktop, readline, terminal, and no-ui also work. Barry reports an error for any other value when a session starts.

ui: btui

bound

• Type: map
• Required: no

Legacy inline deny rules applied to every session, in the shape of a bound. Barry still reads the key and merges it into the session’s denials, but warns about it: barry doctor --fix moves the rules into a named entry under bounds. When a parent and child both set it, their rules combine.

bound:
  deniedTools: [Bash]

scope

• Type: map
• Required: no

The pre-rename spelling of bound, which Barry reads when bound is absent. Move its rules under bounds.

scope:
  deniedAccess: [write]

github

• Type: map
• Required: no

The GitHub App installation the identity answers for, as installationId, a number. The webhook receiver reads it to pick whose credentials handle an App event. <identity> identity github set writes it.

github:
  installationId: 12345678

vault

• Type: string
• Required: no

The name of the vault that holds the identity’s secrets. A name contains letters, digits, and dashes, and starts with a letter or digit; Barry rejects the retired inline vault connection. A child never inherits its parent’s vault, so an identity without one reads no vault items. Several identities can name one shared vault, and <identity> vault assign points an identity at one.

vault: bonanza

Examples

A minimal identity

What barry identity create bonanza writes: a name and the base identity as the parent.

name: bonanza
inherits: base

An identity with secrets and adapters

Packs bags, reads credentials from three sources, and runs two harnesses with one default. The item and account names are placeholders.

name: bonanza
inherits: base
id: 42
aliases:
  - bz
vault: bonanza
bags:
  - memory
  - slack
  - sessions:
      extensions: [search]
traits:
  - coding
  - slack:
      optional: true
secrets:
  SLACK_BOT_TOKEN:
    in: vault
    item: SLACK_BOT_TOKEN
    field: password
  EXAMPLE_HOST:
    in: .env
  EXAMPLE_API_KEY:
    in: keychain
    item: example-service
    account: example-account
adapters:
  codex:
    default: true
    mode: hosted
  opencode:
    model: qwen3:8b
status_notify:
  tool: send_slack_message
  target: "#example-channel"

An identity that inherits another

Starts from the bonanza identity, adds a bag, defines a trait inline, defines a required bound inline, and keeps a vault of its own.

name: bonanza-ops
inherits: bonanza
vault: bonanza-ops
bags:
  - schedules
traits:
  - ops-review:
      description: Reviews scheduled jobs without changing them
      access: read
      bags: [schedules]
bounds:
  - ops-files:
      description: Keeps sessions out of key material
      files:
        deny: ["*.env", "*.pem", "**/.ssh/**"]
  - no-network-write:
      optional: true
secrets:
  EXAMPLE_API_KEY:
    in: vault
    item: bonanza-ops/EXAMPLE_API_KEY
    field: password