> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sec0.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Instrumentation Config Reference

> Developer-facing configuration for sec0-sdk/instrumentation and sec0.config.yaml.

`sec0-sdk/instrumentation` is the decorator-first SDK for in-device tracing, agent state propagation, and hop-aware policy enforcement. Most integrations should start with `sec0.config.yaml` plus `initializeSec0App(...)`, then decorate the methods that represent agent, orchestrator, gateway, server, middleware, tool, or skill boundaries.

## Recommended path: `sec0.config.yaml`

```yaml theme={null}
app:
  tenant: my-app
  environment: dev
  client:
    name: orders-service
    version: "1.0.0"
  hops:
    OrderAgent.run:
      type: agent
      nodeId: order-agent
      agentName: order-agent
      agentVersion: "1.0.0"
      automation:
        idempotency: true
        cause: true
      enforcement:
        policyScope: auto

auth:
  sec0ApiKey: ${SEC0_API_KEY}
  svcToken: ${SEC0_SVC_TOKEN}

controlPlane:
  apiBaseUrl: ${SEC0_URL}
  sec0Dir: ./.sec0
  localSignerPath: ./.sec0/keys/ed25519.key
  appenderDir: ./.sec0/audit
  otlpEndpoint: ${OTLP_ENDPOINT}
  presign:
    enabled: true
```

Boot it with:

```typescript theme={null}
import { initializeSec0App } from "sec0-sdk/instrumentation";

initializeSec0App("./sec0.config.yaml");
```

## StandardAppConfig

| Key            | Type   | Required | Description                                   |
| -------------- | ------ | -------- | --------------------------------------------- |
| `app`          | object | Yes      | App identity and hop registry                 |
| `auth`         | object | No       | API keys and service tokens                   |
| `controlPlane` | object | Yes      | Sec0 runtime paths and control-plane settings |

### app

| Key               | Type                        | Required | Description                          |
| ----------------- | --------------------------- | -------- | ------------------------------------ |
| `app.tenant`      | string                      | Yes      | Tenant or workspace                  |
| `app.environment` | string                      | Yes      | Environment name                     |
| `app.client`      | object                      | No       | Client identity                      |
| `app.hops`        | `Record<string, HopConfig>` | No       | Hop registry keyed by `Class.method` |

### app.client

| Key                  | Type   | Required | Description    |
| -------------------- | ------ | -------- | -------------- |
| `app.client.name`    | string | Yes      | Client name    |
| `app.client.version` | string | No       | Client version |

### auth

| Key               | Type   | Required | Description                         |
| ----------------- | ------ | -------- | ----------------------------------- |
| `auth.svcToken`   | string | No       | Service token used for gateway auth |
| `auth.sec0ApiKey` | string | No       | Sec0 API key                        |

### controlPlane

| Key                            | Type    | Required | Description                   |
| ------------------------------ | ------- | -------- | ----------------------------- |
| `controlPlane.apiBaseUrl`      | string  | No       | Policy server base URL        |
| `controlPlane.sec0Dir`         | string  | Yes      | Sec0 data directory           |
| `controlPlane.localSignerPath` | string  | Yes      | Path to the local Ed25519 key |
| `controlPlane.appenderDir`     | string  | No       | Audit log directory           |
| `controlPlane.otlpEndpoint`    | string  | No       | OTLP endpoint override        |
| `controlPlane.presign.enabled` | boolean | No       | Enable hosted audit uploads   |

## Programmatic bootstrap: `initSec0`

Use `initSec0(...)` when you are not loading `sec0.config.yaml`:

| Key               | Type   | Required | Description                                  |
| ----------------- | ------ | -------- | -------------------------------------------- |
| `localDir`        | string | Yes      | Local directory for keys and audit artifacts |
| `tenant`          | string | No       | Default tenant hint                          |
| `controlPlaneUrl` | string | No       | Policy server base URL                       |
| `apiKey`          | string | No       | API key for tenant resolution                |
| `localSignerPath` | string | Yes      | Path to the local Ed25519 key                |
| `appender.dir`    | string | No       | Audit log directory                          |

## app.hops

Each hop entry is keyed by `Class.method` or a custom string and must match the decorator used on that method.

### HopConfig base fields

| Key           | Type                                                                        | Required | Description                           |
| ------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------- |
| `type`        | `agent`, `orchestrator`, `gateway`, `server`, `tool`, `middleware`, `skill` | Yes      | Hop type                              |
| `nodeId`      | string                                                                      | Yes      | Node identifier                       |
| `automation`  | object                                                                      | No       | Auto-attach Sec0 headers and context  |
| `enforcement` | object                                                                      | No       | Hop-level policy overrides            |
| `remoteUrl`   | string                                                                      | No       | Remote URL used by `manager.invoke()` |

### Agent hop

| Key            | Type   | Required | Description   |
| -------------- | ------ | -------- | ------------- |
| `agentName`    | string | Yes      | Agent name    |
| `agentVersion` | string | Yes      | Agent version |

### Orchestrator hop

| Key                   | Type   | Required | Description          |
| --------------------- | ------ | -------- | -------------------- |
| `orchestratorName`    | string | Yes      | Orchestrator name    |
| `orchestratorVersion` | string | Yes      | Orchestrator version |

### Gateway hop

| Key              | Type   | Required | Description                          |
| ---------------- | ------ | -------- | ------------------------------------ |
| `gateway`        | string | Yes      | Gateway name                         |
| `gatewayBaseUrl` | string | Yes      | Gateway base URL                     |
| `tenant`         | string | No       | Tenant override                      |
| `authHeader`     | string | No       | Authorization header for the gateway |

### Server hop

| Key      | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `server` | string | Yes      | Tool server name |

### Middleware hop

| Key          | Type   | Required | Description                          |
| ------------ | ------ | -------- | ------------------------------------ |
| `middleware` | string | Yes      | Middleware identity (`name@version`) |
| `op`         | string | Yes      | Operation name (`name@version`)      |

### Tool hop

| Key       | Type   | Required | Description                    |
| --------- | ------ | -------- | ------------------------------ |
| `server`  | string | Yes      | Tool server name               |
| `tool`    | string | Yes      | Tool name\@version             |
| `toolRef` | string | No       | Optional tool reference string |

### Skill hop

| Key        | Type   | Required | Description                     |
| ---------- | ------ | -------- | ------------------------------- |
| `skill`    | string | Yes      | Skill name\@version             |
| `source`   | string | No       | Registry or source identity     |
| `skillRef` | string | No       | Optional skill reference string |

## HopAutomationOptions

| Key                          | Type    | Required | Description                      |
| ---------------------------- | ------- | -------- | -------------------------------- |
| `automation.ap2`             | boolean | No       | Auto-apply AP2 headers           |
| `automation.identityContext` | boolean | No       | Auto-attach identity context     |
| `automation.idempotency`     | boolean | No       | Auto-apply idempotency key       |
| `automation.auth`            | boolean | No       | Auto-attach auth header          |
| `automation.cause`           | boolean | No       | Auto-attach cause trace and span |

## HopEnforcementOptions

When omitted, decorators fetch policy automatically from the control plane: `gateway` policy level for gateway hops and `middleware` policy level for all other hop types.

| Key                                                           | Type                             | Required | Description                                              |
| ------------------------------------------------------------- | -------------------------------- | -------- | -------------------------------------------------------- |
| `enforcement.enabled`                                         | boolean                          | No       | Enable or disable hop-level checks                       |
| `enforcement.mode`                                            | `observe` or `enforce`           | No       | Record-only or deny-enforcing mode                       |
| `enforcement.strategy`                                        | `deny_on_match` or `deny_on_any` | No       | Reason matching strategy                                 |
| `enforcement.deny_on` / `enforcement.denyOn`                  | string\[]                        | No       | Override deny reasons for this hop                       |
| `enforcement.escalate_on` / `enforcement.escalateOn`          | string\[]                        | No       | Override escalation reasons for this hop                 |
| `enforcement.policy_level` / `enforcement.policyLevel`        | `gateway` or `middleware`        | No       | Policy level to fetch                                    |
| `enforcement.policy_scope` / `enforcement.policyScope`        | `auto`, `base`, or `agent`       | No       | Policy scope resolution mode                             |
| `enforcement.policy_node_id` / `enforcement.policyNodeId`     | string                           | No       | Override `nodeId` for agent-scoped policy lookup         |
| `enforcement.refresh_ttl_ms` / `enforcement.refreshTtlMs`     | number                           | No       | Policy cache TTL in milliseconds                         |
| `enforcement.fallback_to_base` / `enforcement.fallbackToBase` | boolean                          | No       | Fall back to base policy when the scoped policy is empty |

## AgentStatePayload

| Key         | Type   | Required | Description              |
| ----------- | ------ | -------- | ------------------------ |
| `nodeId`    | string | Yes      | Node identifier          |
| `runId`     | string | No       | Run identifier           |
| `parentRef` | string | No       | Parent reference         |
| `variables` | object | No       | Agent variables by scope |
| `metadata`  | object | No       | Arbitrary metadata       |

Supported variable scopes: `AGENT`, `GATEWAY`, `SERVER`, `TOOL`, `ORCHESTRATOR`.

## Main exported functions

### loadStandardConfig

```typescript theme={null}
loadStandardConfig(configName?: string, sec0Mapping?: (cfg) => Partial<Sec0Config>): StandardAppConfig
```

### initializeSec0App

```typescript theme={null}
initializeSec0App(configPath?: string): void
```

### initSec0

```typescript theme={null}
initSec0(configPathOrObject: string | Sec0Config): Sec0Config
```

### getSec0AppConfig

```typescript theme={null}
getSec0AppConfig<T extends StandardAppConfig>(): T
```

For the decorator-to-hop mapping and a paste-ready class example, see [Decorated Hops Reference](/docs/reference/decorated-hops-runtime).