BEHAVIOR DEFINITIONS

A behavior definition is a YAML file that configures an instance of a behavior type. Definitions are stored in one of two locations depending on how they are created.

To inspect a behavior type's methods, arguments, and output specs before creating a definition, see behavior type describe below.

Commands spelled with the earlier model noun still work; see Compatibility with model commands.

Definition Storage

models/ (via behavior create)

swamp behavior create command/shell my-shell --global-arg prefix="swamp says"

Definitions created with behavior create are stored in models/{type}/{name}.yaml. They are git-tracked and included in behavior search results.

models/
  command/
    shell/
      greeter.yaml
      my-shell.yaml

The directory path encodes the behavior type. The filename is the definition's name; a name that is not filename-safe, and a file written by an older release, uses the definition's UUID instead.

.swamp/auto-definitions/ (via direct type execution)

swamp behavior run @command/shell execute my-shell --input 'run=echo hello'

When a definition with the given name does not exist, one is created automatically in .swamp/auto-definitions/{type}/{name}.yaml. On subsequent runs, the existing definition is reused after verifying the type matches. --input values are split between global arguments and method arguments using the type's schemas — method arguments take precedence on ambiguous keys. Unknown keys are rejected with an error listing valid inputs.

.swamp/
  auto-definitions/
    command/
      shell/
        my-shell.yaml

The same directory and filename conventions apply. Auto-definitions are not git-tracked and are not included in behavior search results. They are findable by behavior get and are included in DEFAULT_DATASTORE_SUBDIRS for datastore sync.

Comparison

Top-Level Fields

type: command/shell
typeVersion: 2026.02.09.1
id: 83e5906c-3d3f-4ffe-84f9-5e01f6e9037c
name: hello-world
version: 1
tags: {}
globalArguments: {}
methods: {}

Optional fields omitted above: inputs, checks, reports. These appear in the YAML only when explicitly set.

type

Behavior type identifier.

The type value is normalized to a lowercase, slash-delimited path. Swamp applies these transformations:

• AWS::EC2::VPC → aws/ec2/vpc
• docker run → docker/run
• Microsoft.Resources/resourceGroup → microsoft/resources/resourcegroup

Consecutive, leading, and trailing slashes are removed.

typeVersion

The behavior type version this definition's globalArguments were written or migrated for.

The behavior type's upgrade chain compares against this value. How it treats the definition depends on what is recorded:

A number is read as its string form, so typeVersion: 1 is recorded as "1" and fails the same way.

Only creating the definition and running an upgrade set typeVersion. Saving the definition for any other reason leaves it unchanged. To record the version for a definition that has none, add the line by hand with the version its globalArguments were written for.

swamp behavior get reports the recorded value alongside the installed behavior type's version and a staleness state.

id

Unique identifier for the definition.

name

Human-readable name for the definition.

Constraints:

• Minimum 1 character.
• Must be unique within the repository.
• Must not contain .., \, or null bytes (path traversal protection).
• / is only allowed in scoped names matching @[a-z0-9_-]+/[a-z0-9_-]+(\/[a-z0-9_-]+)* (e.g., @john/pod-inventory).

version

Definition version number.

Must be a positive integer. Incremented when the definition is modified. This tracks changes to the definition itself — it is separate from typeVersion, which tracks the behavior type schema.

tags

Key-value labels attached to the definition.

Tags flow to data produced by the definition and can be overridden at runtime with --tag key=value.

tags:
  env: production
  team: platform
  owner: alice

globalArguments

Shared arguments available to all methods.

Values can be any JSON-serializable type: string, number, boolean, object, array, or null. CEL expressions are supported using the ${{ }} syntax.

globalArguments:
  repo: systeminit/swamp
  retries: 3
  verbose: true
  computed: "${{ 'https://' + self.tags.domain }}"
  secret: "${{ vault.get('my-vault', 'api-key') }}"

globalArguments:
  repo_root: "${{ env.HOME }}/src/my-extensions"

Global arguments are validated against the behavior type's globalArguments schema (if one is defined) when the definition is validated. When the definition's typeVersion is behind the behavior type, validation first applies the type's upgrade chain to an in-memory copy and checks the upgraded arguments. Nothing is saved: the next method run performs the upgrade and writes the file. See Validation.

A global argument whose schema marks it sensitive must not be given a literal value. A literal is rejected when the definition is written — across behavior create, behavior edit, behavior run / workflow run auto-definitions, and the serve HTTP API — because it would be stored in cleartext in the definition YAML. The value must instead be a vault.get('<vault>', '<key>') expression. The write fails with:

Global argument 'apiKey' is marked sensitive and cannot be set to a literal value or a constant expression such as ${{ literal('...') }} — it would be stored in cleartext in the definition YAML. Store the secret in a vault and reference it with a vault.get expression, e.g. --global-arg "apiKey=${{ vault.get('my-vault', 'api-key') }}". If a stored definition already holds the value, run `swamp doctor secrets` to find it.

See the Vaults and CEL Expressions references for the expression syntax.

methods

Per-method argument overrides.

Each key is a method name. The value is a MethodData object:

methods:
  execute:
    arguments:
      run: "echo hello"
      timeout: 5000
      env:
        MY_VAR: value

MethodData

arguments values support CEL expressions. They are merged with the behavior type's method argument schema and validated at execution time.

When rollbackOnFailure is true, the method's data writes use deferred-latest commit semantics: writes are held in a staging area during execution and committed atomically when the method succeeds. If the method fails, all staged writes are discarded — no partial data is persisted.

methods:
  provision:
    arguments:
      count: 5
    rollbackOnFailure: true

inputs

JSON Schema definition for structured inputs that can be provided at runtime.

InputsSchema

Additional JSON Schema keywords are allowed and preserved.

JsonSchemaProperty

All fields are optional. Properties nest recursively for objects and arrays.

inputs:
  type: object
  properties:
    environment:
      type: string
      enum: [dev, staging, production]
    count:
      type: integer
      default: 1
    config:
      type: object
      properties:
        verbose:
          type: boolean
          default: false
      additionalProperties: true
  required:
    - environment

Input values are available in CEL expressions as inputs.*.

checks

Pre-flight check selection.

CheckSelection

require lists check names to include. skip lists check names to exclude. Checks run before mutating methods (create, update, delete, action). Check names must be defined by the behavior type.

checks:
  require:
    - validate-permissions
    - check-resources
  skip:
    - expensive-validation

reports

Post-execution report selection.

ReportSelection

A ReportRef is either a report name (string) or an object:

When methods is omitted, the report runs for all methods.

reports:
  require:
    - summary-report
    - name: detailed-analysis
      methods:
        - execute
  skip:
    - verbose-debug

A name in require that cannot be resolved to a loaded or installed report (missing extension pull, typo, broken bundle) logs a warning naming the report and the remedy, writes a searchable error artifact (visible via swamp report search), and counts as a report failure — swamp behavior run exits non-zero. A name in skip that also appears in require is exempted from the resolution check — skip wins over require.

resources

Per-resource overrides for the behavior type's resource output specifications.

Each key is the name of a ResourceOutputSpec declared by the behavior type. Use swamp behavior type describe <type> to list available spec names.

ResourceOverride

When vaultName is set, sensitive fields in this resource are stored in the named vault instead of the repo-level defaultVault or the first available vault. Field-level vaultName from schema metadata still takes precedence. See the vault resolution order for the full chain.

resources:
  credentials:
    vaultName: prod-secrets
  config:
    vaultName: dev-secrets

CEL Expressions

String values in globalArguments and methods.*.arguments support CEL expressions using the ${{ }} wrapper:

globalArguments:
  url: "${{ 'https://' + self.tags.domain }}"
  pool: "${{ model.config.definition.globalArguments.pool_size * 2 }}"
  secret: "${{ vault.get('infra', 'api-key') }}"

When the entire YAML value is a single ${{ }} expression, the result preserves its type. When mixed with surrounding text, the result is coerced to a string.

Template syntax that belongs to another service, such as Datadog {{host.name}} or GitHub Actions ${{ github.sha }}, is passed to the method unchanged. See Other Services' Template Syntax.

Context Variables

See the CEL Expressions reference for the full expression language.

Per-Behavior Method Locking

Concurrent swamp behavior run invocations on the same behavior definition serialize automatically. The engine acquires a per-behavior file lock before executing the method and releases it when the method completes, fails, or is cancelled. Different behavior definitions run in parallel — only runs targeting the same definition contend.

The lock uses a ~30-second TTL with a heartbeat. The executing process renews the lock periodically; if the process dies without releasing the lock, stale-lock detection checks whether the owning PID is still alive and reclaims the lock once the TTL expires. This prevents a crashed process from permanently blocking a behavior.

When a second run cannot acquire the lock within the timeout window, the CLI exits with code 75 and a lock_timeout error (see Exit codes and Error codes). The caller can retry with exponential backoff.

Breakglass: inspecting and releasing locks

If a lock is stuck — the owning process is gone but the TTL has not yet expired, or the PID check cannot reach the original host — use the datastore lock commands:

swamp datastore lock status                          # show who holds the lock
swamp datastore lock release --force                 # release the global lock
swamp datastore lock release --force --behavior <type/name>  # release a specific behavior's lock

See Operational Commands for the full flag reference.

Execution Cancellation

A running behavior method can be cancelled via swamp behavior cancel. Cancellation terminates the method run cooperatively and marks it as cancelled — a terminal status alongside succeeded and failed.

Commands

Signal-based cancellation

Pressing Ctrl+C (SIGINT) or sending SIGTERM during swamp behavior run cancels the running method. The CLI intercepts the signal, sends a cancel request, waits for the method to terminate cooperatively, and exits with a non-zero status.

Examples

$ swamp behavior cancel my-server
$ swamp behavior cancel --all
$ swamp behavior cancel my-server --reason 'No longer needed'

Validation

swamp behavior validate checks a definition against its behavior type schema:

$ swamp behavior validate greeter
Validating: greeter (command/shell)
  ✓ Definition schema
  ✓ Type version
  ✓ Global arguments
  ✓ Method arguments
  ✓ Expression paths
  ✓ Check selection
Summary: 6/6 validations passed
Result: PASSED

Omit the name to validate all definitions in the repository.

Validation rules:

• id must be a valid UUID v4.
• name must be at least 1 character, unique within the repository, with no path traversal sequences.
• version must be a positive integer.
• tags values must be strings.
• globalArguments must match the behavior type's global argument schema (if defined). See Upgrades during validation.
• A sensitive global argument must be a vault.get(...) expression, not a literal value.
• methods.*.arguments must match the behavior type's method argument schema.
• typeVersion must be valid CalVer (YYYY.MM.DD.MICRO) or absent. Any other value fails the Type version item, and method runs against the definition fail until it is corrected or removed.
• CEL expression syntax in ${{ }} wrappers must parse correctly.
• Expression paths must reference existing behaviors and valid schema paths. See Reported as errors for the failure output and its expressionErrors JSON.
• checks.require and checks.skip names must exist on the behavior type.

Upgrades during validation

swamp behavior validate, and the check that runs before each workflow step, apply the behavior type's upgrade chain before checking global arguments. The Global arguments item and pre-flight checks see the upgraded copy; every other item reads the definition as written. The definition file is not changed. The next method run applies the same upgrades and saves them.

$ swamp behavior validate boom-host
Validating: boom-host (@sb/up)
  ✓ Definition schema
  ✓ Type version
  ✗ Global arguments
    → Upgrading from typeVersion 2026.10.01.1 to 2026.10.01.2 failed: host 'boom' cannot be migrated
  ✓ Method arguments
  ✓ Expression paths
  ✓ Check selection
Summary: 5/6 validations passed
Result: FAILED

Complete Example

type: command/shell
typeVersion: 2026.02.09.1
id: 53274ce2-c390-412b-93ac-48b205a13f4e
name: greeter
version: 1
tags:
  env: dev
  team: platform
globalArguments:
  prefix: "swamp says"
methods:
  execute:
    arguments:
      run: "echo \"${{ self.globalArguments.prefix }}: hello!\""
inputs:
  type: object
  properties:
    name:
      type: string
      description: Name to greet
      default: world
  required:
    - name
checks:
  require:
    - validate-permissions
reports:
  require:
    - name: execution-summary
      methods:
        - execute

behavior type describe

swamp behavior type describe prints the schema of a behavior type — its methods, arguments, data output specifications, and version. It accepts a type identifier (e.g., command/shell, @swamp/issue-lifecycle) and renders a human-readable summary by default.

$ swamp behavior type describe command/shell
Type: command/shell
Version: 2026.02.09.1

Data Outputs:
  result [resource] - Shell command execution result (exit code, timing, command) (infinite)
  log [file] - Shell command output (stdout and stderr) (text/plain, infinite)

Methods:
  execute - Execute the shell command and capture stdout, stderr, and exit code
    Inputs:
      run (string) *required
      workingDir (string)
      timeout (integer)
      env (object)
      ignoreExitCode (boolean)

For the YAML definition layer that configures behavior instances, see Definition Storage above.

--json

Produces structured JSON output. The full JSON includes complete JSON Schema definitions for every method's arguments and every data output spec's schema.

$ swamp behavior type describe command/shell --json

{
  "type": {
    "raw": "command/shell",
    "normalized": "command/shell"
  },
  "version": "2026.02.09.1",
  "dataOutputSpecs": [
    {
      "specName": "result",
      "kind": "resource",
      "description": "Shell command execution result (exit code, timing, command)",
      "schema": { ... },
      "lifetime": "infinite",
      "garbageCollection": 10
    },
    {
      "specName": "log",
      "kind": "file",
      "description": "Shell command output (stdout and stderr)",
      "contentType": "text/plain",
      "lifetime": "infinite",
      "garbageCollection": 10,
      "streaming": true
    }
  ],
  "methods": [
    {
      "name": "execute",
      "description": "Execute the shell command and capture stdout, stderr, and exit code",
      "arguments": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "run": {
            "type": "string",
            "minLength": 1,
            "description": "The shell command to execute"
          },
          ...
        },
        "required": ["run"],
        "additionalProperties": false
      }
    }
  ]
}

Full JSON shape

Each dataOutputSpecs entry includes the complete JSON Schema for resource specs, or contentType and streaming fields for file specs.

Each methods entry includes the full JSON Schema for that method's arguments, including description, type constraints, and validation rules for every property.

--compact

Produces a minimal digest suited to agent discovery. Strips full JSON Schema definitions down to property names and types, and reduces data output specs to names only.

$ swamp behavior type describe command/shell --compact --json

{
  "type": {
    "raw": "command/shell",
    "normalized": "command/shell"
  },
  "version": "2026.02.09.1",
  "dataOutputSpecs": [
    "result",
    "log"
  ],
  "methods": [
    {
      "name": "execute",
      "description": "Execute the shell command and capture stdout, stderr, and exit code",
      "arguments": {
        "properties": {
          "run": { "type": "string" },
          "workingDir": { "type": "string" },
          "timeout": { "type": "integer" },
          "env": { "type": "object" },
          "ignoreExitCode": { "type": "boolean" }
        },
        "required": ["run"]
      }
    }
  ]
}

Compact JSON shape

The compact form omits JSON Schema metadata ($schema, description, minLength, additionalProperties, constraints) from method arguments, and replaces full data output spec objects with their specName strings.

behavior type search

swamp behavior type search searches for behavior types available in the repository's installed extensions.

swamp behavior type search [query]

$ swamp behavior type search shell

Returns matching behavior types with their version and description. Use --json for structured output.

CLI Commands

swamp behavior create

Create a new behavior definition.

swamp behavior create <type> <name>

Creates a definition file in models/{type}/{name}.yaml. See Definition Storage for the directory layout.

$ swamp behavior create command/shell greeter --global-arg prefix="swamp says"

swamp behavior get

Show details of a behavior definition.

swamp behavior get <behavior_id_or_name>

Use --json for structured output. Resolves definitions from both models/ and .swamp/auto-definitions/.

--json

Produces structured JSON including the definition's configured method argument overrides. Sensitive argument values are redacted in the output.

$ swamp behavior get my-behavior --json

{
  "id": "50ca8807-6c4e-4362-b9da-863536edca3b",
  "name": "my-behavior",
  "type": "command/shell",
  "typeVersion": "2026.02.09.1",
  "currentTypeVersion": "2026.02.09.1",
  "staleness": "current",
  "methods": [
    {
      "name": "execute",
      "description": "Execute the shell command",
      "arguments": { ... }
    }
  ],
  "configuredMethods": {
    "execute": {
      "arguments": {
        "prefix": "swamp says"
      }
    }
  }
}

JSON shape

methods reflects the type-level schema (available arguments, types, and constraints). configuredMethods reflects the definition-level overrides — the values set in methods.<name>.arguments in the definition YAML. When a definition does not configure any method arguments, configuredMethods is absent from the output.

Staleness

Without --json, the output shows Type Version (not recorded when absent), adds Current Type Version when the two differ, and adds a note for the upgradable, stranded, and invalid states:

$ swamp behavior get old
...
Type Version: 2026.05.14.2
Current Type Version: 2026.06.01.1
  This instance is behind its behavior type and no upgrade entry covers the gap,
  so nothing will migrate it. The extension must ship a version upgrade.

swamp behavior search

Search behavior definitions in the repository.

swamp behavior search [query]

Returns definitions stored in models/. Auto-definitions in .swamp/auto-definitions/ are excluded. Use --json for structured output.

--json

Produces structured JSON with the full method signatures and global arguments schema for each definition. Each result includes the definition's methods with their complete JSON Schema arguments, enabling agent-driven discovery without a separate behavior type describe call per definition.

$ swamp behavior search --json

{
  "query": "",
  "results": [
    {
      "id": "50ca8807-6c4e-4362-b9da-863536edca3b",
      "name": "debug-task",
      "type": "command/shell",
      "methods": [
        {
          "name": "execute",
          "description": "Execute the shell command and capture stdout, stderr, and exit code",
          "arguments": {
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "type": "object",
            "properties": {
              "run": {
                "type": "string",
                "minLength": 1,
                "description": "The shell command to execute"
              },
              ...
            },
            "required": ["run"],
            "additionalProperties": false
          }
        }
      ]
    }
  ]
}

JSON shape

Each methods entry contains:

Results are per-definition, not per-type — the same behavior type appears once for each definition that uses it, with the same methods and globalArgumentsSchema on each. Use the name and id fields to distinguish definitions of the same type.

When searching against a remote swamp serve instance (--server), the output uses a leaner representation: method arguments are simplified to property names and types (similar to behavior type describe --compact), reducing payload size for network transfer.

swamp behavior edit

Open a behavior definition in $EDITOR, or replace it with YAML piped on stdin.

swamp behavior edit [behavior_id_or_name]
cat my-server.yaml | swamp behavior edit my-server

When the name is omitted, Swamp presents a selector. Run swamp behavior validate after editing to check the definition.

With --server, stdin is the only edit mode, because the editor cannot run on the server. Running it with nothing piped fails:

Error: 'swamp behavior edit' with --server needs the new YAML piped on stdin, because the editor cannot run on the server. For example: cat edited.yaml | swamp behavior edit <name> --server <url>

A definition whose stored YAML no longer parses must be fixed in an editor first.

swamp behavior delete

Delete a behavior definition and its related artifacts.

swamp behavior delete <behavior_id_or_name>

swamp behavior validate

Validate a definition against its behavior type schema.

swamp behavior validate [behavior_id_or_name]

When the name is omitted and --all is not set, Swamp presents a selector. See Validation above for the rules checked.

swamp behavior evaluate

Evaluate CEL expressions in a definition without executing any method.

swamp behavior evaluate [behavior_id_or_name]

Resolves all ${{ }} expressions in globalArguments and methods.*.arguments and prints the evaluated values.

swamp behavior cancel

Cancel a running method run.

swamp behavior cancel [behavior_id_or_name]

See Execution Cancellation for signal-based cancellation and examples.

Method Execution

swamp behavior run

Execute a method on a behavior. This is the single most important command in Swamp.

swamp behavior run <behavior_or_type> <method> [definition_name]

Values passed with --input, --input-file, and --stdin are evaluated as expressions: a ${{ vault.get(...) }} or ${{ env.* }} in them resolves, and the method receives the resolved value. Never pass untrusted text this way without --literal-inputs. See Behavior Run Inputs Are Evaluated.

Literal inputs

--literal-inputs treats every value passed with --input, --input-file and --stdin as data. Use it for text you did not write, such as issue bodies, tickets or scraped pages:

$ swamp behavior run github-pr update-body --literal-inputs --input-file body.json

With the flag:

• Values reach the method verbatim. Expression text in them stays literal, and Swamp logs a warning naming the path and the raw text, both in quotes. For --input 'run=${{ env.HOME }}':

  [WRN] swamp·expressions: Refusing to evaluate expression at "methods.execute.arguments.run": it was not written in the definition or workflow source, so it arrived as data content. Left as literal text. Raw: "${{ env.HOME }}"

• A value starting with @ is not read as a file path, and \@ keeps its backslash.

• The flag covers every input in the call, including vault.get(...) references, so put a secret in the definition rather than in an input.

• When running a behavior type directly (@type), an input routed to a global argument that holds expression text is refused rather than stored in the auto-definition. The error ends with:

  Write the expression into the definition itself, or pass the value as a method argument instead of a global argument.

• --last-evaluated cannot be combined with it:

  Error: --literal-inputs cannot be combined with --last-evaluated: the cached evaluation may hold expressions an earlier run's inputs vouched for.

• With --server, the client first asks the server whether it supports the flag. A swamp serve that does not advertise the literal-inputs capability would evaluate the inputs, so the run is refused:

  Error: The server (swamp <version>) does not support --literal-inputs, so it would evaluate expressions in the inputs. Upgrade swamp serve, or run without --server.

Exit codes

Error codes (JSON on stderr)

Example

$ swamp behavior run greeter execute
   Resolved   greeter (command/shell)
  Executing   execute · 04:04:21 UTC
              swamp says: hello!

  Completed   execute on greeter succeeded in 22ms · 04:04:21 UTC
...

$ swamp behavior run @command/shell execute my-shell \
    --input 'run=echo hello' --tag env=dev

swamp behavior describe

Describe a method with its arguments, types, and constraints.

swamp behavior describe <behavior_id_or_name> <method>

Use --json for the full JSON Schema of the method's arguments.

swamp behavior history get

Show details of a behavior method run.

swamp behavior history get <output_id_or_behavior_name>

When a behavior name is given, shows the most recent run for that behavior.

swamp behavior history search

Search method run history.

swamp behavior history search [query]

Use --json for structured output.

swamp behavior history logs

Show logs for a method run.

swamp behavior history logs <output_id_or_behavior_name>

Output Management

swamp behavior output get

Show details of a behavior output.

swamp behavior output get <output_id_or_behavior_name>

When a behavior name is given, shows the most recent output for that behavior.

Example

$ swamp behavior output get greeter
$ swamp behavior output get greeter --json

swamp behavior output search

Search behavior outputs.

swamp behavior output search [query]

Use --json for structured output.

swamp behavior output logs

Show log artifact content for an output.

swamp behavior output logs <output_id>

swamp behavior output data

Show data artifact content for an output.

swamp behavior output data <output_id>