Skip to content

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.

incoming requestauth check401 if Bearer / X-Api-Key wrong or missingrate limit429 if over requestsPerMinute + burstbody size check413 if body exceeds maxBodyBytesconcurrency cap503 if over maxConcurrent in-flight requestsworkflow DAG

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:

yaml
# 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 here

Requests 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):

yaml
# ~/.kdeps/config.yaml
api_auth_token: "your-secret-token"

Or with an environment variable:

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

yaml
# 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: nosniff
  • X-Frame-Options: DENY
  • Referrer-Policy: strict-origin-when-cross-origin
  • Permissions-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.

yaml
# workflow.yaml
deploy:
  apiServer:
    rateLimit:
      requestsPerMinute: 60
      burst: 10

For webServer-only workflows, put the same fields under webServer:

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

yaml
# workflow.yaml
deploy:
  apiServer:
    maxBodyBytes: 1048576   # 1 MiB

TLS ​

Static certificates ​

Enable HTTPS with PEM cert/key paths under deploy (not under apiServer):

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

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

yaml
# workflow.yaml
deploy:
  apiServer:
    maxConcurrent: 50

Build-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:

bash
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:

yaml
# deploy/env-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-agent-env
type: Opaque
stringData:
  OPENAI_API_KEY: "sk-..."
yaml
# fragment from kdeps export k8s output
env:
  - name: OPENAI_API_KEY
    valueFrom:
      secretKeyRef:
        name: my-agent-env
        key: OPENAI_API_KEY

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

BackendLimit
dashscope6 MB
xai50 MB
openai100 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 errors

Resource output caps ​

Four environment variables limit how many bytes executor resources return to the workflow engine. Set them in runtime.env.

VariableApplies to
KDEPS_EXEC_MAX_OUTPUT_BYTESShell command stdout (exec component)
KDEPS_HTTP_MAX_RESPONSE_BYTESHTTP resource response body
KDEPS_CHAT_MAX_OUTPUT_BYTESLLM chat response content
KDEPS_PYTHON_MAX_OUTPUT_BYTESPython resource stdout
yaml
# 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 KiB

See also ​

kdeps has the Apache 2.0 License.