Skip to content

gcp

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

gcp

README.md

GCP Cloud Run elizaOS Worker Examples

Deploy elizaOS agents as serverless GCP Cloud Run services. This example shows how to run an AI agent as a containerized worker that processes chat messages via HTTP.

Architecture

┌──────────────┐     ┌─────────────────┐     ┌────────────────┐
│  Test Client │────▶│  Cloud Run      │────▶│  elizaOS       │
│  (curl/node) │◀────│  (HTTP)         │◀────│  Worker        │
└──────────────┘     └─────────────────┘     └────────────────┘
                                                     │
                                                     ▼
                                              ┌────────────────┐
                                              │  OpenAI API    │
                                              └────────────────┘

Prerequisites

  • Google Cloud SDK installed and configured
  • Docker installed
  • GCP project with Cloud Run API enabled
  • OpenAI API key

Quick Start

1. Set Environment Variables

export PROJECT_ID="your-gcp-project-id"
export REGION="us-central1"
export OPENAI_API_KEY="your-openai-api-key"

2. Enable Required APIs

gcloud config set project $PROJECT_ID
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable artifactregistry.googleapis.com

3. Deploy

cd packages/examples/gcp
npm install
npm run build

# Build and deploy
gcloud run deploy eliza-worker-ts \
  --source . \
  --region $REGION \
  --allow-unauthenticated \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"

4. Test Your Deployment

After deployment, Cloud Run provides a URL. Test it:

# Get service URL
SERVICE_URL=$(gcloud run services describe eliza-worker-ts --region $REGION --format 'value(status.url)')

# Health check
curl $SERVICE_URL/health

# Chat
curl -X POST $SERVICE_URL/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, Eliza!"}'

# Using the test client
cd packages/examples/gcp
bun run test-client.ts --url $SERVICE_URL

Local Development

cd packages/examples/gcp
npm install
npm run dev
# Server runs at http://localhost:8080

Validate

bun run test
bun run typecheck

bun run test performs a non-interactive worker availability check. If no local or deployed worker URL is configured, it skips cleanly and prints the setup hint.

Project Structure

packages/examples/gcp/
├── README.md                 # This file
├── Dockerfile                # Cloud Run container image
├── handler.ts                # Cloud Run handler
├── test-client.ts            # Interactive test client
├── package.json              # Test client dependencies
├── cloudbuild.yaml           # Cloud Build configuration
├── deploy.sh                 # Deployment helper
├── env.example               # Environment template
└── terraform/                # Optional infrastructure template

API Reference

POST /chat

Send a message to the elizaOS agent.

Request:

{
  "message": "Hello, how are you?",
  "userId": "optional-user-id",
  "conversationId": "optional-conversation-id"
}

Response:

{
  "response": "I'm doing well, thank you for asking!",
  "conversationId": "uuid-for-conversation-tracking",
  "timestamp": "2025-01-10T12:00:00.000Z"
}

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "runtime": "typescript",
  "version": "2.0.0-beta.0"
}

GET /

Service info endpoint.

Response:

{
  "name": "Eliza",
  "bio": "A helpful AI assistant.",
  "version": "2.0.0-beta.0",
  "powered_by": "elizaOS"
}

Deployment Options

Option 1: gcloud run deploy (Recommended)

# Deploy from source (builds automatically)
gcloud run deploy eliza-worker \
  --source . \
  --region $REGION \
  --allow-unauthenticated \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"

Option 2: Cloud Build

# Submit build and deploy
gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_REGION=$REGION,_OPENAI_API_KEY=$OPENAI_API_KEY

Option 3: Terraform

See the Terraform example for infrastructure-as-code deployment.

Configuration

Environment Variables

Variable Required Default Description
OPENAI_API_KEY Yes - Your OpenAI API key
OPENAI_MODEL No gpt-5-mini Model to use
OPENAI_BASE_URL No OpenAI default Custom API endpoint
CHARACTER_NAME No Eliza Agent's name
CHARACTER_BIO No A helpful AI assistant. Agent's bio
CHARACTER_SYSTEM No Default system prompt Custom system prompt
PORT No 8080 Server port (set by Cloud Run)
LOG_LEVEL No INFO Logging level

Character Customization

Customize the agent's personality via environment variables:

gcloud run deploy eliza-worker \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY" \
  --set-env-vars "CHARACTER_NAME=Ada" \
  --set-env-vars "CHARACTER_BIO=A brilliant mathematician and programmer" \
  --set-env-vars "CHARACTER_SYSTEM=You are Ada Lovelace, speaking from the 19th century..."

Performance Considerations

Cold Starts

Cloud Run cold starts are typically 1-3 seconds. To minimize:

  1. Minimum Instances: Keep at least one instance warm

    gcloud run deploy eliza-worker --min-instances 1

  2. Smaller Container: Use multi-stage Docker builds

  3. Startup CPU Boost: Enable for faster cold starts

    gcloud run deploy eliza-worker --cpu-boost

Resource Configuration

Recommended settings:

Runtime Memory CPU Timeout
TypeScript 512 Mi 1 60s 
gcloud run deploy eliza-worker \
  --memory 512Mi \
  --cpu 1 \
  --timeout 60s

Monitoring

View Logs

gcloud run logs read eliza-worker --region $REGION --limit 100

Streaming Logs

gcloud run logs tail eliza-worker --region $REGION

Cloud Monitoring

Cloud Run automatically provides metrics:

  • Request count
  • Request latencies
  • Container instance count
  • Billable container instance time
  • CPU and memory utilization

Cost Estimation

Cloud Run pricing (as of 2025):

  • CPU: $0.000024 per vCPU-second
  • Memory: $0.0000025 per GiB-second
  • Requests: $0.40 per million requests

Example (1 vCPU, 512 MiB, 2s avg duration, 10K requests/month):

  • CPU: 10,000 × 2s × $0.000024 = $0.48
  • Memory: 10,000 × 2s × 0.5 × $0.0000025 = $0.025
  • Requests: 10,000 × $0.0000004 = $0.004
  • Total: ~$0.51/month

Note: Free tier includes 2 million requests/month

Authentication

Allow Unauthenticated (Public)

gcloud run deploy eliza-worker --allow-unauthenticated

Require Authentication

gcloud run deploy eliza-worker --no-allow-unauthenticated

# Invoke with authentication
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  $SERVICE_URL/chat

Custom Domain

gcloud run domain-mappings create \
  --service eliza-worker \
  --domain eliza.yourdomain.com \
  --region $REGION

Troubleshooting

Container Fails to Start

Check logs for startup errors:

gcloud run logs read eliza-worker --region $REGION --limit 50

"Permission Denied" Error

Ensure the service account has required permissions:

gcloud run services add-iam-policy-binding eliza-worker \
  --member="allUsers" \
  --role="roles/run.invoker" \
  --region $REGION

API Key Not Found

Verify environment variables are set:

gcloud run services describe eliza-worker \
  --region $REGION \
  --format 'yaml(spec.template.spec.containers[0].env)'

Timeout Errors

Increase request timeout:

gcloud run deploy eliza-worker --timeout 300s

Cleanup

Remove all deployed resources:

# Delete Cloud Run service
gcloud run services delete eliza-worker --region $REGION --quiet

# Delete container images (optional)
gcloud artifacts docker images delete \
  $REGION-docker.pkg.dev/$PROJECT_ID/eliza/eliza-worker --quiet

Security Best Practices

  1. Use Secret Manager for API keys:

    echo -n "$OPENAI_API_KEY" | gcloud secrets create openai-api-key --data-file=-

gcloud run deploy eliza-worker \
  --set-secrets "OPENAI_API_KEY=openai-api-key:latest"

  2. Enable VPC Connector for private networking

  3. Set up Cloud Armor for DDoS protection

  4. Use IAM for authentication when possible

See Also