Hull0

Hull0 enforces security manifests on AI agent actions. Agents run in Linux sandboxes; all I/O passes through a capability proxy that enforces rate limits, data flow rules, and approval gates.

See Quick Start to deploy your first agent.

Installation

From Cargo

cargo install hull0-cli

Binary Downloads

Pre-built binaries are available for:

• macOS (ARM64, x86_64)
• Linux (ARM64, x86_64)

Download from the releases page.

Verify Installation

h0 --version

Configuration

The CLI reads configuration from ~/.hull0/config.toml:

[auth]
access_token = "..."

[api]
url = "https://app.hull0.dev"

Configuration precedence: command-line flag > environment variable > config file.

Quick Start

1. Log In

h0 auth login

Opens a browser for OAuth authentication. Tokens are stored in ~/.hull0/config.toml.

2. Deploy an Agent

Browse available agents:

h0 marketplace list

Deploy one:

h0 deploy openclaw

3. Check Status

h0 agent list
h0 agent status <agent_id>

4. Clean Up

h0 agent destroy <agent_id>

The agent sandbox is terminated and resources released.

CLI Reference

The h0 command-line interface manages agents, secrets, and approvals.

Global Flags

Commands

Configuration

The CLI reads ~/.hull0/config.toml:

[auth]
access_token = "eyJ..."

[api]
url = "https://app.hull0.dev"

Precedence: flag > environment variable > config file.

h0 auth

Authentication commands.

login

h0 auth login [OPTIONS]

Authenticate via OAuth 2.0 PKCE flow. Opens a browser, starts a local callback server, exchanges the code for tokens, and stores them in the config file.

Options

Example

h0 auth login
# Browser opens, complete authentication
# Tokens saved to ~/.hull0/config.toml

whoami

h0 auth whoami

Display current authenticated user.

Example

$ h0 auth whoami
user_id: 550e8400-e29b-41d4-a716-446655440000
email: user@example.com
tier: pro

h0 agent

Agent lifecycle management.

list

h0 agent list

List all agents for the authenticated user.

get

h0 agent get <AGENT_ID>

Show details for a specific agent.

register

h0 agent register --name <NAME> --manifest <PATH>

Register a new agent with a manifest file.

Options

Example

h0 agent register --name my-agent --manifest agent.yaml

deploy

h0 agent deploy <AGENT_ID>

Deploy a registered agent. Creates a sandbox and starts the agent process.

status

h0 agent status <AGENT_ID>

Show current agent status: registered, deploying, running, destroying, destroyed, or error.

destroy

h0 agent destroy <AGENT_ID>

Stop a running agent. Terminates the sandbox and releases resources. Agent record remains for audit purposes.

delete

h0 agent delete <AGENT_ID>

Delete an agent record. Only allowed for agents in destroyed or error state.

h0 secret

Manage agent secrets. Secrets are encrypted at rest with AES-256-GCM and injected into HTTP headers at runtime via secret_headers in the manifest.

set

h0 secret set <AGENT_ID> <NAME> <VALUE>

Set a secret for an agent. Overwrites if the name exists.

Example

h0 secret set abc123 API_KEY sk-live-xxx

list

h0 secret list <AGENT_ID>

List secret names for an agent. Values are not displayed.

Example

$ h0 secret list abc123
API_KEY
DATABASE_URL

delete

h0 secret delete <AGENT_ID> <NAME>

Remove a secret.

Example

h0 secret delete abc123 API_KEY

h0 approval

Manage approval requests. Agents with requires_approval: always in their capabilities generate approval requests that must be resolved before the action proceeds.

list

h0 approval list

List pending approval requests for your agents.

Example

$ h0 approval list
ID          AGENT       CAPABILITY      REQUESTED
req_abc123  my-agent    send-email      2024-01-15 10:30:00
req_def456  my-agent    api-call        2024-01-15 10:31:00

approve

h0 approval approve <REQUEST_ID>

Approve a pending request. The action proceeds.

Example

h0 approval approve req_abc123

deny

h0 approval deny <REQUEST_ID>

Deny a pending request. The action is blocked and the agent receives an error response.

Example

h0 approval deny req_def456

h0 account

Account and billing management.

info

h0 account info

Display account details.

Example

$ h0 account info
user_id: 550e8400-e29b-41d4-a716-446655440000
email: user@example.com
tier: personal
created: 2024-01-01T00:00:00Z

upgrade

h0 account upgrade --tier <TIER>

Upgrade account tier. Opens Stripe checkout in browser.

Options

Example

h0 account upgrade --tier pro

billing

h0 account billing

Open the Stripe customer portal in browser to manage payment methods and view invoices.

h0 deploy

Deploy agents from the marketplace.

Synopsis

h0 deploy [OPTIONS] [NAME]

Description

Deploys a pre-configured agent from the marketplace. Equivalent to registering an agent with a marketplace manifest and immediately deploying it.

Options

Examples

List available agents:

$ h0 deploy --marketplace
NAME        DESCRIPTION
openclaw    Legal document assistant
analyst     Financial data analyst

Deploy an agent:

$ h0 deploy openclaw
Deploying openclaw...
Agent ID: abc123
Status: deploying

Use 'h0 agent status abc123' to check progress.

Manifest Reference

Manifests define agent capabilities and constraints. YAML format, schema version 1.0.

Structure

schema_version: "1.0"
name: my-agent
version: "1.0.0"
publisher: example

# UDS mode (cooperative agents)
capabilities:
  - name: api-call
    # ... capability definition

# OR transparent mode (unmodified agents)
network:
  outbound:
    # ... network rules

# Common sections
taint_rules:
  - name: pii-isolation
    # ... taint rule

secrets:
  - name: API_KEY
    # ... secret definition

settings:
  audit_path: /var/log/hull0/audit.jsonl

Modes

Manifests operate in one of two modes:

A manifest cannot have both capabilities and network sections.

Sections

• Capabilities - UDS mode API rules
• Network Policy - Transparent mode network rules
• Taint Rules - Data flow constraints
• Secrets - Secret declarations

Example: UDS Mode

schema_version: "1.0"
name: legal-assistant
version: "1.0.0"
publisher: hull0

capabilities:
  - name: openai-chat
    description: Chat completion API
    api:
      method: POST
      url_pattern: "https://api.openai.com/v1/chat/completions"
    rate_limit:
      requests_per_minute: 60
    secret_headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

secrets:
  - name: OPENAI_API_KEY
    required: true

Example: Transparent Mode

schema_version: "1.0"
name: web-scraper
version: "1.0.0"
publisher: hull0

network:
  outbound:
    - name: target-sites
      domains: ["*.example.com"]
      ports: [443]
      protocol: tcp
  dns:
    mode: allowlist
  runtime:
    runtime_type: node
    entrypoint: "node /app/index.js"

Capabilities

Capabilities define allowed API calls in UDS mode. Each capability specifies an endpoint pattern, rate limits, approval requirements, and optional secret injection.

Schema

capabilities:
  - name: string             # required, unique identifier
    description: string      # optional
    api:
      method: GET|POST|PUT|DELETE|PATCH
      url_pattern: string    # glob pattern, e.g. "https://api.example.com/**"
      url_deny_list: [string]
      headers_allowed: [string]
    rate_limit:
      requests_per_minute: integer
      burst: integer         # optional, default 1
    requires_approval:
      threshold: always|never
      timeout_seconds: integer
      default_on_timeout: deny|approve
    taint_labels: [string]
    secret_headers:
      Header-Name: "template with ${VAR}"

Fields

name

Required. Unique identifier for the capability. Used in audit logs and taint rules.

api

Defines the allowed HTTP request pattern.

rate_limit

Token bucket rate limiter.

requires_approval

Human-in-the-loop approval gate.

taint_labels

Labels applied to response data. Used by taint rules to restrict data flow.

secret_headers

Headers with secret values. ${VAR} is replaced with the secret value at runtime.

Example

capabilities:
  - name: stripe-charge
    description: Create Stripe charges
    api:
      method: POST
      url_pattern: "https://api.stripe.com/v1/charges"
    rate_limit:
      requests_per_minute: 10
      burst: 2
    requires_approval:
      threshold: always
      timeout_seconds: 300
      default_on_timeout: deny
    taint_labels: [payment_data]
    secret_headers:
      Authorization: "Bearer ${STRIPE_SECRET_KEY}"

Network Policy

Network policies define allowed connections in transparent mode. The proxy intercepts all network traffic via iptables DNAT and enforces these rules.

Schema

network:
  outbound:
    - name: string
      domains: [string]      # glob patterns
      ports: [integer]
      protocol: tcp|udp
      rate_limit:
        requests_per_minute: integer
        burst: integer
      taint_labels: [string]
  inbound:
    - name: string
      container_port: integer
      host_port: integer
      allowed_sources: [string]  # CIDR notation
  dns:
    mode: allowlist|passthrough
    additional_domains: [string]
  runtime:
    runtime_type: node|binary|container
    entrypoint: string
    env: {key: value}
    volumes:
      - name: string
        mount_path: string
        size_limit_mib: integer

Sections

outbound

Rules for outgoing connections.

inbound

Rules for incoming connections (optional).

dns

DNS resolution policy.

runtime

Agent execution configuration.

Example

network:
  outbound:
    - name: openai
      domains: ["api.openai.com"]
      ports: [443]
      protocol: tcp
      rate_limit:
        requests_per_minute: 100
    - name: slack
      domains: ["*.slack.com"]
      ports: [443]
      protocol: tcp
  dns:
    mode: allowlist
  runtime:
    runtime_type: node
    entrypoint: "node /app/bot.js"
    env:
      NODE_ENV: production
    volumes:
      - name: data
        mount_path: /data
        size_limit_mib: 256

Taint Rules

Taint rules restrict data flow between capabilities. Data is labeled with taint labels; rules prevent labeled data from flowing to certain destinations.

Schema

taint_rules:
  - name: string
    deny_flow:
      from_labels: [string]
      to_capabilities: [string]

Fields

name

Rule identifier. Used in audit logs.

deny_flow

Defines the forbidden data flow.

How It Works

1. Capabilities define taint_labels on their responses
2. The proxy tracks which data has which labels
3. Before executing a request, the proxy checks if any input data has labels that are denied flow to the target capability
4. If a violation is detected, the request is blocked

Example

Prevent contact information from being sent to an LLM:

capabilities:
  - name: crm-lookup
    api:
      method: GET
      url_pattern: "https://crm.example.com/contacts/**"
    taint_labels: [contact_info, pii]

  - name: llm-chat
    api:
      method: POST
      url_pattern: "https://api.openai.com/v1/chat/completions"
    taint_labels: []

taint_rules:
  - name: no-pii-to-llm
    deny_flow:
      from_labels: [pii, contact_info]
      to_capabilities: [llm-chat]

With this configuration:

• Data from crm-lookup is labeled contact_info and pii
• Any request to llm-chat containing this data is blocked
• The audit log records the blocked flow attempt

Secrets

Secrets declare credentials required by the agent. Values are set via the CLI and encrypted at rest with AES-256-GCM.

Schema

secrets:
  - name: string
    description: string
    required: boolean

Fields

Usage

1. Declare secrets in the manifest:

secrets:
  - name: OPENAI_API_KEY
    description: OpenAI API key
    required: true
  - name: WEBHOOK_SECRET
    description: Webhook signing secret
    required: false

2. Set secret values via CLI:

h0 secret set <agent_id> OPENAI_API_KEY sk-xxx

3. Reference in capabilities:

capabilities:
  - name: openai-chat
    secret_headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

Security

• Secrets are encrypted at rest using AES-256-GCM
• Encryption key is stored in AWS Secrets Manager
• Secret values are never logged or returned via API
• Only secret names are visible in h0 secret list
• Decryption happens at request time in the proxy

Architecture

Hull0 consists of three components: control plane, supervisor, and proxy.

┌─────────────────────────────────────────────────────────────┐
│                      Control Plane                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────────────┐│
│  │  Auth   │  │ Agents  │  │ Secrets │  │    Approvals    ││
│  └─────────┘  └─────────┘  └─────────┘  └─────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Supervisor                            │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ Deploy Poller   │  │ Sandbox Manager │                  │
│  └─────────────────┘  └─────────────────┘                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ spawn
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Sandbox                              │
│  ┌─────────┐         ┌─────────────────────────────────┐   │
│  │  Agent  │ ──UDS── │           Proxy                 │   │
│  └─────────┘         │  ┌─────┐ ┌─────┐ ┌─────┐       │   │
│                      │  │Allow│→│Rate │→│Taint│→ ...  │   │
│                      │  └─────┘ └─────┘ └─────┘       │   │
│                      └─────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Control Plane

REST API handling:

• User authentication (Cognito OAuth)
• Agent registry (CRUD operations)
• Secret storage (AES-256-GCM encrypted)
• Approval queue (human-in-the-loop)

Exposes internal endpoints for supervisor communication.

Supervisor

Runs on compute nodes. Responsibilities:

• Poll control plane for pending deployments
• Create sandboxes (Linux namespaces, cgroups)
• Spawn proxy processes
• Report agent status back to control plane

Proxy

Runs inside each sandbox alongside the agent. Enforces the manifest through an 8-stage pipeline. Two modes:

• UDS: Agent connects via Unix socket, sends JSON requests
• Transparent: iptables redirects network traffic to proxy

Data Flow

1. User deploys agent via CLI or web
2. Control plane records agent as deploying
3. Supervisor polls, sees pending agent, creates sandbox
4. Proxy starts, loads manifest
5. Agent runs, makes requests through proxy
6. Proxy enforces rules, logs to audit chain
7. User can view status, manage approvals via CLI

Proxy Modes

The proxy operates in one of three modes depending on agent requirements.

UDS Mode

For cooperative agents built with Hull0 protocol support.

Agent ──────► Unix Socket ──────► Proxy ──────► Internet
         JSON protocol

Agent connects to /tmp/hull0-proxy.sock and sends JSON requests:

{
  "capability": "openai-chat",
  "method": "POST",
  "url": "https://api.openai.com/v1/chat/completions",
  "headers": {"Content-Type": "application/json"},
  "body": "{...}"
}

Proxy validates against manifest, executes request, returns response.

Advantages:

• Fine-grained capability matching
• Secret injection into headers
• Taint tracking across requests

Use when: Building new agents or modifying existing ones.

Transparent Mode

For unmodified agents. Network traffic is intercepted via iptables.

Agent ──────► veth ──────► iptables DNAT ──────► Proxy ──────► Internet
         TCP/TLS                              TLS SNI

Sandbox has a veth pair. All outbound TCP is redirected to proxy port 9999. Proxy extracts destination from:

• SO_ORIGINAL_DST socket option (original IP:port)
• TLS SNI extension (hostname for HTTPS)

Matches against network.outbound rules in manifest.

Advantages:

• No agent modification required
• Works with any TCP application

Limitations:

• Domain-level granularity only
• No secret injection
• Limited taint tracking

Use when: Running existing applications without modification.

Vsock Mode

For Firecracker microVM sandboxes.

Agent (guest) ──────► AF_VSOCK ──────► Proxy (host)
                    CID:port

Uses virtio-vsock for guest-to-host communication. Same JSON protocol as UDS mode.

Use when: High-isolation requirements (paid tier).

Enforcement Pipeline

Every request passes through an 8-stage pipeline. Each stage can block the request.

Request
   │
   ▼
┌──────────────┐
│ 1. Allowlist │ capability exists? URL matches pattern?
└──────────────┘
   │
   ▼
┌──────────────┐
│ 2. Rate Limit│ token bucket check
└──────────────┘
   │
   ▼
┌──────────────┐
│ 3. Taint     │ data flow labels violate deny rules?
└──────────────┘
   │
   ▼
┌──────────────┐
│ 4. Approval  │ human sign-off required?
└──────────────┘
   │
   ▼
┌──────────────┐
│ 5. Secret    │ inject ${VAR} into headers
└──────────────┘
   │
   ▼
┌──────────────┐
│ 6. Execute   │ HTTP request to external API
└──────────────┘
   │
   ▼
┌──────────────┐
│ 7. Taint Rec │ label response with taint labels
└──────────────┘
   │
   ▼
┌──────────────┐
│ 8. Audit     │ hash-chained, signed log entry
└──────────────┘
   │
   ▼
Response

Stage Details

1. Allowlist

Checks:

• Capability name exists in manifest
• HTTP method matches
• URL matches url_pattern glob
• URL not in url_deny_list
• Headers are in headers_allowed list

2. Rate Limit

Token bucket algorithm per capability. Configured via rate_limit.requests_per_minute and burst.

3. Taint Check

Examines input data labels. If any label matches a taint_rules.deny_flow.from_labels entry where the current capability is in to_capabilities, the request is blocked.

4. Approval Gate

If requires_approval.threshold is always:

1. Create approval request in control plane
2. Wait up to timeout_seconds
3. If approved, proceed; if denied or timeout with default_on_timeout: deny, block

5. Secret Injection

Replace ${VAR} placeholders in secret_headers with decrypted secret values.

6. HTTP Execute

Send request to external API via reqwest. TLS verification enabled.

7. Taint Record

Apply capability's taint_labels to response data for future taint checks.

8. Audit Log

Write hash-chained, Ed25519-signed entry to audit log. Includes: sequence number, timestamp, capability, action, outcome.

Sandboxes

Agents run in isolated sandboxes. Four implementations with increasing isolation levels.

DevSandbox

Plain process spawn. No isolation.

┌──────────────────────────┐
│        Host OS           │
│  ┌────────┐  ┌────────┐  │
│  │ Agent  │  │ Proxy  │  │
│  └────────┘  └────────┘  │
└──────────────────────────┘

Isolation: None Use case: Local development only Platform: Any OS

LinuxSandbox

Linux namespaces with seccomp BPF filtering.

┌──────────────────────────┐
│        Host OS           │
│  ┌────────────────────┐  │
│  │ Namespace (PID,NET,│  │
│  │ MNT,USER)          │  │
│  │ ┌────────┐ ┌─────┐ │  │
│  │ │ Agent  │ │Proxy│ │  │
│  │ └────────┘ └─────┘ │  │
│  │ + seccomp BPF      │  │
│  │ + cgroups v2       │  │
│  └────────────────────┘  │
└──────────────────────────┘

Isolation:

• PID namespace: agent sees only its own processes
• Network namespace: isolated network stack
• Mount namespace: restricted filesystem view
• User namespace: unprivileged inside sandbox
• Seccomp: syscall allowlist
• Cgroups: CPU/memory limits

Use case: Production, UDS mode agents Platform: Linux only

ContainerSandbox

LinuxSandbox plus veth pair for transparent mode.

┌──────────────────────────────────────┐
│            Host OS                   │
│  ┌────────────────────────────────┐  │
│  │ Namespace                      │  │
│  │ ┌────────┐    ┌─────┐         │  │
│  │ │ Agent  │───►│Proxy│──► inet │  │
│  │ └────────┘    └─────┘         │  │
│  │      │                        │  │
│  │   veth ◄─── iptables DNAT     │  │
│  └────────────────────────────────┘  │
└──────────────────────────────────────┘

Additional features:

• veth pair: vh-{id} (host) / vs-{id} (sandbox)
• iptables DNAT: redirects all TCP to proxy
• DNS stub resolver: only resolves allowed domains

Use case: Production, transparent mode agents Platform: Linux only

FirecrackerSandbox

Firecracker microVM with vsock communication.

┌───────────────────────────────────────┐
│             Host OS                   │
│  ┌─────────────────────────────────┐  │
│  │ Firecracker microVM             │  │
│  │ ┌────────┐                      │  │
│  │ │ Agent  │◄───► vsock ◄───► Proxy (host)
│  │ └────────┘                      │  │
│  │ Minimal Linux kernel            │  │
│  └─────────────────────────────────┘  │
└───────────────────────────────────────┘

Isolation: Hardware-level via KVM Use case: High-security requirements Platform: Linux with KVM Tier: Paid plans only

Audit Chain

Every proxy action is logged to an append-only, tamper-evident audit chain.

Format

JSONL (JSON Lines). One entry per line.

{"seq":1,"ts":"2024-01-15T10:30:00Z","cap":"openai-chat","action":"request","outcome":"allowed","hash":"abc...","prev":"000...","sig":"def..."}
{"seq":2,"ts":"2024-01-15T10:30:01Z","cap":"openai-chat","action":"response","outcome":"success","hash":"ghi...","prev":"abc...","sig":"jkl..."}

Entry Fields

Integrity Properties

Hash Chain

Each entry's prev field contains the previous entry's hash. Tampering with any entry breaks the chain.

Entry 1          Entry 2          Entry 3
┌──────┐        ┌──────┐        ┌──────┐
│hash_1│◄───────│prev  │◄───────│prev  │
└──────┘        │hash_2│        │hash_3│
                └──────┘        └──────┘

Signatures

Each entry is signed with an Ed25519 private key. The corresponding public key can be used to verify authenticity.

Verification

To verify an audit log:

1. Check each entry's hash matches SHA-256 of entry content
2. Check each entry's prev matches previous entry's hash
3. Verify Ed25519 sig against hash using public key
4. Check seq is monotonically increasing
5. Check ts is monotonically increasing (within tolerance)

Storage

Default path: /var/log/hull0/audit.jsonl

Configurable via manifest settings.audit_path.

Compliance

The audit chain provides:

• Non-repudiation (signatures)
• Tamper evidence (hash chain)
• Completeness (sequence numbers)
• Temporal ordering (timestamps)

Suitable for SOX, HIPAA, GDPR audit requirements.

Financial Services

AI agents in finance require strict controls around data handling, API access, and auditability.

Requirements

• Rate-limited access to trading APIs
• PII isolation from third-party services
• Human approval for high-value transactions
• Audit trail for SOX/GDPR compliance

Example: Trading Assistant

schema_version: "1.0"
name: trading-assistant
version: "1.0.0"
publisher: fintech-corp

capabilities:
  - name: market-data
    description: Read market prices
    api:
      method: GET
      url_pattern: "https://api.exchange.com/v1/quotes/**"
    rate_limit:
      requests_per_minute: 600
    taint_labels: [market_data]

  - name: place-order
    description: Execute trades
    api:
      method: POST
      url_pattern: "https://api.exchange.com/v1/orders"
    rate_limit:
      requests_per_minute: 10
      burst: 2
    requires_approval:
      threshold: always
      timeout_seconds: 120
      default_on_timeout: deny
    secret_headers:
      Authorization: "Bearer ${EXCHANGE_API_KEY}"

  - name: llm-analysis
    description: AI market analysis
    api:
      method: POST
      url_pattern: "https://api.openai.com/v1/chat/completions"
    rate_limit:
      requests_per_minute: 30
    secret_headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

taint_rules:
  - name: no-pii-to-llm
    deny_flow:
      from_labels: [customer_pii]
      to_capabilities: [llm-analysis]

secrets:
  - name: EXCHANGE_API_KEY
    required: true
  - name: OPENAI_API_KEY
    required: true

Controls

Healthcare

Healthcare AI agents handle Protected Health Information (PHI) under HIPAA regulations.

Requirements

• PHI must not reach third-party LLMs
• Prescription actions require physician approval
• Complete audit trail for compliance
• Network isolation for medical device integrations

Example: Clinical Assistant

schema_version: "1.0"
name: clinical-assistant
version: "1.0.0"
publisher: healthcare-corp

capabilities:
  - name: ehr-read
    description: Read patient records
    api:
      method: GET
      url_pattern: "https://ehr.hospital.internal/fhir/Patient/**"
    rate_limit:
      requests_per_minute: 100
    taint_labels: [phi, patient_data]

  - name: ehr-write
    description: Update patient records
    api:
      method: PUT
      url_pattern: "https://ehr.hospital.internal/fhir/Patient/**"
    rate_limit:
      requests_per_minute: 20
    requires_approval:
      threshold: always
      timeout_seconds: 300
      default_on_timeout: deny
    taint_labels: [phi]

  - name: prescription
    description: Create prescriptions
    api:
      method: POST
      url_pattern: "https://ehr.hospital.internal/fhir/MedicationRequest"
    rate_limit:
      requests_per_minute: 10
    requires_approval:
      threshold: always
      timeout_seconds: 600
      default_on_timeout: deny

  - name: llm-summarize
    description: Summarize non-PHI data
    api:
      method: POST
      url_pattern: "https://api.openai.com/v1/chat/completions"
    rate_limit:
      requests_per_minute: 30
    secret_headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

taint_rules:
  - name: hipaa-phi-isolation
    deny_flow:
      from_labels: [phi, patient_data]
      to_capabilities: [llm-summarize]

secrets:
  - name: OPENAI_API_KEY
    required: true

Controls

Legal Tech

Legal AI agents handle privileged communications and sensitive case data.

Requirements

• Attorney-client privilege protection
• Court filing requires attorney approval
• Document access audit for malpractice defense
• Isolation between client matters

Example: Legal Research Assistant

schema_version: "1.0"
name: legal-assistant
version: "1.0.0"
publisher: lawfirm-llp

capabilities:
  - name: case-search
    description: Search case law databases
    api:
      method: GET
      url_pattern: "https://api.westlaw.com/v1/search/**"
    rate_limit:
      requests_per_minute: 60
    secret_headers:
      Authorization: "Bearer ${WESTLAW_API_KEY}"

  - name: document-read
    description: Read client documents
    api:
      method: GET
      url_pattern: "https://dms.firm.internal/documents/**"
    rate_limit:
      requests_per_minute: 100
    taint_labels: [privileged, client_data]

  - name: court-filing
    description: Submit court filings
    api:
      method: POST
      url_pattern: "https://efiling.courts.gov/api/v1/submit"
    rate_limit:
      requests_per_minute: 5
    requires_approval:
      threshold: always
      timeout_seconds: 3600
      default_on_timeout: deny

  - name: llm-draft
    description: Draft assistance
    api:
      method: POST
      url_pattern: "https://api.openai.com/v1/chat/completions"
    rate_limit:
      requests_per_minute: 30
    secret_headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

taint_rules:
  - name: privilege-protection
    deny_flow:
      from_labels: [privileged, client_data]
      to_capabilities: [llm-draft]

secrets:
  - name: WESTLAW_API_KEY
    required: true
  - name: OPENAI_API_KEY
    required: true

Controls

Customer Service

AI agents handling customer interactions across multiple channels.

Requirements

• Multi-channel support (email, chat, WhatsApp)
• Customer data isolation from LLMs
• Rate limiting per platform
• Escalation workflows

Example: Support Bot

schema_version: "1.0"
name: support-bot
version: "1.0.0"
publisher: support-corp

capabilities:
  - name: crm-lookup
    description: Customer record lookup
    api:
      method: GET
      url_pattern: "https://api.salesforce.com/services/data/v58.0/sobjects/Contact/**"
    rate_limit:
      requests_per_minute: 100
    taint_labels: [customer_pii, contact_info]
    secret_headers:
      Authorization: "Bearer ${SALESFORCE_TOKEN}"

  - name: ticket-create
    description: Create support tickets
    api:
      method: POST
      url_pattern: "https://api.zendesk.com/api/v2/tickets"
    rate_limit:
      requests_per_minute: 50
    secret_headers:
      Authorization: "Basic ${ZENDESK_API_KEY}"

  - name: slack-message
    description: Send Slack messages
    api:
      method: POST
      url_pattern: "https://slack.com/api/chat.postMessage"
    rate_limit:
      requests_per_minute: 30
    secret_headers:
      Authorization: "Bearer ${SLACK_BOT_TOKEN}"

  - name: whatsapp-send
    description: Send WhatsApp messages
    api:
      method: POST
      url_pattern: "https://graph.facebook.com/v18.0/*/messages"
    rate_limit:
      requests_per_minute: 20
      burst: 5
    secret_headers:
      Authorization: "Bearer ${WHATSAPP_TOKEN}"

  - name: llm-respond
    description: Generate responses
    api:
      method: POST
      url_pattern: "https://api.openai.com/v1/chat/completions"
    rate_limit:
      requests_per_minute: 60
    secret_headers:
      Authorization: "Bearer ${OPENAI_API_KEY}"

taint_rules:
  - name: pii-isolation
    deny_flow:
      from_labels: [customer_pii, contact_info]
      to_capabilities: [llm-respond]

secrets:
  - name: SALESFORCE_TOKEN
    required: true
  - name: ZENDESK_API_KEY
    required: true
  - name: SLACK_BOT_TOKEN
    required: true
  - name: WHATSAPP_TOKEN
    required: true
  - name: OPENAI_API_KEY
    required: true

Controls

Transparent Mode Alternative

For existing support applications:

schema_version: "1.0"
name: support-bot-transparent
version: "1.0.0"
publisher: support-corp

network:
  outbound:
    - name: salesforce
      domains: ["*.salesforce.com"]
      ports: [443]
      protocol: tcp
      rate_limit:
        requests_per_minute: 100
    - name: zendesk
      domains: ["*.zendesk.com"]
      ports: [443]
      protocol: tcp
    - name: slack
      domains: ["*.slack.com"]
      ports: [443]
      protocol: tcp
    - name: whatsapp
      domains: ["graph.facebook.com"]
      ports: [443]
      protocol: tcp
    - name: openai
      domains: ["api.openai.com"]
      ports: [443]
      protocol: tcp
  dns:
    mode: allowlist
  runtime:
    runtime_type: node
    entrypoint: "node /app/bot.js"