> ## 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.

# Quickstart

> Ship the current Sec0 integration path: middleware, decorators, guard, and gateway.

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

```bash theme={null}
npm install sec0-sdk
```

## 2. Generate a Signing Key

```bash theme={null}
mkdir -p .sec0/keys
openssl rand -base64 32 > .sec0/keys/ed25519.key
```

<Warning>
  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`.
</Warning>

## 3. Create a Minimal `policy.yaml`

Start with a local, observe-mode policy:

```yaml theme={null}
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.

```typescript theme={null}
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](/docs/middleware).

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

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

```yaml theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](/docs/guard) 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:

```typescript theme={null}
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](/docs/bridge) for client options and [Network Gateway](/docs/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:

```typescript theme={null}
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](/docs/approvals-integration).

## 10. Verify

Use the [Verify & Troubleshoot](/docs/verify-and-troubleshoot) checklist to confirm each layer is working.

## What's Next?

<CardGroup cols={2}>
  <Card title="Middleware" href="/docs/middleware">
    Wrap tool servers and choose local vs hosted presets
  </Card>

  <Card title="Guard API" href="/docs/guard">
    Gate outbound messages, tool calls, and APIs
  </Card>

  <Card title="Instrumentation" href="/docs/instrumentation">
    Register hops, decorators, and propagation
  </Card>

  <Card title="Gateway" href="/docs/gateway">
    Add network-edge enforcement and brokering
  </Card>
</CardGroup>