Configuration reference

Every setting you can change on a Marshal install, with its default and when you would change it. Marshal installs as one Helm chart. You set it up in one of two ways:

• Terraform installer (EKS, GKE, single-node k3s). You write terraform.tfvars. The Terraform variables below are the settings each install target declares.
• ArgoCD (GitOps path). You write chart values in the Application’s valuesObject. Use the Chart values section and the chart value named next to each Terraform variable.

Any chart value also works on the Terraform path: put it in values_overrides. This page covers the Marshal settings. Cluster, node pool, network and database settings that belong to one cloud are on that cloud’s install page.

What you must set

Five settings have no default, on every target:

The first three come with your onboarding. See Onboarding credentials. Each cloud adds its own: cluster_name and region on EKS, project_id and location on GKE.

Terraform variables

The Targets column shows which install targets declare the variable: EKS (aws-eks), GKE (gcp-gke) and k3s (single-node-k3s). A variable a target does not declare is not a tfvar there. Terraform warns about it and ignores the value. Set the chart value through values_overrides instead.

Release and chart

Credentials

Images and registry

All images resolve under one registry prefix. Point it at your image cache for production. See Registry options.

Each cloud target can also build the cache for you. On GKE, create_registry_cache (default true) creates an Artifact Registry mirror and sets registry and registry_auth_mode for you. On EKS, create_harbor_cache (default false) runs Harbor in the cluster as the cache. See GKE and EKS.

Datastores

Postgres holds everything durable: spaces, organizations, credentials, manifests and the audit log. Redis holds only short-lived state that Marshal can rebuild. So the recommended setup is your own managed Postgres and the in-cluster Redis. See Datastore options.

On k3s, provision_datastores (default true) runs Postgres and Redis on the same VM.

Ingress & TLS

Integrations

An organization’s admin turns these features on or off in Settings > Platform at any time, with no restart, and a value saved there always wins over these variables. Both need outbound HTTPS to the host they point at. See Networking.

Object storage

See Object storage for the second step.

values_overrides

values_overrides = [
  yamlencode({
    api = {
      extraEnv = [{ name = "MARSHAL_REGISTRATION_INVITE_ONLY", value = "true" }]
    }
    license = { enforce = true }
  })
]

Chart values

These are chart values with no Terraform variable on any target. Set them in values_overrides (Terraform) or valuesObject (ArgoCD).

Sign-in and license

Marketplace and toolchains

Price list

The Compute tab of the Costs page estimates your monthly cost from public list prices for Google Cloud and AWS. Your install downloads the latest price list once a day and keeps a copy built into every release. It needs no cloud credentials.

Admins see the date of the price list in use on the Compute tab. See Costs.

Secrets management

Two app secrets live in one Kubernetes Secret: JWT_SECRET signs sign-in and API tokens, and KMS_LOCAL_KEY encrypts every stored credential. You choose how the chart gets them.

Namespaces, registry details and capacity

The MCP settings mcp.extraHosts, mcp.cimdEnabled and tailscaleIngress.* are explained on Connect an AI agent (MCP).

API database pool and readiness

The API keeps serving under heavy load. Its readiness probe checks the database on a connection of its own, outside the pool, so a busy pool that keeps completing queries stays in rotation. A pod leaves rotation only when its pool is fully in use and has completed nothing for staleAfter. At startup the API waits up to 60 seconds for Postgres and Redis to answer, so a fresh install comes up without a restart.

Two request limits are set through api.extraEnv. Each takes a duration such as 45s, and 0 turns the limit off. Streaming routes, such as a run’s live events, and a few long-running actions, such as purging a deputy, are exempt. The configuration routes are limited like any other.

A request that reaches its limit answers 503 with {"error":"service unavailable"} and Retry-After: 2. Routes behind a per-organization switch (runs and deputies, the Webhook Relay, the Auth Broker, Slack) answer with the same 503, error and header when the API cannot read the organization’s settings within 5 seconds, and add a message that says to try again. A slow database never shows a feature as switched off. A switch that is off still answers 503 with feature_disabled. API clients should treat service unavailable as retryable: earlier releases answered an unreadable switch with feature_disabled and reason unavailable.

Upgrades without failed requests

When an API or web console pod stops, during an upgrade, a rollout or a node drain, it keeps serving for a short drain window first. The API also reports itself not ready in that window, so Kubernetes, your ingress controller and any load balancer that checks pods directly move traffic to the other pods before this one closes. In-flight requests then finish and the pod exits on its own. With api.readiness.path set to /healthz, the API still drains but does not report itself not ready.

A longer drain makes each upgrade a little slower: every stopping pod waits its drain window once.

Node tuning

Spaces watch many files, and the kernel’s inotify limits are shared by every container on a node. The kernel default of 128 instances runs out after a handful of spaces, and the next space fails to start with failed to create fsnotify watcher: too many open files.

These limits are node settings, so no pod can raise them for itself. The chart runs a small DaemonSet that raises them on every node, including nodes an autoscaler adds later. It only ever raises a value, so a node you tuned higher yourself keeps its value.

The write happens in a short-lived privileged init container. The container that stays running has no privileges, runs as uid 65534 with a read-only root filesystem, and requests 10m CPU.

Optional features

Some features are off until you turn them on. This table lists each one, where it is switched on, and the default.

The first three are switches each organization’s owners and admins control themselves, under Settings > Platform. A change applies right away, with no restart. Webhooks and the Slack connection need the installation JWT, because they connect to Marshal’s hosted services.

Example of api.extraEnv in chart values:

api:
  extraEnv:
    - name: MARSHAL_REGISTRATION_INVITE_ONLY
      value: "true"

Notes:

• Runs and deputies. One switch controls both, for one organization. With it off, the Deputies and Runs entries in the web app show as not enabled, the run and deputy API answers 503 with feature_disabled, and marshal run fails. Other organizations on the same install keep their own setting. An install that set MARSHAL_DEPUTIES_ENABLED on the API keeps that value as the starting point for every organization that has not set the switch.
• First-run setup token. The chart stores it in the app secret under the key SETUP_TOKEN. Read it with kubectl get secret <release>-app-secrets -n <namespace> -o jsonpath='{.data.SETUP_TOKEN}' | base64 -d. With secrets.provider: existing, use your own Secret’s name, and add a SETUP_TOKEN key to it, or first-run setup stays off.