Managing Fingerprints

Complete guide to initializing agent manifests and generating code fingerprints.

This guide covers agent manifest initialization and code fingerprinting using the Beltic CLI.

What are Fingerprints?

Code fingerprints provide tamper-evident verification that an agent's code hasn't changed since credential issuance.

How it works:

CLI generates SHA256 hash of all files matching include/exclude patterns
Fingerprint stored in agent manifest
Verifiers can regenerate fingerprint and compare
If fingerprints don't match → code was modified

Initializing Agent Manifests

Interactive Mode (Default)

beltic init

Interactive prompts:

Agent name: Aurora Refund Guide
Agent version: 2.3.0
Agent description: Conversational assistant for e-commerce refunds
Model provider: Anthropic
Model family: Claude-3 Opus
Context window: 200000
Deployment type: [standalone/monorepo/embedded/plugin/serverless]: standalone
Developer credential ID: d7aa92c7-8b07-4f35-8c9b-a2d02e26f012

Output:

✓ Manifest created: agent-manifest.json
✓ Generated fingerprint: sha256:f6d2...

Non-Interactive Mode

beltic init \
  --non-interactive \
  --output agent-manifest.json \
  --type standalone \
  --developer-id d7aa92c7-8b07-4f35-8c9b-a2d02e26f012

Uses defaults or values from .beltic.yaml

With Custom Configuration

beltic init \
  --config .beltic.yaml \
  --include "src/**" \
  --include "package.json" \
  --exclude "**/*.test.*" \
  --exclude "**/node_modules/**"

Force Overwrite

beltic init --force --output agent-manifest.json

Warning: Overwrites existing manifest without confirmation!

Configuration File (.beltic.yaml)

Create .beltic.yaml in your project root:

version: "1.0"

agent:
  # Basic info
  name: "Aurora Refund Guide"
  version: "2.3.0"
  description: "Conversational assistant for e-commerce refunds"

  # Files to fingerprint
  paths:
    include:
      - "src/**"
      - "package.json"
      - "tsconfig.json"
    exclude:
      - "**/*.test.*"
      - "**/*.spec.*"
      - "**/node_modules/**"
      - "**/.git/**"
      - "**/dist/**"
      - "**/build/**"

  # Dependencies
  dependencies:
    internal:
      - "@company/shared-utils"
      - "@company/api-client"
    external:
      - "anthropic@^1.0.0"
      - "express@^4.18.0"

  # Deployment
  deployment:
    type: "standalone"  # standalone, monorepo, embedded, plugin, serverless
    environment: "production"

Fingerprint Generation

Basic Fingerprint

beltic fingerprint

Uses:

Current directory as root
Patterns from .beltic.yaml or defaults
Updates agent-manifest.json automatically

Output:

Collecting files...
  Found 47 files
Generating SHA256 fingerprint...
  Fingerprint: sha256:f6d2a8b3c4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
Updated manifest: agent-manifest.json

Verify Mode (Don't Write)

beltic fingerprint --verify

Compares fingerprint without modifying manifest:

Current fingerprint:  sha256:f6d2...
Manifest fingerprint: sha256:f6d2...
✓ MATCH - Code unchanged

Or:

Current fingerprint:  sha256:a1b2...
Manifest fingerprint: sha256:f6d2...
✗ MISMATCH - Code has changed!

With Dependency Fingerprints

beltic fingerprint --deps

Includes fingerprints of declared dependencies:

{
  "systemConfigFingerprint": "sha256:f6d2...",
  "dependencyFingerprints": {
    "@company/shared-utils": "sha256:a1b2...",
    "anthropic": "sha256:c3d4..."
  }
}

Verbose Output

beltic fingerprint --verbose

Shows all files included:

Collecting files...
  ✓ src/index.ts
  ✓ src/handlers/refund.ts
  ✓ src/handlers/lookup.ts
  ✓ package.json
  ✗ src/test/refund.test.ts (excluded)
  ✗ node_modules/... (excluded)
Total: 47 files
Generating fingerprint...
SHA256: f6d2a8b3c4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1

Custom Manifest Path

beltic fingerprint --manifest custom-manifest.json

Custom Config

beltic fingerprint --config .beltic.production.yaml

Deployment Types

Standalone

Single codebase, one agent:

deployment:
  type: "standalone"

Includes: Entire repository

Monorepo

Multiple agents in one repository:

deployment:
  type: "monorepo"
paths:
  include:
    - "packages/refund-agent/**"
    - "shared/**"

Includes: Only relevant packages

Embedded

Agent embedded in larger application:

deployment:
  type: "embedded"
paths:
  include:
    - "src/agent/**"
    - "agent-config.json"

Includes: Agent-specific code only

Plugin

Agent as plugin/extension:

deployment:
  type: "plugin"
paths:
  include:
    - "plugin/**"
    - "manifest.json"

Includes: Plugin directory and metadata

Serverless

Agent as serverless functions:

deployment:
  type: "serverless"
paths:
  include:
    - "functions/**"
    - "serverless.yml"

Includes: Functions and configuration

Include/Exclude Patterns

Glob Patterns

Include all TypeScript:

include:
  - "**/*.ts"

Exclude tests:

exclude:
  - "**/*.test.ts"
  - "**/*.spec.ts"

Include specific directories:

include:
  - "src/**"
  - "lib/**"
exclude:
  - "src/test/**"

Common Patterns

Node.js project:

include:
  - "src/**"
  - "package.json"
  - "package-lock.json"
exclude:
  - "**/node_modules/**"
  - "**/.git/**"
  - "**/dist/**"
  - "**/*.test.*"

Python project:

include:
  - "src/**"
  - "requirements.txt"
  - "pyproject.toml"
exclude:
  - "**/__pycache__/**"
  - "**/.venv/**"
  - "**/dist/**"
  - "**/*_test.py"

Monorepo:

include:
  - "packages/agent-core/**"
  - "packages/shared/**"
  - "package.json"
exclude:
  - "**/node_modules/**"
  - "**/dist/**"

Workflow Integration

Development Workflow

# 1. Initialize manifest
beltic init

# 2. Develop agent code
# ... make changes ...

# 3. Update fingerprint before committing
beltic fingerprint

# 4. Commit changes
git add agent-manifest.json
git commit -m "Update agent code and fingerprint"

CI/CD Integration

# .github/workflows/verify-fingerprint.yml
name: Verify Fingerprint

on: [pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Beltic CLI
        run: |
          # Repository is currently private
          # See /docs/early-access for access requests
          # cargo install --git https://github.com/beltic/beltic-cli

      - name: Verify fingerprint
        run: |
          beltic fingerprint --verify
          if [ $? -ne 0 ]; then
            echo "Fingerprint mismatch! Run 'beltic fingerprint' to update."
            exit 1
          fi

Pre-commit Hook

# .git/hooks/pre-commit
#!/bin/bash

echo "Verifying fingerprint..."
beltic fingerprint --verify

if [ $? -ne 0 ]; then
  echo "Fingerprint mismatch! Updating..."
  beltic fingerprint
  git add agent-manifest.json
fi

Best Practices

Include only production code - Exclude tests, builds, dependencies
Use .beltic.yaml - Version control your fingerprint configuration
Verify in CI - Catch fingerprint mismatches before deployment
Update after every code change - Keep fingerprints current
Document exclusions - Comment why files are excluded

Next Steps

Signing & Verification

Sign your manifest as a credential

Command Reference

Complete CLI command documentation

AgentCredential

Complete agent credential specification

Managing Fingerprints

Signing & Verification

Command Reference

AgentCredential

On this page