Instrumentation Config Reference

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`

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:

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

loadStandardConfig(configName?: string, sec0Mapping?: (cfg) => Partial<Sec0Config>): StandardAppConfig

initializeSec0App

initializeSec0App(configPath?: string): void

initSec0

initSec0(configPathOrObject: string | Sec0Config): Sec0Config

getSec0AppConfig

getSec0AppConfig<T extends StandardAppConfig>(): T

For the decorator-to-hop mapping and a paste-ready class example, see Decorated Hops Reference.

Getting Started

In-Device Security

Network Boundary Security

Policy & Compliance

Operations

Advanced

Reference

Instrumentation Config Reference

Recommended path: `sec0.config.yaml`

StandardAppConfig

app

app.client

auth

controlPlane

Programmatic bootstrap: `initSec0`

app.hops

HopConfig base fields

Agent hop

Orchestrator hop

Gateway hop

Server hop

Middleware hop

Tool hop

Skill hop

HopAutomationOptions

HopEnforcementOptions

AgentStatePayload

Main exported functions

loadStandardConfig

initializeSec0App

initSec0

getSec0AppConfig

​Recommended path: sec0.config.yaml

​StandardAppConfig

​app

​app.client

​auth

​controlPlane

​Programmatic bootstrap: initSec0

​app.hops

​HopConfig base fields

​Agent hop

​Orchestrator hop

​Gateway hop

​Server hop

​Middleware hop

​Tool hop

​Skill hop

​HopAutomationOptions

​HopEnforcementOptions

​AgentStatePayload

​Main exported functions

​loadStandardConfig

​initializeSec0App

​initSec0

​getSec0AppConfig

Recommended path: `sec0.config.yaml`

StandardAppConfig

app

app.client

auth

controlPlane

Programmatic bootstrap: `initSec0`

app.hops

HopConfig base fields

Agent hop

Orchestrator hop

Gateway hop

Server hop

Middleware hop

Tool hop

Skill hop

HopAutomationOptions

HopEnforcementOptions

AgentStatePayload

Main exported functions

loadStandardConfig

initializeSec0App

initSec0

getSec0AppConfig