Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.idun-group.com/llms.txt

Use this file to discover all available pages before exploring further.

Cloud Run runs a single container per request, scales to zero by default, and forwards HTTPS. The standalone is designed to fit.

​
1. Set up Cloud SQL (Postgres)

The standalone uses SQLite by default; on Cloud Run that disappears between revisions. Use Cloud SQL Postgres: 
gcloud sql instances create idun-postgres \
    --database-version=POSTGRES_16 --region=europe-west1 --tier=db-f1-micro
gcloud sql databases create idun --instance=idun-postgres
gcloud sql users create idun --instance=idun-postgres --password='changeme'
URL form (Cloud SQL Auth Proxy / unix socket): 
postgresql+asyncpg://idun:changeme@/idun?host=/cloudsql/PROJECT:REGION:idun-postgres

​
2. Store secrets in Secret Manager

echo -n "$(idun hash-password)" | gcloud secrets create idun-admin-hash --data-file=-
openssl rand -hex 32 | gcloud secrets create idun-session-secret --data-file=-
echo -n "postgresql+asyncpg://..." | gcloud secrets create idun-db-url --data-file=-

​
3. Build & push

Use Dockerfile.example as a starting point: 
docker build -f Dockerfile.example -t gcr.io/PROJECT/my-agent:0.1.0 .
docker push gcr.io/PROJECT/my-agent:0.1.0

​
4. Deploy

Copy the template into your deploy directory, then edit it: 
cp /path/to/idun-agent-platform/libs/idun_agent_standalone/docker/cloud-run.example.yaml cloud-run.yaml
# Replace PROJECT, REGION, and the image tag in cloud-run.yaml.
gcloud run services replace cloud-run.yaml --region=europe-west1
The template ships two annotations you must keep:
  • metadata.annotations."run.googleapis.com/cloudsql-instances" — attaches the Cloud SQL instance to the service. Required for the unix-socket form host=/cloudsql/PROJECT:REGION:idun-postgres in DATABASE_URL.
  • spec.template.metadata.annotations."run.googleapis.com/cloudsql-instances" — same value at the revision level. Cloud Run requires both for new revisions to inherit the connection.
Recommended runtime settings (already set in the template):
  • minScale: "1" — eliminates cold starts and keeps the trace retention scheduler running.
  • cpu-throttling: "false" — keeps the trace writer flushing between requests.
  • 1 GiB memory, 1 vCPU is plenty for a small agent.

​
Caveats

  • MCP servers using command: docker run … won’t work on Cloud Run. Switch to transport: stdio with a binary command (e.g. npx, uvx, a precompiled binary) or use HTTP transport pointing at another Cloud Run service.
  • Trace retention purge runs hourly via APScheduler — when Cloud Run scales to zero the scheduler stops too. With minScale: "1" it runs continuously.
  • Cookies need Secure — Cloud Run’s load balancer sets X-Forwarded-Proto: https. The standalone honors that automatically.

​
Next steps

Production hardening

Lock down admin auth, TLS, secrets, and trace retention before exposing the service.

GCP Trace

Send distributed traces to the same Google Cloud project.

GCP Logging

Stream structured logs to Cloud Logging from the running service.
Last modified on May 20, 2026