Advanced Settings¶

This section covers advanced configuration options for Pixee Enterprise Server.

External Database¶

For production environments, it is recommended to configure an external database when deploying into production. See the installation prerequisites for requirements.

Embedded ClusterHelm Deployment

To configure external database in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Under Database Type select External.

Provide the following information:

Database host
Database port
Database username
Database password
Database name

To configure external database in Helm Deployment follow:

You can configure Pixee Enterprise Server to use an external database server. If you prefer to use the in-cluster, embedded database, you may skip this step.

To configure an external database, add the following to your values.yaml:

platform:
  database:
    embedded: false
    host: "<your database hostname>"
    port: "<your database server port, defaults to 5432>"
    name: "<your database name, defaults to pixee_platform>"
    username: "<your database user with access to database>"
    password: "<your database user password>"
    # -- Use an existing secret for the password instead of passing directly in Values.  Secret must contain a `password` key.
    existingSecret: "<your postgres secret name>"

Analysis Service Database (Optional)

The analysis service can use a separate logical database for episodic memory (Case-Based Reasoning). This is optional — if not configured, analysis-service runs normally without this feature.

To enable it, create an analysis_service database on your PostgreSQL server and add the following to your values.yaml:

analysis:
  database:
    host: "<your database hostname>"
    port: 5432
    name: "analysis_service"
    username: "analysis"
    password: "<your analysis database user password>"
    # -- Or use an existing secret with `username` and `password` keys.
    existingSecret: ""

Embedded Database Credential Secrets¶

When using the embedded database (platform.database.embedded: true), Pixee Enterprise Server automatically creates Kubernetes secrets for CloudNative-PG managed database roles used by Superset and Authentik. If you prefer to manage these secrets yourself (e.g., via an external secrets operator), you can provide your own pre-existing secrets instead.

Embedded ClusterHelm Deployment

Embedded Cluster deployments manage these secrets automatically. No additional configuration is needed.

To use existing secrets for Superset and/or Authentik database credentials, first create the secret(s):

Superset database credentials:

apiVersion: v1
kind: Secret
metadata:
  name: my-superset-postgresql-credentials
type: kubernetes.io/basic-auth
stringData:
  username: "superset"
  password: "<your-password>"

Authentik database credentials:

apiVersion: v1
kind: Secret
metadata:
  name: my-authentik-postgresql-credentials
type: kubernetes.io/basic-auth
stringData:
  username: "authentik"
  password: "<your-password>"

Then reference them in your values.yaml:

superset:
  database:
    existingSecret: "my-superset-postgresql-credentials"

authentik:
  database:
    existingSecret: "my-authentik-postgresql-credentials"

Object Store¶

Embedded Object Store¶

You can configure Pixee Enterprise Server to use an embedded object store. This is the default configuration and is suitable for development and testing environments.

When embedded object store is enabled, you will also be prompted to configure the Object Store Expiry in Days for the object store. This setting determines how long objects will be retained in the embedded object store before they are automatically deleted.

External Object Store¶

You can configure Pixee Enterprise Server to use an external object store. If you prefer to use the in-cluster, embedded object store, you may skip this step.

Requirements¶

The following are requirements of an external object store compatible with Pixee Enterprise Server:

The object store and the Kubernetes cluster are able to communicate over the network
The object store exposes a S3 compatible API
A bucket has been created for use as the pixee-analysis-input bucket

Embedded ClusterHelm Deployment

To configure external object store in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Under Object Store Type select External.

Provide the following information:

Object store endpoint URL
Object store username (Access Key ID)
Object store password (Secret Access Key)
Bucket name for pixee analysis inputs
Bucket name for the pixee analysis service

To configure external object store with static credentials in Helm Deployment follow:

Static Credentials¶

To configure an external object store, add the following to your values.yaml:

global:
  pixee:
    objectStore:
      embedded: false
      endpoint: "<your object store endpoint url>"
      username: "<your object store username>"  # Access Key ID for S3
      password: "<your object store password>"  # Secret Access Key for S3
      credentialType: "static"
platform:
  inputBucket: "<your provisioned bucket name for pixee analysis inputs>"
analysis:
  objectStore:
    bucket: "<your provisioned bucket name for the pixee analysis service>"

Service Account Authentication¶

For enhanced security, you can use Kubernetes service account authentication instead of static credentials. This approach leverages cloud provider IAM roles and eliminates the need for long-lived access keys.

To configure service account authentication, add the following to your values.yaml:

global:
  pixee:
    serviceAccount:
      create: false
      name: "your-external-service-account"
    objectStore:
      embedded: false
      endpoint: "<your object store endpoint url>"
      region: "<your object store region>"
      credentialType: "default"
      # username and password are not required with service account auth
platform:
  inputBucket: "<your provisioned bucket name for pixee analysis inputs>"
analysis:
  objectStore:
    bucket: "<your provisioned bucket name for the pixee analysis service>"

Git Clone Strategy¶

Pixee Enterprise Server supports two Git cloning strategies for VCS operations:

Partial Clone (Default): Downloads only the specific commit, tree, and blob objects needed for the requested revision. This provides optimal performance and minimal bandwidth usage but may not be supported by all Git servers.
Full Clone: Downloads the complete repository including all history, branches, and objects. While this requires more time and bandwidth, it ensures maximum compatibility with all Git servers.

Embedded ClusterHelm Deployment

To configure the Git clone strategy in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Under Git Clone Strategy, select either:

Partial (recommended - faster, less bandwidth): For optimal performance
Full (maximum compatibility): For environments where partial clones are not supported

To configure the Git clone strategy in Helm deployments, add the following to your values.yaml:

platform:
  gitCloneStrategy: "partial"  # or "full" for maximum compatibility

The default value is partial for optimal performance. Change to full if you encounter issues with Git servers that don't support partial clones.

Git Author Identity¶

When using a service account for Git operations (e.g., a GitLab service account), you may need to configure the author email and username that Pixee uses when creating commits. You can retrieve these values from your VCS provider's API:

# GitLab example — username
curl -s -H "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/user" | jq '.username'

# GitLab example — email (separate endpoint)
curl -s -H "Authorization: Bearer $GITLAB_TOKEN" "https://gitlab.com/api/v4/user/emails" | jq '.[0].email'

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Under Git Author Email and Git Author Username, enter the service account's email and username.

Add the following to your values.yaml:

platform:
  gitAuthorEmail: "service-account@example.com"
  gitAuthorUsername: "pixee-bot"

Error Reporting¶

By default, Pixee Enterprise Server will send error and crash reports to Pixee via Sentry.io.

Embedded ClusterHelm Deployment

To configure error reporting in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section.

To disable automatic error and crash reporting, uncheck the error reporting option.

To configure error reporting in Helm Deployment follow:

To disable automatic error and crash reporting, add the following to your values.yaml:

global:
  pixee:
    sentry:
      enabled: false

HTTP(S) Proxy Settings¶

You can configure Pixee Enterprise Server to route HTTP/HTTPS traffic through a proxy server.

NO_PROXY Configuration Limitations¶

Important: NO_PROXY Wildcard Limitations

The NO_PROXY environment variable in Pixee Enterprise Server does not support wildcard patterns. You must specify exact hostnames or IP addresses.

Not Supported:

NO_PROXY=*.internal.company.com
NO_PROXY=10.0.*.*

Supported (Required Format):

NO_PROXY=service1.internal.company.com,service2.internal.company.com,10.0.1.5,10.0.2.10

This limitation means that if you have multiple internal services that should bypass the proxy, each hostname must be explicitly listed in the NO_PROXY configuration.

Embedded ClusterHelm Deployment

To configure HTTP(S) proxy in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section.

Select the Configure HTTP(S) Proxy checkbox if you need to route HTTP/HTTPS traffic through a proxy server. Once enabled, you can configure or modify the HTTP and HTTPS proxy server addresses as well as provide a comma separated list of domains to exclude from using your HTTP/HTTPS proxy.

Note: The NO_PROXY field requires exact hostnames or IP addresses. Wildcard patterns are not supported.

To configure HTTP(S) proxy in Helm Deployment follow:

Add the following to your values.yaml:

global:
  pixee:
    httpProxy: "<address>:<port>"     # HTTP proxy server host/address and port
    httpsProxy: "<address>:<port>"    # HTTPS proxy server host/address and port  
    noProxy: "<comma,separated,hosts>" # Comma separated list of exact hostnames/IPs to exclude from proxy (wildcards not supported)

Example configuration:

global:
  pixee:
    httpProxy: "proxy.company.com:8080"
    httpsProxy: "proxy.company.com:8080"
    noProxy: "kubernetes.default,kubernetes.default.svc,10.0.0.1,database.internal.company.com,api.internal.company.com"

Private CA Certificates¶

If your environment uses self-signed certificates or a private Certificate Authority (CA), you can configure Pixee Enterprise Server to trust these certificates.

Embedded ClusterHelm Deployment

Embedded Cluster automatically detects and uses the host system's CA trust store at install time. Ensure your private CA certificates are installed on the host before running the Embedded Cluster installer — no additional Pixee configuration is needed.

Updating CA certificates after installation:

If you need to add new CA certificates after the initial installation:

Update the host's CA trust store (e.g. add the certificate and run update-ca-trust)
Wait up to one hour for the kotsadm-private-cas ConfigMap to refresh automatically, or force an immediate refresh:
```
kubectl rollout restart deployment/embedded-cluster-operator -n embedded-cluster
```

Restart the Pixee platform deployment to pick up the new certificates:

kubectl rollout restart deployment/pixee-platform -n <namespace>

Create a ConfigMap containing your PEM-encoded CA certificate(s):

kubectl create configmap my-ca-certs \
  --from-file=ca.pem=/path/to/your/ca-certificate.pem \
  -n <namespace>

Then reference it in your values.yaml:

global:
  pixee:
    privateCACert: "my-ca-certs"

The ConfigMap may contain one or more PEM files, each with one or more certificates. All certificates will be imported into the trust stores used by the platform, analysis, and forge services.

Updating CA certificates:

To add or replace certificates, update the ConfigMap and restart the platform deployment:

kubectl rollout restart deployment/pixee-platform -n <namespace>

Deprecated: Skip SSL Verification

The global.pixee.skipSSLVerification Helm value (and the corresponding KOTS admin console checkbox) is deprecated and will be removed in a future release. This setting disables ALL certificate verification for outbound HTTPS connections, which is a security risk. Use private CA certificates instead.

Host Aliases¶

You can configure a custom host-to-IP mapping (/etc/hosts entry) for the Platform pods. This is useful for environments with private DNS, split-horizon DNS, or services not resolvable via the cluster's DNS.

Embedded ClusterHelm Deployment

To configure host aliases in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Select the Enable Custom Host Aliases checkbox.

Once enabled, enter host aliases in /etc/hosts format in the text area — one entry per line, with an IP address followed by one or more space-separated hostnames. Lines starting with # are treated as comments and ignored.

Example:

10.0.0.1 service.internal api.internal
192.168.1.100 db.internal

To configure host aliases in Helm deployments, add the following to your values.yaml:

platform:
  hostAliases:
    - ip: "10.0.0.1"
      hostnames:
        - "service.internal"
        - "api.internal"

Each entry maps an IP address to one or more hostnames, which are added to the pod's /etc/hosts file.

Metrics Reporting¶

By default, Pixee Enterprise Server will send anonymized usage metrics to Pixee.

Embedded ClusterHelm Deployment

To configure metrics reporting in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section.

To disable metrics reporting, uncheck the metrics reporting option.

To configure metrics reporting in Helm Deployment follow:

To disable metrics reporting, add the following to your values.yaml:

global:
  pixee:
    metrics:
      enabled: false

Object Store Signature Duration¶

By default, Pixee Enterprise Server generates pre-signed URLs for object store operations with a system-defined expiration duration. You can customize this duration by configuring the signature duration setting.

The duration should be specified as a string with time units. Common examples: "1h" (1 hour), "30m" (30 minutes), "2h" (2 hours), "45m" (45 minutes). If not configured, the system will use its default behavior.

Embedded ClusterHelm Deployment

To configure signature duration in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Object Store Signature Duration field.

To configure signature duration in Helm Deployment follow:

To configure a custom signature duration for pre-signed URLs, add the following to your values.yaml:

platform:
  inputSignatureDuration: "<duration>"

Reverse Proxy Settings¶

If your Pixee Enterprise Server is accessible via a reverse proxy (i.e., ALB, App Gateway, NGINX, etc.), you may need to configure additional settings.

Two requirements that come before the reverse proxy settings

1. Domain name must be the hostname browsers use. Pixee builds every browser-facing URL from the Domain name in the Network settings — the OIDC authorization endpoint, the OAuth2 redirect_uri, the token issuer, and the logout URL are all absolute URLs fixed at deploy time from that value. Set it to the cluster's own address or to the origin address your proxy was configured with, and clicking Continue on the login page redirects the browser to a host it cannot reach (ERR_CONNECTION_TIMED_OUT). No X-Forwarded-* header changes this: those URLs are not reconstructed per request.

2. Your proxy must send that same hostname in the Host header. The cluster's gateway routes on Host alone — it serves only requests whose Host matches Domain name, and it does not consult X-Forwarded-Host. A proxy that rewrites Host to its own origin address therefore gets 404 Not Found on every request, before anything reaches the application at all. Authentik itself is more tolerant here: it accepts X-Forwarded-Host or Host when building its own URLs. That tolerance does not help, because the request never gets past the gateway to reach it.

The two must agree: Domain name and the Host header your proxy sends are the same value. Forwarded headers are useful in addition to this, never instead of it.

Where the proxy cannot be changed, Additional accepted hostnames lets the cluster answer to the rewritten Host as well, while Domain name stays the public hostname — see When You Cannot Change the Proxy. It resolves requirement 2 only; requirement 1 is unchanged.

Which forwarded headers your proxy actually needs

Once Host carries the public hostname, X-Forwarded-Host is redundant — the gateway matches on Host, Authentik accepts Host, and the browser-facing OIDC URLs come from Domain name rather than from any header. Sending it does no harm, but it is not what makes the deployment work.

Two of its siblings are not redundant:

X-Forwarded-Proto — required whenever your proxy terminates TLS and forwards HTTP to the cluster. Without it the application generates http:// links for anything it builds per request.
X-Forwarded-Port — required when the public URL uses a non-standard port that the Host header does not carry.

Your proxy should also strip any inbound X-Forwarded-* headers it did not set itself, since the application trusts the ones it receives.

Embedded ClusterHelm Deployment

To configure reverse proxy settings in Embedded Cluster deployments follow:

Navigate to the admin console, select the Config tab, then go to the Network Settings section. Every setting in this section — the domain name, the port, the reverse proxy options, and the TLS options — is configured there together.

Check Behind a reverse proxy, load balancer, or CDN
Select TLS Termination:
- TLS at this server — the server serves HTTPS and the reverse proxy forwards encrypted traffic
- TLS at reverse proxy — the reverse proxy terminates TLS and forwards HTTP to the cluster
- No TLS (HTTP only) — no encryption, not recommended for production

To configure reverse proxy settings in Helm Deployment follow:

Add the following applicable settings to your values.yaml:

global:
  pixee:
    # Set externalProtocol when the reverse proxy terminates TLS and the cluster serves HTTP
    externalProtocol: "https"  # protocol used by browsers (omit to use the same as protocol)
platform:
  proxy:
    enabled: true

Forwarded headers are always honored, and are never filtered by proxy address

Pixee Enterprise Server honors X-Forwarded-Proto, X-Forwarded-Port, X-Forwarded-Host and Forwarded on every deployment, and there is no setting that turns that off. It trusts whichever client sent them and offers no trusted-proxy allow-list, so rejecting forwarded headers from unexpected sources has to happen at your proxy — which should strip any inbound X-Forwarded-* headers it did not set itself.

Releases before 6.1 exposed a Reverse Proxy Forwarded Headers checkbox and a Reverse Proxy Address Filter field in the admin console, along with platform.proxy.address and platform.proxy.headers.* in Helm. None of them ever took effect — the checkbox was read by no template at all, and the address filter rendered a Tomcat trusted-proxy setting that the forward-headers strategy this chart always uses ignores — and all of them have been removed. Leaving them in an existing values.yaml is harmless — Helm ignores unrecognized values — but they never provided the trusted-proxy boundary the address filter's wording implied.

None of this affects the browser-facing OIDC URLs, which are built from Domain name and never from a request header.

The cluster restores X-Forwarded-Proto when your proxy terminates TLS

Envoy sets X-Forwarded-Proto from the port the request arrived on and overwrites whatever your proxy sent, so with TLS Termination set to TLS at reverse proxy the header would otherwise reach the application as http even though the browser is on https. Components that build URLs from the request — Authentik most visibly, since it publishes the OIDC issuer and authorization endpoint — would then advertise http:// endpoints, and sign-in fails with no message naming a scheme.

The gateway routes therefore set the header back to the browser-facing scheme. This happens automatically from TLS Termination; there is no setting for it, and nothing changes on a deployment that serves HTTPS from the cluster.

CDNs and Proxies That Rewrite the Host Header¶

Many proxies default to replacing the Host header with the address of the origin they were configured with, rather than passing through the hostname the client requested. Because the cluster's gateway serves only requests whose Host matches the Domain name setting, each of these needs an explicit override:

Product	Setting	Value
Azure Front Door	Origin → Origin host header	your public endpoint hostname (e.g. `contoso.azurefd.net`), not the origin IP or FQDN
Azure Application Gateway	Backend setting → Override with new host name	Off, so the incoming host is preserved — or set explicitly to the public hostname
AWS CloudFront	Origin request policy	include `Host` in the headers forwarded to the origin
AWS ALB / NLB	—	preserved by default; no action needed
NGINX	`proxy_set_header Host $host;`	(`$host`, not `$proxy_host`)
HAProxy	leave `Host` untouched	do not `http-request set-header Host`

Setting Domain name to the public hostname and configuring the host-header override are a single change — apply both together. Changing only Domain name makes the gateway reject every request; changing only the proxy leaves the login redirects pointing at the internal address.

When You Cannot Change the Proxy¶

Preserving the original Host at the proxy is the recommended configuration, and the rest of this section assumes it. Where the proxy is managed by another team and cannot be changed, Additional accepted hostnames is the fallback: it tells the cluster to answer to further Host values on top of Domain name.

Set the two together:

Domain name — the hostname users type in their browser. Every browser-facing URL is built from this, so it must stay the public hostname.
Additional accepted hostnames — the address the proxy actually sends, as a comma-separated list (for example the origin IP, 10.0.90.4).

Embedded ClusterHelm Deployment

Enable Behind a reverse proxy, load balancer, or CDN
Leave Domain name set to your public hostname
Enter the proxy's origin address in Additional accepted hostnames

global:
  pixee:
    domain: "pixee.example.com"        # public hostname; browser-facing URLs
    gatewayHostnames:                  # what the proxy actually sends
      - "10.0.90.4"

This setting widens routing only — it is not a second domain. Requests arriving with either Host are routed, and every browser-facing URL continues to be built from Domain name alone. That is deliberate: the two values exist precisely so that a rewritten Host does not drag the OIDC redirects onto an address the browser cannot reach.

It is also the mechanism for a zero-downtime rename: add the new hostname, cut the DNS and the proxy over, change Domain name, then drop the old entry.

Validate sign-in before relying on this in production

This setting fixes routing — requests stop returning 404. It does not change how Authentik derives the absolute URLs it generates per request, and the CLI device flow compares the token issuer as an exact string. Both depend on the proxy forwarding X-Forwarded-Host with the original hostname. Confirm browser sign-in, pixee login from the CLI, and the Superset dashboards in a non-production environment before rolling this out; if any of them fail, the supported fix remains the host-header override in the table above.

Not available with a cluster-generated or Let's Encrypt certificate

Accepting more than one hostname requires the gateway's listener to stop filtering by name, and that listener hostname is exactly what cert-manager derives the certificate's DNS names from. With TLS Options set to Generate or Request, clearing it would leave the certificate never issued on a new install, and never renewed on an existing one — HTTPS would fail weeks later, far from the setting that caused it. Rather than ship that, the deployment refuses to start with both configured, naming this setting in the error.

Two supported combinations:

Protocol → HTTP, with TLS Termination → TLS at reverse proxy — the proxy terminates TLS and the cluster serves plain HTTP, so no certificate is involved. This is the usual arrangement behind a CDN.
Protocol → HTTPS, with TLS Options → Upload TLS certificate — you supply the certificate, so nothing is derived from the listener. Include every accepted hostname in it, or use a certificate the proxy is configured not to validate by name.

TLS Termination → TLS at reverse proxy is not sufficient by itself. That setting controls the scheme in browser-facing URLs; it does not change what this server serves. Leaving Protocol on HTTPS with TLS Options on Generate or Request keeps the certificate in play and the deployment will still refuse to start. Change it as well.

Do not cache authentication endpoints

A CDN in front of Pixee must not cache /authentik/* or /api/*. Caching an OIDC authorization response — or caching with a cache key that ignores query strings, which is the default on several CDNs once caching is switched on — makes Authentik serve a stale response to a request carrying entirely different OAuth2 parameters. The symptom is an Authentik Client ID Error — the client identifier (client_id) is missing or invalid page even though the URL plainly contains client_id=pixee. Disable caching on the route, or confine it to static asset paths and set the cache key to use the full query string.

Origin certificate validation

If your CDN or proxy reaches the cluster over HTTPS, changing the host header it sends also changes the name it validates the origin certificate against. Either install a certificate on the cluster matching the public hostname, disable origin certificate subject-name validation on the proxy, or terminate TLS at the proxy and set TLS Termination to TLS at reverse proxy.

Non-Standard Port (Load Balancer)¶

If your load balancer exposes Pixee Enterprise Server on a non-standard port (e.g., port 5443 instead of 443), additional configuration is required so that OIDC authentication redirects include the correct port.

Set the port here, and forward it too

Entering the port in the Non-standard port field is what puts it into the OIDC authorization endpoint and redirect_uri — those are absolute URLs built from Domain name plus this port, so the setting is required.

Your load balancer should also forward the port, via one of these headers:

X-Forwarded-Host with the port included (e.g., X-Forwarded-Host: yourdomain.com:5443), or
X-Forwarded-Port as a separate header (e.g., X-Forwarded-Port: 5443)

That is what carries the port into the other absolute links the application generates per request. Most load balancers (ALB, HAProxy, NGINX) set these automatically for non-standard ports.

Embedded ClusterHelm Deployment

Check Use non-standard port? at the end of the section
Enter the port number in Non-standard port (e.g., 5443)

This applies whether or not a reverse proxy is configured, so a deployment reached on a NodePort can set it too.

The non-standard port setting is what puts the port into the browser-facing OIDC URLs (authorization endpoint, redirect_uri, end-session endpoint). The X-Forwarded-Host / X-Forwarded-Port headers from your load balancer carry it into the rest of the absolute links the application generates.

Add the port to your values.yaml:

global:
  pixee:
    port: "5443"  # your non-standard port
platform:
  proxy:
    enabled: true

How it works

The OIDC URLs are fixed at deploy time, not reconstructed from request headers:

Browser-facing OIDC URLs — the authorization endpoint, the OAuth2 redirect_uri, the token issuer, and the end-session URL — are absolute URLs built from Domain name, the TLS configuration, and the non-standard port. Entering the port is what puts it into all of them.
Forwarded headers apply to the other absolute links the application generates per request. They do not override the browser-facing OIDC URLs, so forwarded headers alone cannot compensate for a wrong Domain name or a missing port.

Both are needed for the full flow to work with a non-standard port, but only the Non-standard port setting affects the OIDC URLs.

Analysis Timeout Settings¶

Pixee Enterprise Server uses a two-tier timeout model to decide when an in-progress analysis is stuck and should be failed. Both tiers run continuously; whichever trips first ends the analysis. The idle timeout must always be shorter than the progress-stall timeout.

Idle timeout (Tier 1)¶

The idle timeout controls how long the platform waits without any sign of life from the analysis service — any streaming event (keepalive pings included) or result callback. Because keepalives reset it, the idle timeout only needs to be long enough to detect a genuinely silent or dead analysis. Default: 15m.

In the admin console this is Analysis idle timeout; in Helm it is platform.analysisTimeout. (The underlying setting key is unchanged from earlier releases for upgrade compatibility.)

Progress-stall timeout (Tier 2)¶

The progress-stall timeout controls how long the platform waits without the analysis completing any result outcome. Unlike the idle timeout, keepalives do not reset it — only real progress (a completed finding) does. This reclaims an analysis that keeps pinging but is not making progress, while letting a legitimately long analysis (for example, one with many findings) run as long as it keeps completing findings, regardless of total elapsed time. Default: 45m.

In the admin console this is Analysis progress-stall timeout; in Helm it is platform.analysisMaxProgressStall.

SAST and SCA analysis timeouts (deprecated)¶

Deprecated. sastAnalysisTimeout / scaAnalysisTimeout are superseded by the idle and progress-stall timeouts above, which apply uniformly across analysis types. They are still honored if set, but will be removed in a future release — leave them unset. Note that the idle timeout's behavior changed (it is now reset by keepalives rather than only by completed outcomes), and an idle timeout larger than the progress-stall timeout has no effect because the progress-stall timeout trips first.

Embedded ClusterHelm Deployment

To configure analysis timeouts in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section.

Analysis idle timeout: Tier 1 — silence detection; reset by any event including keepalives (default: 15m)
Analysis progress-stall timeout: Tier 2 — reset only by completed outcomes (default: 45m)
SAST analysis timeout (deprecated): leave unset
SCA analysis timeout (deprecated): leave unset

The duration should be specified as a string with time units. Common examples: "15m" (15 minutes), "30m" (30 minutes), "1h" (1 hour). The idle timeout must be less than the progress-stall timeout.

To configure analysis timeouts in Helm deployments, add the following to your values.yaml:

platform:
  analysisTimeout: "15m"            # Tier 1 idle timeout (reset by any event, keepalives included)
  analysisMaxProgressStall: "45m"   # Tier 2 progress-stall timeout (reset only by completed outcomes)
  # sastAnalysisTimeout / scaAnalysisTimeout are deprecated and will be removed in a future release

Analysis Queue Max Concurrency¶

Controls the maximum number of analyses the platform dispatches to the analysis service at once. The analysis service applies back-pressure (HTTP 429 with Retry-After) when it cannot accept more work, so this knob primarily caps how many in-flight analyses the platform will hold open concurrently.

Leave the value blank or unset to use the platform default. Raise it when the analysis service has spare capacity and you want to increase throughput; lower it to be more conservative.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Set Analysis queue max concurrency to a positive integer (e.g., 10). Leave it blank to keep the platform default.

Add the following to your values.yaml:

platform:
  analysisQueueMaxConcurrency: "10"

Omit the value to keep the platform default.

Analysis Service Memory Limit¶

Sets the memory ceiling for the analysis service pod. Raise it if analyses fail with out-of-memory errors — the analysis pod is OOMKilled (restarts with exit code 137) — which can happen on large repositories or under high analysis concurrency. When the pod is killed mid-run, its in-flight work surfaces as errors on the Classification and Fix stages.

The default is 8Gi. The value must be a Kubernetes resource quantity in whole GiB (e.g., 8Gi, 16Gi).

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Set Analysis service memory limit to a whole-GiB quantity (e.g., 16Gi).

Add the following to your values.yaml:

analysis:
  resources:
    limits:
      memory: 16Gi

Agentic Triage Analyzer Strategy¶

Controls which AI reasoning approach is used for triage analysis across all rules.

Available strategies:

decision-tree (default) — Autonomous agent that emulates a human-led triage process
react — Multi-step reasoning with tool use
react-holistic — Broader context analysis with tool use
claude-agent — Claude-powered autonomous agent
anthropic-agent — Anthropic SDK-based autonomous agent

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Select the desired strategy from the Agentic Triage Analyzer Strategy dropdown.

To configure the agentic triage analyzer strategy in Helm deployments, add the following to your values.yaml:

analysis:
  agenticTriageAnalyzerStrategy: decision-tree

Project Context¶

When enabled, project-level contextual analysis is used to inform triage and fix analysis results. This allows the analysis engine to consider broader project context when evaluating findings, leading to more accurate triage decisions and higher quality fixes.

This setting is enabled by default.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable Project Context checkbox.

To enable project context in Helm deployments, add the following to your values.yaml:

analysis:
  enableProjectContext: true

SCA Max Requests to Analyze¶

Controls the maximum number of requests to analyze during SCA (Software Composition Analysis). This limits the upper bound of dependency requests that SCA will process per analysis, helping to manage resource usage for repositories with large dependency trees.

The default value is 5.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the SCA Max Requests to Analyze field and enter the desired value.

To configure the SCA max requests to analyze in Helm deployments, add the following to your values.yaml:

analysis:
  scaMaxRequestsToAnalyze: 5

SCA Exploitability Fix Shortcircuit¶

When enabled, fix generation is skipped for findings that SCA (Software Composition Analysis) determines are not exploitable. This reduces unnecessary compute usage by not generating fixes for vulnerabilities that cannot be reached in practice.

This setting is disabled by default.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Skip fix for non-exploitable SCA findings checkbox.

To enable this optimization in Helm deployments, add the following to your values.yaml:

analysis:
  useScaExploitabilityToShortcircuitFix: true

Vendored File Triage¶

When enabled, a specialized triage strategy is used for vendored files. This improves the accuracy of analysis results for files that are vendored (copied from external sources) rather than authored in-house.

This setting is enabled by default.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable vendored file triage checkbox.

This is enabled by default. To disable it in Helm deployments, add the following to your values.yaml:

analysis:
  enableVendoredFileTriage: false

Analysis Input Caching¶

The analysis service supports URL-based input caching to improve performance for repeated analyses. When enabled, downloaded analysis inputs are cached locally to avoid redundant downloads.

Caching is enabled by default with a 24-hour TTL and 10GB maximum cache size.

Embedded ClusterHelm Deployment

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section.

Enable analysis input caching: Toggle to enable or disable caching (enabled by default)
Analysis cache TTL (seconds): Set the time-to-live for cached inputs (default: 86400 seconds / 24 hours)

To configure analysis input caching in Helm deployments, add the following to your values.yaml:

analysis:
  cache:
    enabled: true
    defaultTtlSeconds: 86400     # 24 hours
    maxSizeBytes: 10737418240    # 10GB
    honorCacheControl: true

Analysis Backpressure¶

The analysis backpressure feature enables the analysis service to proactively cancel analyses that cannot successfully complete within platform timeout limits. This helps prevent wasted compute resources on analyses that would eventually timeout.

This setting is enabled by default.

Embedded ClusterHelm Deployment

To configure analysis backpressure in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable analysis backpressure checkbox.

Enabled (default): The analysis service will proactively cancel analyses that cannot complete in time
Disabled: Analyses will run until they complete or timeout naturally

To configure analysis backpressure in Helm deployments, add the following to your values.yaml:

analysis:
  backpressureEnabled: true  # or false to disable

LLM Adaptive Concurrency Limiter¶

The LLM adaptive concurrency limiter uses an AIMD (Additive Increase / Multiplicative Decrease) algorithm to dynamically adjust the number of concurrent LLM requests the analysis service sends. When disabled, no concurrency gating is applied but coordinated Retry-After backoff still works.

This setting is disabled by default.

Embedded ClusterHelm Deployment

To configure the LLM adaptive concurrency limiter in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable LLM adaptive concurrency limiter checkbox.

Disabled (default): No adaptive concurrency gating; Retry-After backoff still applies
Enabled: The AIMD adaptive concurrency limiter actively gates outbound LLM requests

To configure the LLM adaptive concurrency limiter in Helm deployments, add the following to your values.yaml:

analysis:
  llmConcurrencyEnabled: true  # or false to disable

Automatic Threat Model Refresh¶

When enabled, the platform automatically refreshes a repository's threat model on SCM events — when a repository is onboarded and when commits land on its default branch. When disabled (default), threat models are only regenerated on demand.

Embedded ClusterHelm Deployment

To configure automatic threat model refresh in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable Automatic Threat Model Refresh checkbox.

Enabled: The platform refreshes threat models on repository onboarding and on pushes to the default branch
Disabled (default): Threat models are refreshed only on demand

To configure automatic threat model refresh in Helm deployments, add the following to your values.yaml:

platform:
  threatModelRefreshEnabled: true  # or false to disable (default)

Pull-Request Feedback Capture¶

When enabled, the platform captures developer reactions on Pixee-generated pull requests — comments (including @PixeeBot mentions), reviews, closes, and pushed commits — from GitHub webhooks. Each captured event is written to the analysis service's episodic-memory store so case-based reasoning agents can consult it when triaging or fixing similar findings later.

When disabled (default), no PR feedback is captured or written to memory. The database migration and admin resource are present either way, so this flag can be toggled without a data migration.

Embedded ClusterHelm Deployment

To configure pull-request feedback capture in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable Pull-Request Feedback Capture checkbox.

Enabled: The platform captures comments, reviews, closes, and pushed commits on Pixee-generated PRs and writes each event to the analysis service's episodic-memory store
Disabled (default): No PR feedback is captured or stored

To configure pull-request feedback capture in Helm deployments, add the following to your values.yaml:

platform:
  prFeedbackEnabled: true  # or false to disable (default)

SCA Chain Resolution (Experimental)¶

SCA chain resolution adds a prefilter pre-step to the SCA orchestrator for both direct and transitive dependency flows. When disabled (default), SCA behavior is unchanged.

This setting is disabled by default and is considered experimental — recommended rollout is to enable in a staging environment first and confirm the orchestrator logs show chain_resolution_prefilter step entries before promoting to higher environments.

Embedded ClusterHelm Deployment

To configure SCA chain resolution in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable SCA Chain Resolution (Experimental) checkbox.

Enabled: The SCA orchestrator runs the chain resolution prefilter as a pre-step
Disabled (default): SCA behavior is unchanged

To configure SCA chain resolution in Helm deployments, add the following to your values.yaml:

analysis:
  enableScaChainResolution: true  # or false to disable (default)

Guardrail-Rewrite Detection¶

The analysis service runs a heuristic detector on responses from OpenAI and Azure-OpenAI LLM providers that recognizes when a provider-side safety guardrail has rewritten or refused the requested fix. Two independent flags control this behavior:

Guardrail-Rewrite Detection (guardrailDetectionEnabled) is the master switch. When disabled, the scan is skipped entirely — no metrics, no breadcrumb on FindingContext.fix_caveats, no per-phase marking, and no abort in the fix retry loops. Disable this when you want the feature completely off (for example, if you observe unexpected scan overhead or do not trust the detector in a given environment).
Abort fix retries on guardrail detection (guardrailShortCircuitEnabled) controls only the abort behavior. When disabled, detection still runs (metrics and breadcrumbs continue to emit, so dashboards stay populated) but the fix retry loops in agentic_fast, impl, and fix_planner will not abort on a detection. Flip this off first if false-positive aborts appear in production while you want to preserve the observability signal. This setting has no effect when Guardrail-Rewrite Detection is disabled.

Both settings are enabled by default. The recommended starting configuration is to leave them on and only disable guardrailShortCircuitEnabled if false-positive aborts emerge.

Embedded ClusterHelm Deployment

To configure guardrail-rewrite detection in Embedded Cluster deployments:

Navigate to the admin console, select the Config tab, then go to the Advanced Settings section. Locate the Enable Guardrail-Rewrite Detection and Abort fix retries on guardrail detection checkboxes.

To configure guardrail-rewrite detection in Helm deployments, add the following to your values.yaml:

analysis:
  guardrailDetectionEnabled: true     # or false to disable detection entirely (default true)
  guardrailShortCircuitEnabled: true  # or false to keep detection but skip retry aborts (default true)