{
  "schema_version": 1,
  "kind": "article",
  "title": "Hosting OpenClaw agents on Google Cloud Run",
  "description": "A deployment walkthrough covering tenant-specific services, persistent workspaces, webhook routing, and scaling on Cloud Run.",
  "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run",
  "markdown_url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run.md",
  "json_url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run.json",
  "language": "en",
  "author": {
    "type": "Organization",
    "name": "CloudOn",
    "url": "https://cloudon-one.com/"
  },
  "rights_url": "https://cloudon-one.com/terms",
  "indexable": true,
  "headings": [
    {
      "level": 2,
      "text": "Architecture",
      "id": "architecture",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#architecture"
    },
    {
      "level": 3,
      "text": "GCSFuse Workspace Persistence",
      "id": "gcsfuse-workspace-persistence",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#gcsfuse-workspace-persistence"
    },
    {
      "level": 3,
      "text": "Multi-Tenant Router",
      "id": "multi-tenant-router",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#multi-tenant-router"
    },
    {
      "level": 3,
      "text": "Security",
      "id": "security",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#security"
    },
    {
      "level": 2,
      "text": "Instructions",
      "id": "instructions",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#instructions"
    },
    {
      "level": 3,
      "text": "Prerequisites",
      "id": "prerequisites",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#prerequisites"
    },
    {
      "level": 3,
      "text": "1. Clone the repo",
      "id": "1-clone-the-repo",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#1-clone-the-repo"
    },
    {
      "level": 3,
      "text": "2. Configure your project",
      "id": "2-configure-your-project",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#2-configure-your-project"
    },
    {
      "level": 3,
      "text": "3. Create the Artifact Registry repository and enable APIs",
      "id": "3-create-the-artifact-registry-repository-and-enable-apis",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#3-create-the-artifact-registry-repository-and-enable-apis"
    },
    {
      "level": 3,
      "text": "4. Build and push both container images",
      "id": "4-build-and-push-both-container-images",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#4-build-and-push-both-container-images"
    },
    {
      "level": 3,
      "text": "5. Store your Anthropic API key",
      "id": "5-store-your-anthropic-api-key",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#5-store-your-anthropic-api-key"
    },
    {
      "level": 3,
      "text": "6. Define your first tenant in tenants.yaml",
      "id": "6-define-your-first-tenant-in-tenantsyaml",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#6-define-your-first-tenant-in-tenantsyaml"
    },
    {
      "level": 3,
      "text": "7. Deploy infrastructure",
      "id": "7-deploy-infrastructure",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#7-deploy-infrastructure"
    },
    {
      "level": 3,
      "text": "8. Create a Telegram bot",
      "id": "8-create-a-telegram-bot",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#8-create-a-telegram-bot"
    },
    {
      "level": 3,
      "text": "9. Store tenant secrets",
      "id": "9-store-tenant-secrets",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#9-store-tenant-secrets"
    },
    {
      "level": 3,
      "text": "10. Register the Telegram webhook",
      "id": "10-register-the-telegram-webhook",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#10-register-the-telegram-webhook"
    },
    {
      "level": 2,
      "text": "Conclusion",
      "id": "conclusion",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#conclusion"
    },
    {
      "level": 2,
      "text": "Want to try it?",
      "id": "want-to-try-it",
      "url": "https://cloudon-one.com/blog/openclaw-gcp-cloud-run#want-to-try-it"
    }
  ],
  "date_published": "2026-03-01T00:00:00.000Z",
  "tags": [
    "GCP",
    "Cloud Run",
    "OpenClaw",
    "AI Agents",
    "Serverless"
  ],
  "content_markdown": "---\ntitle: Hosting OpenClaw agents on Google Cloud Run\ndescription: A deployment walkthrough covering tenant-specific services, persistent workspaces, webhook routing, and scaling on Cloud Run.\nurl: https://cloudon-one.com/blog/openclaw-gcp-cloud-run\nauthor: CloudOn\nlanguage: en\ndate_published: '2026-03-01T00:00:00.000Z'\ntags:\n  - GCP\n  - Cloud Run\n  - OpenClaw\n  - AI Agents\n  - Serverless\nrights_url: https://cloudon-one.com/terms\n---\n\n# Hosting OpenClaw agents on Google Cloud Run\n\nA few days ago, Matias Kreder published a great article on running OpenClaw on AWS Bedrock AgentCore.\n\nThe architecture was elegant: ephemeral containers, S3-backed workspace sync, per-user isolation, no always-on VMs.\n\nI was already running OpenClaw on a GKE node, and the bill was… fine, but the node was sitting there 24/7 whether anyone was chatting with the agent or not.\n\nAfter reading Matias's post, I thought: GCP has all the same primitives. Can I replicate this pattern natively on GCP?\n\nTurns out yes — and in some ways the GCP path is even cleaner. Cloud Run v2 supports native GCSFuse volume mounts, which means you get a persistent workspace without a sync daemon, a sidecar, or a background timer. The filesystem just works across container restarts.\n\nThis post walks through how I built a multi-tenant OpenClaw deployment on Cloud Run, with full per-tenant isolation, Telegram/Slack support, and a shared router service as the only public endpoint.\n\nThe full repo is on GitHub: [openclaw-serverless](https://github.com/cloudon-one/openclaw-serverless).\n\n## Architecture\n\n### GCSFuse Workspace Persistence\n\nCloud Run containers are ephemeral — they spin up on demand and disappear when idle. OpenClaw stores everything it knows about a user under *.openclaw/* (conversation memory, user profiles, tool outputs). Without a persistence strategy, that all disappears the moment a session ends.\n\nThe solution here is simpler than the AWS approach: Cloud Run v2 has built-in GCSFuse support. The agent container gets a */data* volume mount backed by a per-tenant GCS bucket. The entrypoint writes *openclaw.json* to that path on startup, and every file write the agent makes is transparently persisted to GCS. No sync loop, no *SIGTERM* handler — it just works. Container restarts pick up exactly where the previous session left off.\n\nOne intentional detail: config is always overwritten on startup from environment variables. GCSFuse persists agent state; environment variables drive configuration. A new deploy always wins over stale config on disk.\n\n### Multi-Tenant Router\n\nRather than exposing each tenant's Cloud Run service to the internet, a single lightweight Node.js router sits at the public endpoint. It validates webhook signatures (Telegram secret token, Slack HMAC-SHA256), looks up the tenant by user/channel ID, then forwards the request to the right tenant service using a GCP-issued ID token. Tenant services are deployed with *INGRESS_TRAFFIC_INTERNAL_ONLY* — they are completely unreachable except through the router.\n\nWebhook secrets are fetched from Secret Manager and cached for 5 minutes. Both channels are fail-closed: requests without valid signatures are rejected before any tenant code runs.\n\n### Security\n\n**Network:** Tenant Cloud Run services have internal-only ingress. The only public endpoint is the router service. Even within GCP, a caller needs a valid ID token to invoke a tenant service — ambient network access is not enough.\n\n**Per-tenant isolation:** Each tenant gets its own Cloud Run service, GCS bucket, and service account. The tenant SA has *objectAdmin* on its own bucket only — no IAM binding to any other tenant's resources. Secrets are scoped per-tenant; the SA can access its own secrets plus the shared Anthropic API key, nothing else.\n\n**Least-privilege IAM:** The router SA has secretAccessor on webhook secrets and run.invoker on each tenant service. Tenant SAs have secretAccessor on their own secrets and objectAdmin on their own bucket. That's it.\n\n**Secret management:** Bot tokens, webhook secrets, and the Anthropic API key all live in Secret Manager. Nothing sensitive in environment variables or container images.\n\n**Device pairing bypass:** OpenClaw normally requires an interactive shell command to approve devices. Cloud Run has no shell. *dmPolicy: allowlist* with the tenant's user ID in allowFrom bypasses pairing entirely — safe because the router already validated the webhook source before the message arrived.\n\n## Instructions\n\n### Prerequisites\n\n- GCP project with billing enabled\n- gcloud CLI authenticated\n- terraform / opentofu installed\n- Docker with linux/amd64 build support\n\n### 1. Clone the repo\n\n```bash\ngit clone https://github.com/cloudon-one/openclaw-serverless\ncd openclaw-serverless\n```\n\n### 2. Configure your project\n\n```bash\n# Set your GCP project\nexport PROJECT_ID=your-gcp-project-id\nexport REGION=us-central1\nexport REGISTRY=\"${REGION}-docker.pkg.dev/${PROJECT_ID}/openclaw\"\ngcloud config set project $PROJECT_ID\ngcloud auth configure-docker ${REGION}-docker.pkg.dev\n```\n\n### 3. Create the Artifact Registry repository and enable APIs\n\n```bash\ngcloud services enable run.googleapis.com \\\n  secretmanager.googleapis.com \\\n  artifactregistry.googleapis.com\n\ngcloud artifacts repositories create openclaw \\\n  --repository-format=docker \\\n  --location=$REGION\n```\n\n### 4. Build and push both container images\n\n```bash\n./scripts/build.sh\n```\n\nOr manually:\n\n```bash\ndocker build --platform linux/amd64 -t ${REGISTRY}/agent:latest .\ndocker build --platform linux/amd64 -t ${REGISTRY}/router:latest .\ndocker push ${REGISTRY}/agent:latest\ndocker push ${REGISTRY}/router:latest\n```\n\n### 5. Store your Anthropic API key\n\n```bash\necho -n \"YOUR_ANTHROPIC_API_KEY\" | gcloud secrets create openclaw-anthropic-api-key \\\n  --data-file=- --replication-policy=automatic\n```\n\n### 6. Define your first tenant in tenants.yaml\n\n```yaml\ntenants:\n  alice:\n    display_name: \"Alice Smith\"\n    telegram_user_id: \"YOUR_TELEGRAM_USER_ID\"\n    telegram_enabled: true\n    slack_enabled: false\n    min_instances: 0\n    max_instances: 1\n    cpu: \"2\"\n    memory: \"2Gi\"\n```\n\n### 7. Deploy infrastructure\n\n```bash\ncd infrastructure\ncp terraform.tfvars.example terraform.tfvars\n# Edit terraform.tfvars with your project ID, region, registry URL\n\nterraform init\nterraform apply\n```\n\nTerraform creates: service accounts, GCS buckets, Secret Manager containers, Cloud Run services (router + one per tenant).\n\n### 8. Create a Telegram bot\n\n- Message @BotFather on Telegram\n- Use /newbot and copy the token\n\n### 9. Store tenant secrets\n\n```bash\n# Telegram bot token\necho -n \"YOUR_BOT_TOKEN\" | gcloud secrets versions add \\\n  openclaw-sl-alice-telegram-token --data-file=-\n\n# Webhook validation secret (random)\nopenssl rand -hex 32 | gcloud secrets versions add \\\n  openclaw-sl-alice-telegram-webhook-secret --data-file=-\n```\n\n### 10. Register the Telegram webhook\n\n```bash\nROUTER_URL=$(cd infrastructure && terraform output -raw router_url)\nWEBHOOK_SECRET=$(gcloud secrets versions access latest \\\n  --secret=openclaw-sl-alice-telegram-webhook-secret)\n\ncurl \"https://api.telegram.org/bot${YOUR_BOT_TOKEN}/setWebhook\" \\\n  -d \"url=${ROUTER_URL}/webhook/telegram\" \\\n  -d \"secret_token=${WEBHOOK_SECRET}\"\n```\n\nThat's it. Send a message to your bot on Telegram. The first response takes ~15–20 seconds for a cold start; subsequent messages in the same session are fast.\n\n## Conclusion\n\nThe solution works well and the GCSFuse approach is genuinely nicer than S3 sync — one less moving part, no 5-minute flush window, no shutdown race condition. A few things worth knowing before you deploy:\n\n**cpu_idle: false adds cost but is required.** Agent sessions involve async operations and WebSocket connections that break under CPU throttling. With *min_instances: 0* you're only paying when the container is actually running, so this is acceptable — but it's not free.\n\n**Gen2 execution environment is non-negotiable.** GCSFuse is not available in Gen1. Set *execution_environment = \"EXECUTION_ENVIRONMENT_GEN2\"* in Terraform or the mount will silently fail.\n\n**Cold starts are real.** First message to an idle tenant takes 15–20 seconds. For async chat this is fine; for anything latency-sensitive it's a problem. Set min_instances: 1 per tenant if you need it — just budget accordingly.\n\n**Adding a second tenant is genuinely one YAML entry + *terraform apply*.**\n\nThe isolation model scales cleanly. Each tenant is a fully independent island with no shared state.\n\n**The Terraform state bucket needs to exist before *terraform init*.** Create it manually or bootstrap it separately — classic chicken-and-egg.\n\nCompared to the AWS AgentCore approach, the GCP version skips the NAT gateway entirely (Cloud Run has direct internet egress) which removes the ~$32/month baseline AWS cost.\n\nFor a single personal agent, this architecture is essentially free at idle.\n\n## Want to try it?\n\nThe repo is at [https://github.com/cloudon-one/openclaw-serverless](https://github.com/cloudon-one/openclaw-serverless). If you hit issues or want to extend it to other channels (WhatsApp, Discord), the router is straightforward to extend.\n",
  "content_sha256": "7f08b912224741cc233570edff74ea71fdc19acdf3931cfedc07ec917d92f96c"
}
