Skip to main content
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. 
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

KeyTypeRequiredDescription
appobjectYesApp identity and hop registry
authobjectNoAPI keys and service tokens
controlPlaneobjectYesSec0 runtime paths and control-plane settings

​
app

KeyTypeRequiredDescription
app.tenantstringYesTenant or workspace
app.environmentstringYesEnvironment name
app.clientobjectNoClient identity
app.hopsRecord<string, HopConfig>NoHop registry keyed by Class.method

​
app.client

KeyTypeRequiredDescription
app.client.namestringYesClient name
app.client.versionstringNoClient version

​
auth

KeyTypeRequiredDescription
auth.svcTokenstringNoService token used for gateway auth
auth.sec0ApiKeystringNoSec0 API key

​
controlPlane

KeyTypeRequiredDescription
controlPlane.apiBaseUrlstringNoPolicy server base URL
controlPlane.sec0DirstringYesSec0 data directory
controlPlane.localSignerPathstringYesPath to the local Ed25519 key
controlPlane.appenderDirstringNoAudit log directory
controlPlane.otlpEndpointstringNoOTLP endpoint override
controlPlane.presign.enabledbooleanNoEnable hosted audit uploads

​
Programmatic bootstrap: initSec0

Use initSec0(...) when you are not loading sec0.config.yaml:
KeyTypeRequiredDescription
localDirstringYesLocal directory for keys and audit artifacts
tenantstringNoDefault tenant hint
controlPlaneUrlstringNoPolicy server base URL
apiKeystringNoAPI key for tenant resolution
localSignerPathstringYesPath to the local Ed25519 key
appender.dirstringNoAudit 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

KeyTypeRequiredDescription
typeagent, orchestrator, gateway, server, tool, middleware, skillYesHop type
nodeIdstringYesNode identifier
automationobjectNoAuto-attach Sec0 headers and context
enforcementobjectNoHop-level policy overrides
remoteUrlstringNoRemote URL used by manager.invoke()

​
Agent hop

KeyTypeRequiredDescription
agentNamestringYesAgent name
agentVersionstringYesAgent version

​
Orchestrator hop

KeyTypeRequiredDescription
orchestratorNamestringYesOrchestrator name
orchestratorVersionstringYesOrchestrator version

​
Gateway hop

KeyTypeRequiredDescription
gatewaystringYesGateway name
gatewayBaseUrlstringYesGateway base URL
tenantstringNoTenant override
authHeaderstringNoAuthorization header for the gateway

​
Server hop

KeyTypeRequiredDescription
serverstringYesTool server name

​
Middleware hop

KeyTypeRequiredDescription
middlewarestringYesMiddleware identity (name@version)
opstringYesOperation name (name@version)

​
Tool hop

KeyTypeRequiredDescription
serverstringYesTool server name
toolstringYesTool name@version
toolRefstringNoOptional tool reference string

​
Skill hop

KeyTypeRequiredDescription
skillstringYesSkill name@version
sourcestringNoRegistry or source identity
skillRefstringNoOptional skill reference string

​
HopAutomationOptions

KeyTypeRequiredDescription
automation.ap2booleanNoAuto-apply AP2 headers
automation.identityContextbooleanNoAuto-attach identity context
automation.idempotencybooleanNoAuto-apply idempotency key
automation.authbooleanNoAuto-attach auth header
automation.causebooleanNoAuto-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.
KeyTypeRequiredDescription
enforcement.enabledbooleanNoEnable or disable hop-level checks
enforcement.modeobserve or enforceNoRecord-only or deny-enforcing mode
enforcement.strategydeny_on_match or deny_on_anyNoReason matching strategy
enforcement.deny_on / enforcement.denyOnstring[]NoOverride deny reasons for this hop
enforcement.escalate_on / enforcement.escalateOnstring[]NoOverride escalation reasons for this hop
enforcement.policy_level / enforcement.policyLevelgateway or middlewareNoPolicy level to fetch
enforcement.policy_scope / enforcement.policyScopeauto, base, or agentNoPolicy scope resolution mode
enforcement.policy_node_id / enforcement.policyNodeIdstringNoOverride nodeId for agent-scoped policy lookup
enforcement.refresh_ttl_ms / enforcement.refreshTtlMsnumberNoPolicy cache TTL in milliseconds
enforcement.fallback_to_base / enforcement.fallbackToBasebooleanNoFall back to base policy when the scoped policy is empty

​
AgentStatePayload

KeyTypeRequiredDescription
nodeIdstringYesNode identifier
runIdstringNoRun identifier
parentRefstringNoParent reference
variablesobjectNoAgent variables by scope
metadataobjectNoArbitrary 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.