Skip to content
Atuin icon
v1.1.4App: v18.23.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

Atuin Helm chart

Deploy the official Atuin shell history sync server with safe SQLite defaults or PostgreSQL for production scaling.

Features

  • Official, pinned Atuin image with no floating tags.
  • Safe single-replica SQLite default and shared-state PostgreSQL topology.
  • Independently configurable application listener and Kubernetes Service port.
  • Ingress and Gateway API exposure with TLS-first operational guidance.
  • Hardened non-root runtime, optional NetworkPolicy, HPA and disruption budget.
  • Native External Secrets resources and a separate private metrics listener.
  • Startup, readiness and liveness probes that follow the configured route prefix.

Architecture

The default topology runs one Atuin server with its SQLite database on a ReadWriteOnce PVC. PostgreSQL mode uses either the HelmForge PostgreSQL dependency or a complete connection URI read from an existing Secret. Atuin is stateless once PostgreSQL owns the shared state, so replicas and autoscaling can then be enabled. See DESIGN.md for topology diagrams, boundaries and intentional non-goals.

Install

helm upgrade --install atuin oci://ghcr.io/helmforgedev/helm/atuin \
  --namespace atuin --create-namespace

The default creates one hardened pod, a 5 GiB PVC and a ClusterIP Service. Registration is closed. Temporarily set atuin.openRegistration=true to create the first account, then close it again.

Configuration

containerPorts.http configures the real Atuin HTTP listener through ATUIN_PORT. service.port is the independent client-facing Kubernetes Service port and targets the named http container port. Both default to 8888, but changing only service.port does not move the process listener. Because Atuin runs as UID 1000 with all capabilities dropped, application and metrics listener ports must be 1024 or higher.

Value Default Purpose
containerPorts.http 8888 Atuin HTTP process listener
service.port 8888 Kubernetes Service-facing port
atuin.openRegistration false Allow controlled account registration
atuin.path "" Optional prefix for API and health routes
atuin.maxRecordSize 1GiB Maximum encrypted sync record size
database.type sqlite Select SQLite or PostgreSQL
database.existingSecret "" Secret containing an external PostgreSQL URI
postgresql.enabled false Deploy the HelmForge PostgreSQL dependency
persistence.size 5Gi SQLite PVC capacity
metrics.enabled false Enable the private Prometheus listener
metrics.port 9001 Prometheus process and Service port
serviceAccount.automountServiceAccountToken false Keep the Kubernetes API token unmounted
securityContext.readOnlyRootFilesystem true Prevent writes outside declared volumes
networkPolicy.enabled false Enable baseline ingress and egress isolation

The complete contract is in values.yaml and values.schema.json. Detailed database, exposure, operations and security guidance is linked below.

Examples

The examples/ directory includes simple SQLite, production PostgreSQL, Gateway API and External Secrets configurations. Start from the smallest applicable example and keep credentials in Secrets rather than plain values.

Production PostgreSQL

database:
  type: postgresql
postgresql:
  enabled: true
  auth:
    database: atuin
    username: atuin

The HelmForge PostgreSQL dependency generates and retains credentials. With an external database, create a Secret whose db-uri value is a complete postgres:// URI, set database.type=postgresql, database.existingSecret, and leave postgresql.enabled=false.

Every Atuin replica may open 100 PostgreSQL connections. Size the database or pooler before increasing replicas. Upstream migrations run automatically on startup; back up before upgrades.

HTTPS

Public installations must terminate TLS at Ingress or Gateway API. Atuin warns that passwords are exposed over plain HTTP. See exposure.

Monitoring

Set metrics.enabled=true to expose the private metrics Service. Set metrics.serviceMonitor.enabled=true when Prometheus Operator CRDs are installed.

Security

The pod runs as UID/GID 1000 with RuntimeDefault seccomp, a read-only root filesystem, no privilege escalation, every Linux capability dropped and no automatically mounted service account token. Public endpoints must terminate TLS because login credentials are not protected by Atuin's history encryption. See security before enabling public exposure or external database and webhook egress.

Backup

For SQLite, stop or quiesce Atuin before copying the database and its WAL files, or use a CSI volume snapshot with application coordination. For PostgreSQL, use pg_dump --format=custom --no-owner --no-acl or your managed database backup facility. See operations.

S3 clarification

Atuin Server 18.23.0 stores synchronized records in SQL and has no native S3 backend. This chart does not expose misleading S3 application settings. An independent backup system may still store database backups in object storage.

Documentation

Uninstall

helm uninstall atuin --namespace atuin

Helm deletes the default PVC during uninstall unless persistence.annotations includes helm.sh/resource-policy: keep. Confirm backups before uninstalling or removing storage.

Troubleshooting

  • If a SQLite release rejects multiple replicas, switch to PostgreSQL before scaling; this is an intentional data-safety check.
  • If the pod never becomes ready, inspect the init container, database Secret keys and PostgreSQL Service endpoints.
  • If clients receive 404 responses, align atuin.path, proxy rewriting and the client sync_address.
  • If health succeeds while sync fails, inspect database connectivity and run a real login or sync canary; /healthz only proves HTTP process availability.
  • If metrics have no targets, confirm both metrics.enabled and metrics.serviceMonitor.enabled, then inspect ServiceMonitor selectors.

Security Scan: atuin

Security scan results use the same Kubescape policy set as HelmForge CI.

Framework Score
MITRE 100.00%
NSA 92.50%
SOC 2 90.00%
Aggregate resource score 93.94%

Kubescape reported no critical or high-severity control failures. The medium findings concern unrestricted ingress and egress when the optional NetworkPolicy is disabled by default; the low finding belongs to a generated dependency resource rather than the hardened Atuin container.

System Architecture

DESIGN.md Synced

Verified architecture contract rendered dynamically from GitHub DESIGN.md

flowchart LR
    Client[Atuin client] --> Service[ClusterIP Service]
    Service --> Server[Atuin server pod]
    Server --> Config[/config PVC]
    Config --> SQLite[(SQLite database and WAL)]
Official Contractvalues.schema.json

Atuin Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

123 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Global values consumed by dependencies.

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring-Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring-Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Image(4)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.digeststring-Chart configuration parameter
image.pullPolicyselect-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Replica Count(1)

ParameterTypeDefaultDescription
replicaCountinteger-Chart configuration parameter

Atuin(10)

ParameterTypeDefaultDescription
atuin.openRegistrationboolean-Chart configuration parameter
atuin.pathstring-Chart configuration parameter
atuin.maxRecordSizestring-Chart configuration parameter
atuin.logLevelstring-Chart configuration parameter
atuin.fakeVersionstring-Chart configuration parameter
atuin.registerWebhook.existingSecretstring-Chart configuration parameter
atuin.registerWebhook.keystring-Chart configuration parameter
atuin.registerWebhook.usernamestring-Chart configuration parameter
atuin.extraEnvarray-Chart configuration parameter
atuin.envFromarray-Chart configuration parameter

Database(4)

ParameterTypeDefaultDescription
database.typeselect-Chart configuration parameter
Allowed:sqlitepostgresql
database.sqlite.pathstring-Chart configuration parameter
database.existingSecretstring-Chart configuration parameter
database.existingSecretKeystring-Chart configuration parameter

Postgresql(6)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Chart configuration parameter
postgresql.architectureselect-Chart configuration parameter
Allowed:standalonereplication
postgresql.auth.databasestring-Chart configuration parameter
postgresql.auth.usernamestring-Chart configuration parameter
postgresql.auth.existingSecretstring-Chart configuration parameter
postgresql.auth.existingSecretUserPasswordKeystring-Chart configuration parameter

Database Uri Helper(7)

ParameterTypeDefaultDescription
databaseUriHelper.image.repositorystring-Chart configuration parameter
databaseUriHelper.image.tagstring-Chart configuration parameter
databaseUriHelper.image.pullPolicyselect-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever
databaseUriHelper.resources.requests.cpustringnumber-Chart configuration parameter
databaseUriHelper.resources.requests.memorystringnumber-Chart configuration parameter
databaseUriHelper.resources.limits.cpustringnumber-Chart configuration parameter
databaseUriHelper.resources.limits.memorystringnumber-Chart configuration parameter

Container Ports(1)

ParameterTypeDefaultDescription
containerPorts.httpinteger-Real Atuin HTTP process listener configured through ATUIN_PORT.

Persistence(6)

ParameterTypeDefaultDescription
persistence.enabledboolean-Chart configuration parameter
persistence.existingClaimstring-Chart configuration parameter
persistence.storageClassstring-Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.sizestring-Chart configuration parameter
persistence.annotationsobject-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(5)

ParameterTypeDefaultDescription
service.typeselect-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter
service.ipFamilyPolicyselect-Chart configuration parameter
Allowed:SingleStackPreferDualStackRequireDualStack
service.ipFamiliesarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Gateway API(2)

ParameterTypeDefaultDescription
gatewayAPI.enabledboolean-Chart configuration parameter
gatewayAPI.httpRoutesarray-Chart configuration parameter

Metrics & Observability(7)

ParameterTypeDefaultDescription
metrics.enabledboolean-Chart configuration parameter
metrics.portinteger-Chart configuration parameter
metrics.service.annotationsobject-Chart configuration parameter
metrics.serviceMonitor.enabledboolean-Chart configuration parameter
metrics.serviceMonitor.intervalstring-Chart configuration parameter
metrics.serviceMonitor.scrapeTimeoutstring-Chart configuration parameter
metrics.serviceMonitor.labelsobject-Chart configuration parameter

External Secrets(3)

ParameterTypeDefaultDescription
externalSecrets.enabledboolean-Chart configuration parameter
externalSecrets.refreshIntervalstring-Chart configuration parameter
externalSecrets.itemsarray-Chart configuration parameter

Health Probes(15)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(4)

ParameterTypeDefaultDescription
resources.requests.cpustringnumber-Chart configuration parameter
resources.requests.memorystringnumber-Chart configuration parameter
resources.limits.cpustringnumber-Chart configuration parameter
resources.limits.memorystringnumber-Chart configuration parameter

Pod Security(7)

ParameterTypeDefaultDescription
podSecurityContext.runAsNonRootboolean-Chart configuration parameter
podSecurityContext.runAsUserinteger-Chart configuration parameter
podSecurityContext.runAsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupinteger-Chart configuration parameter
podSecurityContext.fsGroupChangePolicyselect-Chart configuration parameter
Allowed:AlwaysOnRootMismatch
podSecurityContext.seccompProfile.typeselect-Chart configuration parameter
Allowed:RuntimeDefaultLocalhostUnconfined
podSecurityContext.seccompProfile.localhostProfilestring-Chart configuration parameter

Container Security(4)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.readOnlyRootFilesystemboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter
securityContext.capabilities.addarray-Chart configuration parameter

Strategy(1)

ParameterTypeDefaultDescription
strategyobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Pod Disruption Budget(2)

ParameterTypeDefaultDescription
podDisruptionBudget.enabledboolean-Chart configuration parameter
podDisruptionBudget.minAvailableany-Chart configuration parameter

Autoscaling(4)

ParameterTypeDefaultDescription
autoscaling.enabledboolean-Chart configuration parameter
autoscaling.minReplicasinteger-Chart configuration parameter
autoscaling.maxReplicasinteger-Chart configuration parameter
autoscaling.targetCPUUtilizationPercentageinteger-Chart configuration parameter

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.extraIngressarray-Chart configuration parameter
networkPolicy.extraEgressarray-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Containers(1)

ParameterTypeDefaultDescription
extraContainersarray-Chart configuration parameter

Extra Init Containers(1)

ParameterTypeDefaultDescription
extraInitContainersarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter