# ZeroLeaks Developer Context

## Product Selection

Use @zeroleaks/sdk for production-fidelity runtime scans managed by ZeroLeaks. The hosted engine relays probes to the developer's local AI SDK, OpenAI, or custom agent and records complete tool calls and results. It also supports prompt scans, deployed HTTP endpoint scans, agent-skill scans, reports, polling, and cancellation.

Use @zeroleaks/shield inside an LLM application's runtime request path. It hardens system prompts, detects prompt-injection patterns, sanitizes leaked prompt fragments, and wraps common model providers. Its core checks run locally and do not require a ZeroLeaks API key.

Use the zeroleaks package and CLI when scans must run locally or the developer needs direct control over attack agents, probes, knowledge, and orchestration. It uses OPENROUTER_API_KEY rather than a ZeroLeaks cloud key.

## Hosted SDK Setup

Install @zeroleaks/sdk and set:

    ZEROLEAKS_API_KEY=zl_live_...

Initialize:

    import { ZeroLeaks } from "@zeroleaks/sdk";
    const zeroleaks = new ZeroLeaks();

The API key is a server credential. Do not place it in browser bundles, NEXT_PUBLIC_ variables, mobile apps, repositories, or logs.

## Production Runtime Workflow

Wrap the existing production agent with createRuntimeTarget(), @zeroleaks/sdk/ai-sdk, or @zeroleaks/sdk/openai. Then call runtimeScans.run(target).

The SDK sends only serializable target metadata and complete tool definitions to ZeroLeaks. Model keys, executable tool functions, memory, retrieved data, and local state stay in the runner environment. Each invoke/reset relay event is executed through the real target. The SDK preserves session history and submits final text plus observed tool arguments, results, errors, and provider execution state.

All configured tools are included by default. Use scan-safe databases, tenants, email sinks, payment sandboxes, and credentials for irreversible side effects while preserving the same authorization and approval logic as production.

AI SDK supports existing Agent objects or ToolLoopAgent settings. OpenAI supports Responses API and Chat Completions function-tool loops. Custom orchestration should use createRuntimeTarget() so the production handler is invoked exactly.

## Prompt Scan Workflow

Use zeroleaks.scans.run({ systemPrompt, scanMode }) for the high-level workflow. It creates a scan, polls until terminal, and returns the report.

For asynchronous application workflows:

1. POST /api/v1/scans or call scans.create().
2. Store scanId.
3. GET /api/v1/scans/{scanId} or call scans.wait().
4. GET /api/v1/reports/by-scan/{scanId} if a separate report fetch is needed.
5. POST /api/v1/scans/{scanId}/cancel to stop active work.

Prompt scan modes are extraction, injection, dual, sandbox, and full. Optional controls include targetModel, temperature, reasoningEffort, knowledgeProfile, attackSurfaces, userTools, autoDetectTools, and maxAdaptiveCandidates.

## Endpoint Scan Workflow

1. Create an endpoint configuration with endpointConfigs.create() or POST /api/v1/agent-configs.
2. Start a scan with endpointScans.create(configId) or POST /api/v1/agent-scans.
3. Poll endpointScans.get() or GET /api/v1/agent-scans/{scanId}.
4. Cancel through endpointScans.cancel() when needed.

Supported target auth modes are none, bearer, api_key, and custom_header. Authenticated targets require HTTPS. Request formats support custom headers, message/history/session fields, JSON-safe templates, and nested response fields. Target credentials are encrypted and omitted from API reads.

## Skill Scan Workflow

Use skillScans.run({ source }) for remote sources, or skillScans.uploadArchive() for ZIP uploads. Async scans return scanId and can be polled through skillScans.get() or skillScans.wait(). Sync delivery returns the report in the create response.

Skill scan modes are review, risk, behavior, and full. Tool profiles are readonly, standard, and networked.

## Error Policy

- 400: fix the named validation error before retrying.
- 401: replace the missing, invalid, or revoked API key.
- 403: subscription or workspace access prevents the operation.
- 404: verify the resource ID and API-key owner.
- 429: wait for the provided reset time.
- 500 or 503: retry later with bounded backoff.

Do not automatically retry scan-creation POST requests because they are not idempotent.

## Resources

- Docs: https://www.zeroleaks.ai/docs
- SDK: https://www.zeroleaks.ai/docs/sdk
- Shield: https://www.zeroleaks.ai/docs/shield-sdk
- Local package: https://www.zeroleaks.ai/docs/zeroleaks-package
- OpenAPI: https://www.zeroleaks.ai/openapi.json
- Short context: https://www.zeroleaks.ai/llms.txt