Skip to main content

​
Introduction

Silvana Book relies on autonomous off-chain agents to perform sensitive operations such as cryptographic signing. When deployed on Google Cloud, these agents run as secure, scalable services with strict IAM boundaries and protected key storage. The result is a production-grade signing endpoint that integrates cleanly into the broader Silvana Book infrastructure. This guide explains how to deploy and configure such an agent within a Google Cloud environment.
Google Cloud provides a secure, scalable, and production-grade runtime for Silvana Book agents. When deployed on Google Cloud, the agent runs inside Cloud Run as a managed container, with private key storage handled by Secret Manager and external access controlled through API Gateway.
Silvana Book agents are not tied to a single hosting model: you can deploy the agent on your own infrastructure or run it on Google Cloud.
  • Self-hosted: Full infrastructure control, internal scaling and deployment management.
  • Google Cloud: Managed runtime, automatic scaling, built-in secret storage, faster production rollout.

​
Before You Start

The Silvana Book agents can be obtained from our official repository here.
Deploying a Google Cloud Agent will:
  • Create or modify a Google Cloud project
  • Enable billable services
  • Assign IAM roles
  • Store a private signing key in Secret Manager
Ensure you are operating in the correct Google Cloud account and project. Deploying into the wrong environment may expose resources unintentionally or generate unexpected costs.

​
Step 1: Authenticate and Prepare the Environment

  1. Install and authenticate Google Cloud CLI:
gcloud auth login
  1. Verify available projects:
gcloud projects list
If no project exists, one must be created in the next step.

​
Step 2: Create or Select a Google Cloud Project

You can either create a new isolated project for the agent or deploy into an existing one.

​
Create a New Project

gcloud projects create <PROJECT_ID>
  1. Link billing:
gcloud billing projects link <PROJECT_ID> --billing-account=<ACCOUNT_ID>
  1. Set it as active:
gcloud config set project <PROJECT_ID>

​
Use an Existing Project

gcloud config set project <PROJECT_ID>
  1. Confirm billing is enabled:
gcloud billing projects describe <PROJECT_ID>
  1. If billing is disabled, link a billing account before proceeding.

​
Step 3: Enable Required Services

Google Cloud Agents depend on several managed services. Enable them: 
gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  secretmanager.googleapis.com \
  apigateway.googleapis.com \
  servicecontrol.googleapis.com \
  servicemanagement.googleapis.com
This activates:
  • Serverless runtime (Cloud Run)
  • Container builds (Cloud Build)
  • Image storage (Artifact Registry)
  • Secure secret storage (Secret Manager)
  • API exposure (API Gateway)

​
Step 4: Configure IAM Permissions

  1. Retrieve your project number:
gcloud projects describe <PROJECT_ID> --format="value(projectNumber)"
  1. The default service account follows this format:
<PROJECT_NUMBER>-compute@developer.gserviceaccount.com
  1. Grant required roles:
gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:<COMPUTE_SA>" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:<COMPUTE_SA>" \
  --role="roles/artifactregistry.writer"
  1. Later steps will require:
  • roles/secretmanager.secretAccessor
  • roles/run.invoker
IAM changes may take several minutes to propagate.

​
Step 5: Create Artifact Registry Repository

Create a Docker repository: 
gcloud artifacts repositories create cloud-run-source-deploy \
  --repository-format=docker \
  --location=us-central1
This repository stores the container image generated during deployment.

​
Step 6: Secure the Ed25519 Private Key

The Google Cloud Agent requires a base58-encoded 64-byte Ed25519 private key.
  1. Create a secret:
echo -n "<PRIVATE_KEY>" | \
gcloud secrets create ed25519-private-key --data-file=-
  1. If it already exists:
echo -n "<PRIVATE_KEY>" | \
gcloud secrets versions add ed25519-private-key --data-file=-
  1. Grant runtime access:
gcloud secrets add-iam-policy-binding ed25519-private-key \
  --member="serviceAccount:<COMPUTE_SA>" \
  --role="roles/secretmanager.secretAccessor"
The private key is never hardcoded and never exposed in logs. Cloud Run retrieves it securely at runtime.

​
Step 7: Deploy the Agent to Cloud Run

  1. Deploy the agent directly from source. The deployment must explicitly clear any previously set PRIVATE_KEY environment variable before injecting the Secret Manager value.
gcloud run deploy ed25519-signer \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --remove-env-vars="PRIVATE_KEY" \
  --set-secrets="PRIVATE_KEY=ed25519-private-key:latest" \
  --memory 256Mi \
  --cpu 1 \
  --min-instances 0 \
  --max-instances 10 \
  --quiet
This deployment performs the following:
  • Builds the container image via Cloud Build.
  • Stores the image in Artifact Registry.
  • Deploys a new Cloud Run revision.
  • Injects the private key securely from Secret Manager.
  • Ensures no plaintext PRIVATE_KEY variable remains in runtime.
  1. Retrieve the Cloud Run URL:
gcloud run services describe ed25519-signer \
  --region us-central1 \
  --format="value(status.url)"

​
Step 8: Configure API Gateway

  1. Create an OpenAPI specification that routes requests to Cloud Run and requires an API key.
  2. Define routes:
  • GET /health
  • POST /sign
  • GET /publickey
  1. Create the API:
gcloud api-gateway apis create ed25519-api
  1. Set configuration:
gcloud api-gateway api-configs create ed25519-config \
  --api=ed25519-api \
  --openapi-spec=openapi.yaml \
  --backend-auth-service-account=<COMPUTE_SA>
  1. Grant invocation permission:
gcloud run services add-iam-policy-binding ed25519-signer \
  --member="serviceAccount:<COMPUTE_SA>" \
  --role="roles/run.invoker" \
  --region=us-central1
  1. Deploy gateway:
gcloud api-gateway gateways create ed25519-gateway \
  --api=ed25519-api \
  --api-config=ed25519-config \
  --location=us-central1
  1. Retrieve the gateway hostname:
gcloud api-gateway gateways describe ed25519-gateway \
  --location=us-central1 \
  --format="value(defaultHostname)"

​
Step 9: Enable Managed Service and Create API Key

  1. Retrieve the managed service name:
MANAGED_SERVICE=$(gcloud api-gateway apis describe ed25519-api \
  --format="value(managedService)")
  1. Enable it:
gcloud services enable $MANAGED_SERVICE --quiet
  1. Create an API key restricted to this service:
gcloud services api-keys create \
  --display-name="Ed25519 Signer Key" \
  --api-target=service=$MANAGED_SERVICE \
  --quiet
  1. Retrieve the API key value:
API_KEY_NAME=$(gcloud services api-keys list \
  --format="value(name)" --limit=1)

gcloud services api-keys get-key-string $API_KEY_NAME \
  --format="value(keyString)"
All requests to the gateway must include: 
x-api-key: <API_KEY>

​
Step 10: Test the Running Agent

  1. Run health check:
curl -H "x-api-key: <API_KEY>" \
     https://<GATEWAY_URL>/health
  1. Sign request:
curl -H "x-api-key: <API_KEY>" \
     -X POST https://<GATEWAY_URL>/sign \
     -H 'Content-Type: application/json' \
     -d '{"message":"Hello"}'
If you receive 403 Forbidden, wait a few minutes for IAM propagation.

​
Updating the Agent

To release a new version:
  1. Update source code.
  2. Re-run the gcloud run deploy command.
  3. Cloud Run creates a new revision.
  4. Traffic shifts automatically to the latest revision.
Previous revisions remain available for rollback.

​
Operational Notes

For improved performance, follow these guidelines:
  • Separate staging and production environments.
  • Rotate the private key by adding a new secret version.
  • Monitor scaling limits if signing volume increases.
  • Restrict public access if gateway-only invocation is required.
  • Check logs with:
gcloud run services logs read ed25519-signer --region us-central1

​
Deployment Outcome

Once completed, the Google Cloud Agent operates as:
  • a serverless Cloud Run backend;
  • a cryptographic signing service using secure secret injection;
  • an HTTPS endpoint protected by API Gateway;
  • a horizontally scalable, revision-based runtime.
The infrastructure remains fully managed while maintaining strict control over private key material and access boundaries.