Helm Install

Errand can be deployed to any Kubernetes cluster using its official Helm chart. This is the recommended approach for production environments, teams, and anywhere you need high availability or autoscaling.

Prerequisites

• A running Kubernetes cluster (any provider — cloud or local)
• Helm 3 installed on your machine
• kubectl configured to access your cluster
• An API key from at least one LLM provider (e.g. Anthropic, OpenAI)

Step 1: Create Kubernetes secrets

Before installing the chart, create the secrets that Errand needs. Run these commands, replacing the placeholder values with your own:

1. Database credentials — connection string for PostgreSQL:

   kubectl create secret generic errand-database \
     --from-literal=DATABASE_URL="postgresql://user:password@hostname:5432/errand"

2. LLM provider credentials — your API key:

   kubectl create secret generic errand-openai \
     --from-literal=OPENAI_API_KEY="your-api-key-here"

3. Credential encryption key — used to encrypt stored integration credentials:

   kubectl create secret generic errand-encryption \
     --from-literal=CREDENTIAL_ENCRYPTION_KEY="$(python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"

Step 2: Install the Helm chart

Install the chart directly from the OCI registry:

helm install errand oci://ghcr.io/errand-ai/charts/errand \
  --set database.existingSecret=errand-database \
  --set openai.existingSecret=errand-openai \
  --set credentialEncryption.existingSecret=errand-encryption

Tip

For your first install, set worker.replicaCount=0 so you can verify the server is running before tasks start executing. Once you are satisfied, upgrade the release with workers enabled.

Step 3: Configure values

The Helm chart is configured through a values.yaml file. Here are the key settings:

Replicas and scaling

Value	Description	Default
server.replicaCount	Number of API server replicas	1
worker.replicaCount	Number of worker replicas	1
worker.maxTurns	Maximum LLM reasoning turns per task	200
keda.enabled	Enable KEDA-based autoscaling for workers	false

Secrets

Value	Description
database.existingSecret	Kubernetes secret containing DATABASE_URL
openai.existingSecret	Kubernetes secret containing OPENAI_API_KEY
credentialEncryption.existingSecret	Kubernetes secret containing CREDENTIAL_ENCRYPTION_KEY

Networking

Value	Description	Default
ingress.host	Domain name for the Errand UI	—
ingress.tls.enabled	Enable HTTPS using cert-manager	false

Built-in services

Value	Description	Default
valkey.enabled	Deploy a built-in Valkey cache	true
gdrive.enabled	Enable Google Drive integration	false
onedrive.enabled	Enable OneDrive integration	false

To use a custom values file:

helm install errand oci://ghcr.io/errand-ai/charts/errand \
  -f values.yaml

Step 4: Verify the installation

1. Check that the pods are running:

   kubectl get pods -l app.kubernetes.io/name=errand

2. If you configured an ingress, open https://your-domain in your browser. Otherwise, use port forwarding:

   kubectl port-forward svc/errand-server 8000:8000

3. Navigate to http://localhost:8000 and log in

How task execution works

The worker uses Kubernetes Jobs to execute each task in an isolated pod. This means:

• Each task runs in its own container with its own resources
• A failed task does not affect other running tasks
• The worker’s ServiceAccount needs RBAC permissions to create and manage Jobs, ConfigMaps, and Pods

The Helm chart automatically creates the required ServiceAccount and RBAC roles. If you are using a custom ServiceAccount, make sure it has permissions for jobs, configmaps, and pods in the Errand namespace.

Database options

The chart does not include a built-in PostgreSQL instance. You need to provide your own database. Two common options:

• Managed database — use a cloud-hosted PostgreSQL service (e.g. AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL) and pass the connection string via the database.existingSecret
• CloudNativePG — deploy PostgreSQL on Kubernetes using the CloudNativePG operator, which handles backups, failover, and high availability

Troubleshooting

Issue	Solution
Pods stuck in Pending state	Check for resource constraints with kubectl describe pod <pod-name>. The cluster may not have enough CPU or memory available
Server pod crashes on startup	Check logs with kubectl logs <pod-name>. The most common cause is a missing or incorrect DATABASE_URL in the database secret
Worker cannot create task Jobs	Verify the worker’s ServiceAccount has the required RBAC permissions for Jobs, ConfigMaps, and Pods
Cannot reach the UI through ingress	Confirm that ingress.host is set correctly, DNS points to your cluster, and (if using TLS) cert-manager has issued a certificate
LLM errors during task execution	Verify the OPENAI_API_KEY secret is correct and your account has available credits with your LLM provider
KEDA autoscaling not working	Ensure KEDA is installed in your cluster and keda.enabled is set to true in your values