Configuration

SDK configuration

Silker works out of the box with safe defaults tuned for low false positives. Override behavior with environment variables or options passed to initSilker().

Environment variables

The SDK resolves these automatically when the matching option is not passed in code.

Variable	Description
`SILKER_API_KEY`	Your application's API key (`sk_…`). Enables telemetry, remote config, and shared bans.
`SILKER_APP_ID`	Optional. Groups data per app. Resolved from the API key when omitted.
`SILKER_ENDPOINT`	Optional. Defaults to `https://platform.silkerai.com` (prod) / `http://localhost:3000` (dev).

initSilker() options

All options are optional. Passing nothing reads from the environment and applies defaults.

config example

import { initSilker, middleware } from '@silker-ai/agent';

initSilker({
  apiKey: process.env.SILKER_API_KEY, // sk_...
  profile: 'saas',                    // 'strict' | 'saas' | 'audit'
  trustProxy: true,                   // read client IP from X-Forwarded-For
  maxPayloadSize: 1048576,            // max inspected body size in bytes (1MB)
  remoteConfig: true,                 // pull feature toggles from the dashboard
  telemetry: { sampleRate: 1.0 },     // share of request events sent (threats always 100%)
  rateLimit: { windowMs: 60000, maxRequests: 60, banDurationMs: 60000 },
  features: { ssrfDetection: true },  // per-feature overrides
});

app.use(middleware());

Options reference

apiKeystringoptionaldefault: env SILKER_API_KEY

Cloud API key. Without it, the SDK runs in detection-only mode (no telemetry) and never throws.

appIdstringoptionaldefault: env SILKER_APP_ID

Application identifier for grouping data. The platform resolves it from the API key if omitted.

endpointstringoptionaldefault: platform.silkerai.com

Override the cloud endpoint (self-host / dev).

profile'strict' | 'saas' | 'audit'optional

Preset bundle of feature defaults. Explicit features always win over the profile.

featuresSilkerFeaturesoptional

Per-feature toggles. See the full list in Security features.

trustProxybooleanoptionaldefault: true

Read the real client IP from X-Forwarded-For / X-Real-IP. Set false only when the app is not behind a proxy/CDN/load balancer - otherwise the header is spoofable and per-IP bans become unreliable.

maxPayloadSizenumberoptionaldefault: 1048576

Maximum request body size (bytes) inspected for threats. Capped at 100MB.

rateLimitRateLimitConfigoptional

{ windowMs?, maxRequests?, banDurationMs? } - defaults to 60 requests / minute with a 60s ban on breach.

remoteConfigbooleanoptionaldefault: true

Pull dashboard-managed feature flags on each telemetry sync, so toggles take effect without a redeploy. Set false to keep config purely in code/env.

telemetry{ sampleRate?: number }optionaldefault: 1.0

Share of normal request events reported (0–1). Threats are always sent at 100%. Lower it to cut ingest cost under heavy traffic.

blockOutgoingbooleanoptionaldefault: false

Block outgoing fetch calls flagged as anomalous. Default is monitor-only (telemetry).

allowedHostsstring[]optional

Allow-list for Host-header validation. No validation by default.

threatIntel{ ips?: string[]; domains?: string[] }optional

Extra IPs/domains merged with the built-in threat-intelligence lists.

storeSilkerStateStoreoptional

Pluggable shared store (e.g. Redis) so rate-limit counters and IP bans stay consistent across multiple instances. Local memory remains authoritative; the external store is mirrored best-effort.

waitUntil(p: Promise) => voidoptional

Serverless lifecycle hook (Vercel waitUntil / Next after) to deliver telemetry after the response without blocking the request path.

debugbooleanoptionaldefault: false

Verbose logging for local debugging.

Remote config

When remoteConfig is enabled (the default), feature toggles managed in the dashboard are the source of truth. The ingest response carries the resolved feature set, and the SDK applies it on the next sync - so you can turn detections on/off per app without shipping code.

Disabling cloudCommunication (or running without an API key) stops telemetry and remote config. Local detection still works, but the dashboard will show no data.

Shared state store (multi-instance)

Behind a load balancer, give every instance the same store so rate limiting and IP bans are consistent. Implement the SilkerStateStore interface (e.g. backed by Redis) and pass it as store.