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 clientsync_address. - If health succeeds while sync fails, inspect database connectivity and run a
real login or sync canary;
/healthzonly proves HTTP process availability. - If metrics have no targets, confirm both
metrics.enabledandmetrics.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 SyncedVerified 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)]Atuin Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Global values consumed by dependencies. |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | - | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | - | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Image(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.digest | string | - | Chart configuration parameter |
| image.pullPolicy | select | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Replica Count(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| replicaCount | integer | - | Chart configuration parameter |
Atuin(10)
| Parameter | Type | Default | Description |
|---|---|---|---|
| atuin.openRegistration | boolean | - | Chart configuration parameter |
| atuin.path | string | - | Chart configuration parameter |
| atuin.maxRecordSize | string | - | Chart configuration parameter |
| atuin.logLevel | string | - | Chart configuration parameter |
| atuin.fakeVersion | string | - | Chart configuration parameter |
| atuin.registerWebhook.existingSecret | string | - | Chart configuration parameter |
| atuin.registerWebhook.key | string | - | Chart configuration parameter |
| atuin.registerWebhook.username | string | - | Chart configuration parameter |
| atuin.extraEnv | array | - | Chart configuration parameter |
| atuin.envFrom | array | - | Chart configuration parameter |
Database(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.type | select | - | Chart configuration parameter Allowed: sqlitepostgresql |
| database.sqlite.path | string | - | Chart configuration parameter |
| database.existingSecret | string | - | Chart configuration parameter |
| database.existingSecretKey | string | - | Chart configuration parameter |
Postgresql(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| postgresql.enabled | boolean | - | Chart configuration parameter |
| postgresql.architecture | select | - | Chart configuration parameter Allowed: standalonereplication |
| postgresql.auth.database | string | - | Chart configuration parameter |
| postgresql.auth.username | string | - | Chart configuration parameter |
| postgresql.auth.existingSecret | string | - | Chart configuration parameter |
| postgresql.auth.existingSecretUserPasswordKey | string | - | Chart configuration parameter |
Database Uri Helper(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| databaseUriHelper.image.repository | string | - | Chart configuration parameter |
| databaseUriHelper.image.tag | string | - | Chart configuration parameter |
| databaseUriHelper.image.pullPolicy | select | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
| databaseUriHelper.resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| databaseUriHelper.resources.requests.memory | stringnumber | - | Chart configuration parameter |
| databaseUriHelper.resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| databaseUriHelper.resources.limits.memory | stringnumber | - | Chart configuration parameter |
Container Ports(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| containerPorts.http | integer | - | Real Atuin HTTP process listener configured through ATUIN_PORT. |
Persistence(6)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | - | Chart configuration parameter |
| persistence.existingClaim | string | - | Chart configuration parameter |
| persistence.storageClass | string | - | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.size | string | - | Chart configuration parameter |
| persistence.annotations | object | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Service & Networking(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | select | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
| service.ipFamilyPolicy | select | - | Chart configuration parameter Allowed: SingleStackPreferDualStackRequireDualStack |
| service.ipFamilies | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Gateway API(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| gatewayAPI.enabled | boolean | - | Chart configuration parameter |
| gatewayAPI.httpRoutes | array | - | Chart configuration parameter |
Metrics & Observability(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| metrics.enabled | boolean | - | Chart configuration parameter |
| metrics.port | integer | - | Chart configuration parameter |
| metrics.service.annotations | object | - | Chart configuration parameter |
| metrics.serviceMonitor.enabled | boolean | - | Chart configuration parameter |
| metrics.serviceMonitor.interval | string | - | Chart configuration parameter |
| metrics.serviceMonitor.scrapeTimeout | string | - | Chart configuration parameter |
| metrics.serviceMonitor.labels | object | - | Chart configuration parameter |
External Secrets(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalSecrets.enabled | boolean | - | Chart configuration parameter |
| externalSecrets.refreshInterval | string | - | Chart configuration parameter |
| externalSecrets.items | array | - | Chart configuration parameter |
Health Probes(15)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources.requests.cpu | stringnumber | - | Chart configuration parameter |
| resources.requests.memory | stringnumber | - | Chart configuration parameter |
| resources.limits.cpu | stringnumber | - | Chart configuration parameter |
| resources.limits.memory | stringnumber | - | Chart configuration parameter |
Pod Security(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.runAsNonRoot | boolean | - | Chart configuration parameter |
| podSecurityContext.runAsUser | integer | - | Chart configuration parameter |
| podSecurityContext.runAsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroup | integer | - | Chart configuration parameter |
| podSecurityContext.fsGroupChangePolicy | select | - | Chart configuration parameter Allowed: AlwaysOnRootMismatch |
| podSecurityContext.seccompProfile.type | select | - | Chart configuration parameter Allowed: RuntimeDefaultLocalhostUnconfined |
| podSecurityContext.seccompProfile.localhostProfile | string | - | Chart configuration parameter |
Container Security(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.readOnlyRootFilesystem | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
| securityContext.capabilities.add | array | - | Chart configuration parameter |
Strategy(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| strategy | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Pod Disruption Budget(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podDisruptionBudget.enabled | boolean | - | Chart configuration parameter |
| podDisruptionBudget.minAvailable | any | - | Chart configuration parameter |
Autoscaling(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| autoscaling.enabled | boolean | - | Chart configuration parameter |
| autoscaling.minReplicas | integer | - | Chart configuration parameter |
| autoscaling.maxReplicas | integer | - | Chart configuration parameter |
| autoscaling.targetCPUUtilizationPercentage | integer | - | Chart configuration parameter |
Network Policy(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.extraIngress | array | - | Chart configuration parameter |
| networkPolicy.extraEgress | array | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Containers(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraContainers | array | - | Chart configuration parameter |
Extra Init Containers(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraInitContainers | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.