Security reference
Each request goes through a chain of gates before it gets to the workflow DAG. Each gate can reject the request with a specific status code. This applies when you configure an apiServer.
Authentication
When you configure apiServer, authentication is necessary. Each request must include the token in Authorization: Bearer <token> or X-Api-Key: <token>. The /health endpoint never needs a token. /_kdeps/* management routes use KDEPS_MANAGEMENT_TOKEN instead (see Management API). kdeps refuses to start the API server without a token. The kdeps API is a separate loopback listener (KDEPS_API_TOKEN) and is not this workflow gate.
Public routes
Routes that serve a browser frontend can disable bearer auth with public: true. A static page cannot keep a secret. All data in the JS is public:
# workflow.yaml
deploy:
apiServer:
routes:
- path: /api/v1/chat
methods: [POST]
public: true # no token needed for credential-less requests
- path: /api/v1/admin
methods: [POST] # token still required hereRequests with no credentials pass. kdeps validates a token if the request has one, so a wrong Authorization header always gets 401. In merged API+Web mode, the webServer routes are always public, because browser navigation cannot send a header. But paths of an API route always need authentication, unless you mark them public: true.
Set the token in ~/.kdeps/config.yaml (machine-local, never committed):
# ~/.kdeps/config.yaml
api_auth_token: "your-secret-token"Or with an environment variable:
export KDEPS_API_AUTH_TOKEN="your-secret-token"No auth: block in workflow.yaml. The token is never stored in the workflow file.
Trusted proxies
kdeps ignores X-Forwarded-For and X-Real-IP unless the direct TCP peer matches an entry in trustedProxies. This prevents clients from spoofing their IP for rate limiting and request context. Configure CIDRs or exact IPs for your load balancer or ingress.
# workflow.yaml
deploy:
apiServer:
trustedProxies:
- "10.0.0.0/8"
- "172.16.0.0/12"
- "192.168.0.0/16"Without trustedProxies, kdeps uses RemoteAddr only. When you configure apiServer and webServer, kdeps merges the entries from both blocks for rate limiting and request IP context.
Security headers
Both apiServer and webServer responses include defensive HTTP headers on every response:
X-Content-Type-Options: nosniffX-Frame-Options: DENYReferrer-Policy: strict-origin-when-cross-originPermissions-Policy: camera=(), microphone=(), geolocation=()Strict-Transport-Security: max-age=31536000; includeSubDomains(TLS only)
apiServer also sets a strict Content-Security-Policy (default-src 'none'; frame-ancestors 'none'; base-uri 'none') on JSON API responses. webServer omits CSP so proxied apps (Streamlit, Gradio, SPAs) are not blocked.
webServer-only mode
When you configure only webServer (no apiServer), kdeps does not enforce bearer auth. If static files and app proxies bind to 0.0.0.0, all clients can read them. To prevent this, add an ingress with auth. You can still set rateLimit, maxBodyBytes, and maxConcurrent under webServer to throttle abuse.
Rate limiting
Limit requests per client IP using a token-bucket algorithm. requestsPerMinute is the sustained rate. burst is the number of requests that a client can send above that rate in one burst. Clients that exceed the limit receive a 429 response with a Retry-After: 60 header.
# workflow.yaml
deploy:
apiServer:
rateLimit:
requestsPerMinute: 60
burst: 10For webServer-only workflows, put the same fields under webServer:
# workflow.yaml
deploy:
webServer:
rateLimit:
requestsPerMinute: 120
burst: 20
maxBodyBytes: 1048576
maxConcurrent: 50
routes:
- path: "/"
serverType: "static"
publicPath: "./public"Body size limit
Set the maximum size of request bodies. Requests that exceed maxBodyBytes receive a 413 response. This limit does not apply to multipart/form-data uploads.
# workflow.yaml
deploy:
apiServer:
maxBodyBytes: 1048576 # 1 MiBTLS
Static certificates
Enable HTTPS with PEM cert/key paths under deploy (not under apiServer):
# workflow.yaml
deploy:
certFile: "/etc/certs/server.crt"
keyFile: "/etc/certs/server.key"
apiServer:
routes:
- path: /api/v1/chat
methods: [POST]Let's encrypt (custom domain)
Automatic ACME certificates for a custom domain (HTTP-01 on port 80 + TLS-ALPN-01 on HTTPS). Point DNS A/AAAA at this host. Prefer listen :443.
# workflow.yaml
deploy:
letsEncrypt:
domain: api.example.com # required primary hostname
domains: # optional SANs
- www.example.com
email: ops@example.com # recommended for expiry notices
cacheDir: /var/lib/kdeps/letsencrypt # optional; default ~/.kdeps/letsencrypt
staging: false # true = LE staging CA (browsers untrusted)
# httpChallengeAddr: ":80" # default; set "" to disable HTTP-01
apiServer:
hostIp: "0.0.0.0"
portNum: 443
routes:
- path: /api/v1/chat
methods: [POST]If you set certFile/keyFile and letsEncrypt, static PEM has priority. The same settings apply to webServer when it is enabled.
Docker/K8s: publish 80 and 443. Keep cacheDir on a writable volume.
Full guide: TLS and HTTPS (Custom Domains).
Concurrent request limit
Set the maximum number of requests that run at the same time. At the limit, new requests receive 503 Service Unavailable immediately. They do not wait in a queue. Omit or set to 0 to disable.
# workflow.yaml
deploy:
apiServer:
maxConcurrent: 50Build-time env (Docker and Kubernetes export)
kdeps puts runtime.env into generated Dockerfiles and Kubernetes manifests. Plain keys become ENV / value: entries. kdeps rejects auth tokens at Docker build time (KDEPS_API_AUTH_TOKEN, KDEPS_MANAGEMENT_TOKEN) and any secret-like key (_TOKEN, _SECRET, _PASSWORD, _API_KEY, and similar) in both Docker and Kubernetes export.
Set those at runtime instead:
docker run -e KDEPS_API_AUTH_TOKEN=api-secret -e KDEPS_MANAGEMENT_TOKEN=mgmt-secret -e OPENAI_API_KEY=sk-...Kubernetes export maps auth tokens to {metadata.name}-auth and secret-like runtime.env keys to {metadata.name}-env with secretKeyRef. kdeps never writes the values into the manifest:
# deploy/env-secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: my-agent-env
type: Opaque
stringData:
OPENAI_API_KEY: "sk-..."# fragment from kdeps export k8s output
env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: my-agent-env
key: OPENAI_API_KEYRequest body size preflight
kdeps checks the request body size before every LLM API call. Providers with strict payload caps (e.g. DashScope at 6 MB) silently reject oversized requests, so the preflight returns an actionable error before the call. A workflow chat: checks its first call and each tool-round follow-up.
Each limit is a provider-body-limit-<backend> event. Override it in ~/.kdeps/events/, or turn it off for no limit.
| Backend | Limit |
|---|---|
dashscope | 6 MB |
xai | 50 MB |
openai | 100 MB |
| (all others) | No known limit |
If the estimated size is more than the limit of the provider, kdeps blocks the call with a clear error:
request body size ~5.5 MB exceeds dashscope limit of 6.0 MB
(reduce context window, trim conversation history, or switch models)At startup, kdeps warns about backends with limits under 10 MB:
WARN backend "dashscope" has a 6.0 MB request body limit --
reduce MaxHistoryTokens if you hit payload errorsResource output caps
Four environment variables limit how many bytes executor resources return to the workflow engine. Set them in runtime.env.
| Variable | Applies to |
|---|---|
KDEPS_EXEC_MAX_OUTPUT_BYTES | Shell command stdout (exec component) |
KDEPS_HTTP_MAX_RESPONSE_BYTES | HTTP resource response body |
KDEPS_CHAT_MAX_OUTPUT_BYTES | LLM chat response content |
KDEPS_PYTHON_MAX_OUTPUT_BYTES | Python resource stdout |
# workflow.yaml
deploy:
runtime:
env:
KDEPS_EXEC_MAX_OUTPUT_BYTES: "524288" # 512 KiB
KDEPS_HTTP_MAX_RESPONSE_BYTES: "1048576" # 1 MiB
KDEPS_CHAT_MAX_OUTPUT_BYTES: "1048576" # 1 MiB
KDEPS_PYTHON_MAX_OUTPUT_BYTES: "524288" # 512 KiBSee also
- Advanced configuration - Request object, agent settings, SQL connections, trusted proxies
- Docker reference - Container security hardening
- Validation and control flow - Per-resource access control
