Quickstart

This quickstart uses the current developer entrypoints in sec0-sdk:

sec0-sdk/middleware for in-process tool enforcement
sec0-sdk/instrumentation for hop decorators and agent-state propagation
sec0-sdk/guard for outbound allow, redact, block, and escalate decisions
sec0-sdk/middleware plus sec0-sdk/gateway for cross-network tool calls

Prerequisites

Node.js >= 20
An Ed25519 signing key
A local policy.yaml
Optional: a Sec0 API key when you switch to hosted policy or approvals

1. Install the SDK

npm install sec0-sdk

2. Generate a Signing Key

mkdir -p .sec0/keys
openssl rand -base64 32 > .sec0/keys/ed25519.key

Store your signing key securely. If you keep the key outside default safe directories (.sec0/keys, keys, config/keys, .sec0/secrets, secrets), set SEC0_SIGNER_KEY_DIRS.

3. Create a Minimal `policy.yaml`

Start with a local, observe-mode policy:

tenant: my-app
default_retention: "30d"

signing:
  enabled: true
  key_ref: "file://./.sec0/keys/ed25519.key"

observability:
  otlp_endpoint: "http://127.0.0.1:4318"
  sample:
    success: 1
    error: 1

tools:
  allowlist: ["*"]
  deny_if_unpinned_version: false

privacy:
  redact_outputs: false
  store_raw_payloads: false

side_effects:
  require_idempotency_key: false
  max_retries: 0

enforcement:
  deny_on: []
  circuit_breakers:
    error_rate_pct: 100
    p95_latency_ms: 0

sec0_export:
  enabled: false
  bucket_uri: "gs://unused-local-dev"

4. Wrap a Tool Server with `sec0LocalMiddleware`

For a first integration, use the local preset. It keeps policy, runtime decisions, approvals, and audit writes on-device.

import fs from "node:fs";
import { parsePolicyYaml } from "sec0-sdk/policy";
import { LocalDevSigner } from "sec0-sdk/signer";
import { sec0LocalMiddleware } from "sec0-sdk/middleware";

const server = createYourMcpServer();
const policy = parsePolicyYaml(fs.readFileSync("./policy.yaml", "utf8"));

sec0LocalMiddleware({
  policy,
  signer: LocalDevSigner.fromKeyRef(policy.signing.key_ref),
  otel: {
    endpoint: policy.observability.otlp_endpoint,
    serviceName: "orders-mcp",
    serviceVersion: "1.0.0",
    environment: "dev",
    tenant: policy.tenant,
  },
  sec0: { dir: ".sec0", retentionDays: 30 },
  telemetry: { enabled: false },
})(server);

When you need hosted policy, approvals, or remote runtime evaluation, switch the same server to sec0HostedMiddleware. See Middleware.

5. Register Hop Metadata in `sec0.config.yaml`

Instrumentation uses sec0.config.yaml to resolve hop identity, gateway defaults, and local storage:

app:
  tenant: my-app
  environment: dev
  client:
    name: my-agent-runtime
    version: "1.0.0"
  hops:
    Workflow.orchestrate:
      type: orchestrator
      nodeId: workflow-orch
      orchestratorName: workflow-orch
      orchestratorVersion: "1.0.0"
    OrderAgent.run:
      type: agent
      nodeId: order-agent
      agentName: order-agent
      agentVersion: "1.0.0"
    Gateway.forward:
      type: gateway
      nodeId: workflow-gateway
      gateway: sec0-gateway
      gatewayBaseUrl: https://gateway.example.com
      automation:
        auth: true
        cause: true
        idempotency: true

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

controlPlane:
  sec0Dir: ./.sec0
  localSignerPath: ./.sec0/keys/ed25519.key
  appenderDir: ./.sec0/logs

6. Initialize Decorators and Propagate Agent State

Decorators give you stable nodeId, runId, state propagation, and signed audit envelopes across agent hops:

import { initializeSec0App, sec0, AgentManager } from "sec0-sdk/instrumentation";

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

class OrderAgent {
  @sec0.agent()
  async run(ctx: any, input: { orderId: string }, manager: AgentManager) {
    manager.agent.setState({ order_id: input.orderId });
    manager.agent.setMetadata({ received_at: Date.now() });

    const headers = manager.getAgentStateHeaders();
    await fetch("https://api.example.com/process-order", {
      method: "POST",
      headers,
      body: JSON.stringify({ orderId: input.orderId }),
    });

    return { ok: true };
  }
}

class Workflow {
  @sec0.orchestrator()
  async orchestrate(ctx: any, input: any, manager: AgentManager) {
    manager.agent.objective("Plan and execute the order workflow safely.");
    await manager.invoke("OrderAgent.run", {
      orderId: input.orderId,
    });

    return { ok: true };
  }
}

7. Add Guard Checks for Outbound Messages or API Calls

Use sec0-sdk/guard when the action is not naturally wrapped by the middleware, or when you want a simple allow, redact, block, and escalate API in application code:

import { createSec0Guard } from "sec0-sdk/guard";

const guard = createSec0Guard({
  mode: "standalone",
  provider: {
    local: {
      policy: {
        defaultOutcome: "allow",
        rules: [
          {
            kind: "message_outbound",
            target: "discord:supplier",
            outcome: "block",
            reason: "supplier_messages_require_review",
          },
        ],
      },
    },
  },
});

await guard.execute(
  {
    kind: "message_outbound",
    target: "discord:supplier",
    content: outboundMessage,
  },
  async () => sendToSupplier(outboundMessage),
);

See Guard API for dashboard and hybrid modes, redaction, and approvals transport wiring.

8. Route Cross-Network Tool Calls Through the Gateway

Use the bridge helper when tool execution crosses a process or network boundary:

import { callToolViaGateway } from "sec0-sdk/middleware";

const result = await callToolViaGateway({
  gatewayBaseUrl: "https://gateway.example.com",
  server: "payments-mcp",
  toolAtVersion: "charge@1.0",
  args: { amount: 4999, currency: "usd" },
  authHeader: `Bearer ${process.env.SVC_TOKEN}`,
  cause: { traceId: ctx.traceId, spanId: ctx.spanId },
  agentState: manager.agent.snapshot(),
  timeoutMs: 15_000,
});

Use Gateway Bridge for client options and Network Gateway to deploy the server side.

9. Switch to Hosted Policy and Approvals When Ready

Replace the local preset with the hosted preset when you want control-plane policy sync, escalation creation, or remote runtime evaluation:

import { sec0HostedMiddleware } from "sec0-sdk/middleware";
import { LocalDevSigner } from "sec0-sdk/signer";

sec0HostedMiddleware({
  policy: {
    source: "control-plane",
    level: "middleware",
    scope: "auto",
    refreshTtlMs: 60_000,
  },
  auth: { apiKey: process.env.SEC0_API_KEY! },
  signer: LocalDevSigner.fromKeyRef("file://./.sec0/keys/ed25519.key"),
  otel: {
    endpoint: "http://127.0.0.1:4318",
    serviceName: "orders-mcp",
    serviceVersion: "1.0.0",
    environment: "dev",
    tenant: "my-app",
  },
  sec0: { dir: ".sec0", retentionDays: 30 },
})(server);

Then configure enforcement.escalate_on plus security.side_effects.human_escalation and connect the approvals bridge. See Approvals & Escalations.

Getting Started

In-Device Security

Network Boundary Security

Policy & Compliance

Operations

Advanced

Reference

Prerequisites

1. Install the SDK

2. Generate a Signing Key

3. Create a Minimal `policy.yaml`

4. Wrap a Tool Server with `sec0LocalMiddleware`

5. Register Hop Metadata in `sec0.config.yaml`

6. Initialize Decorators and Propagate Agent State

7. Add Guard Checks for Outbound Messages or API Calls

8. Route Cross-Network Tool Calls Through the Gateway

9. Switch to Hosted Policy and Approvals When Ready

10. Verify

What’s Next?

Middleware

Guard API

Instrumentation

Gateway

​Prerequisites

​1. Install the SDK

​2. Generate a Signing Key

​3. Create a Minimal policy.yaml

​4. Wrap a Tool Server with sec0LocalMiddleware

​5. Register Hop Metadata in sec0.config.yaml

​6. Initialize Decorators and Propagate Agent State

​7. Add Guard Checks for Outbound Messages or API Calls

​8. Route Cross-Network Tool Calls Through the Gateway

​9. Switch to Hosted Policy and Approvals When Ready

​10. Verify

​What’s Next?

Middleware

Guard API

Instrumentation

Gateway

Prerequisites

1. Install the SDK

2. Generate a Signing Key

3. Create a Minimal `policy.yaml`

4. Wrap a Tool Server with `sec0LocalMiddleware`

5. Register Hop Metadata in `sec0.config.yaml`

6. Initialize Decorators and Propagate Agent State

7. Add Guard Checks for Outbound Messages or API Calls

8. Route Cross-Network Tool Calls Through the Gateway

9. Switch to Hosted Policy and Approvals When Ready

10. Verify

What’s Next?