packages/examples/gcp/README.md
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.
┌──────────────┐ ┌─────────────────┐ ┌────────────────┐
│ Test Client │────▶│ Cloud Run │────▶│ elizaOS │
│ (curl/node) │◀────│ (HTTP) │◀────│ Worker │
└──────────────┘ └─────────────────┘ └────────────────┘
│
▼
┌────────────────┐
│ OpenAI API │
└────────────────┘
export PROJECT_ID="your-gcp-project-id"
export REGION="us-central1"
export OPENAI_API_KEY="your-openai-api-key"
gcloud config set project $PROJECT_ID
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable artifactregistry.googleapis.com
cd 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"
cd examples/gcp/python
# Build and deploy
gcloud run deploy eliza-worker-py \
--source . \
--region $REGION \
--allow-unauthenticated \
--set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"
cd examples/gcp/rust
# Build container
docker build -t eliza-worker-rust .
# Tag and push to Artifact Registry
docker tag eliza-worker-rust $REGION-docker.pkg.dev/$PROJECT_ID/eliza/eliza-worker-rust
docker push $REGION-docker.pkg.dev/$PROJECT_ID/eliza/eliza-worker-rust
# Deploy
gcloud run deploy eliza-worker-rust \
--image $REGION-docker.pkg.dev/$PROJECT_ID/eliza/eliza-worker-rust \
--region $REGION \
--allow-unauthenticated \
--set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"
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 examples/gcp
bun run test-client.ts --url $SERVICE_URL
cd examples/gcp
npm install
npm run dev
# Server runs at http://localhost:8080
cd examples/gcp/python
pip install -r requirements.txt
python handler.py
# Server runs at http://localhost:8080
cd examples/gcp/rust
cargo run
# Server runs at http://localhost:8080
examples/gcp/
├── README.md # This file
├── test-client.ts # Interactive test client
├── package.json # Test client dependencies
├── cloudbuild.yaml # Cloud Build configuration
├── typescript/
│ ├── handler.ts # Cloud Run handler
│ ├── Dockerfile
│ ├── package.json
│ └── tsconfig.json
├── python/
│ ├── handler.py # Cloud Run handler
│ ├── Dockerfile
│ └── requirements.txt
└── rust/
├── Cargo.toml
├── Dockerfile
└── src/
└── main.rs # Cloud Run handler
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"
}
Health check endpoint.
Response:
{
"status": "healthy",
"runtime": "typescript|python|rust",
"version": "2.0.0-beta.0"
}
Service info endpoint.
Response:
{
"name": "Eliza",
"bio": "A helpful AI assistant.",
"version": "2.0.0-beta.0",
"powered_by": "elizaOS"
}
# Deploy from source (builds automatically)
gcloud run deploy eliza-worker \
--source . \
--region $REGION \
--allow-unauthenticated \
--set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"
# Submit build and deploy
gcloud builds submit --config=cloudbuild.yaml \
--substitutions=_REGION=$REGION,_OPENAI_API_KEY=$OPENAI_API_KEY
See the Terraform example for infrastructure-as-code deployment.
| 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 |
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..."
Cloud Run cold starts are typically 1-3 seconds. To minimize:
Minimum Instances: Keep at least one instance warm
gcloud run deploy eliza-worker --min-instances 1
Smaller Container: Use multi-stage Docker builds
Startup CPU Boost: Enable for faster cold starts
gcloud run deploy eliza-worker --cpu-boost
Recommended settings:
| Runtime | Memory | CPU | Timeout |
|---|---|---|---|
| TypeScript | 512 Mi | 1 | 60s |
| Python | 512 Mi | 1 | 60s |
| Rust | 256 Mi | 1 | 60s |
gcloud run deploy eliza-worker \
--memory 512Mi \
--cpu 1 \
--timeout 60s
gcloud run logs read eliza-worker --region $REGION --limit 100
gcloud run logs tail eliza-worker --region $REGION
Cloud Run automatically provides metrics:
Cloud Run pricing (as of 2025):
Example (1 vCPU, 512 MiB, 2s avg duration, 10K requests/month):
Note: Free tier includes 2 million requests/month
gcloud run deploy eliza-worker --allow-unauthenticated
gcloud run deploy eliza-worker --no-allow-unauthenticated
# Invoke with authentication
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
$SERVICE_URL/chat
gcloud run domain-mappings create \
--service eliza-worker \
--domain eliza.yourdomain.com \
--region $REGION
Check logs for startup errors:
gcloud run logs read eliza-worker --region $REGION --limit 50
Ensure the service account has required permissions:
gcloud run services add-iam-policy-binding eliza-worker \
--member="allUsers" \
--role="roles/run.invoker" \
--region $REGION
Verify environment variables are set:
gcloud run services describe eliza-worker \
--region $REGION \
--format 'yaml(spec.template.spec.containers[0].env)'
Increase request timeout:
gcloud run deploy eliza-worker --timeout 300s
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
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"
Enable VPC Connector for private networking
Set up Cloud Armor for DDoS protection
Use IAM for authentication when possible