Secrets and connections

Write-only secrets

useSecret("NAME") produces an opaque reference — never a value. Values are injected only into declared connections after origin, method, path-prefix, agent, and environment checks. They never appear in prompts, logs, templates, snapshots, bundles, manifests, rendered instructions, events, session transcripts, --json output, API responses, or env dumps.

zap secret set WEBHOOK_TOKEN --agent transcode --env production --stdin
zap secret list          # names, scopes, last4 only
zap secret remove WEBHOOK_TOKEN --agent transcode --env production

Values are encrypted at rest, resolved just-in-time immediately before a request, attached only to that request, and discarded.

Connections

defineConnection allowlists an HTTPS origin, an allowed method list, and a path prefix:

import { bearer, defineConnection, useSecret } from "@wzrdtech/zap-agent";

export const api = defineConnection({
  id: "api",
  origin: "https://api.example.com",
  methods: ["GET", "POST"],
  pathPrefix: "/v1/",
  headers: { Authorization: bearer(useSecret("API_TOKEN")) },
});

At request time:

fetch takes relative paths only; absolute URLs fail closed (CONNECTION_ABSOLUTE_URL).
Methods outside the allowlist fail (CONNECTION_METHOD_DENIED); paths outside the prefix fail (CONNECTION_PATH_DENIED).
Hard-coding sensitive headers (Authorization, Cookie, X-API-Key) as literals is a build error (ZAP_BUILD_SECRET_LITERAL).

Outbound HTTP without a declared connection is denied with SECRET_SCOPE_DENIED.

Redaction

Every resolved key registers with the redaction layer, so any occurrence in logs, run events, or --json output is replaced with [redacted]:

import { registerSecret, redactingLogger } from "@wzrdtech/zap-runtime";

registerSecret(apiKey);
const log = redactingLogger((line) => process.stdout.write(`${line}\n`));

Get Started

Core Concepts

Agents as Code

Runtime Services

Sandboxes

Harnesses & Templates

MCP

Secrets and connections

Write-only secrets

Connections

Redaction

​Write-only secrets

​Connections

​Redaction

Write-only secrets

Connections

Redaction