# How to Run AI Agents on Google Cloud Run with Fastio

Google Cloud Run is a good home for an agent that runs on demand and then gets out of the way. This guide covers the deployment that actually applies: you containerize your own agent, and it connects out to the Fastio MCP server, which Fastio hosts. You will set up least-privilege IAM, keep the Fastio API key in Secret Manager, tune timeouts and concurrency for long agent turns, and decide what to do about cold starts.

Source: https://fast.io/resources/deploy-fastio-mcp-server-google-cloud-run/
Last reviewed: 2026-09-02

## What you are actually deploying

Start with the shape of the system, because it is the thing most Cloud Run guides get backwards.

Fastio hosts its MCP server remotely at `https://mcp.fast.io/mcp`, with `https://mcp.fast.io/mcp/key` for scoped API key authentication and `/sse` for legacy SSE clients. You do not deploy, containerize, or run the Fastio server. What you deploy to Cloud Run is **your agent**: the service that holds the model loop, receives triggers, and calls the hosted Fastio MCP server as a client.

Once that is clear, Cloud Run turns out to be a good fit. Agents are bursty. They sit idle, then do a few minutes of concentrated work, then go quiet again. Cloud Run scales stateless containers automatically and scales them to zero when nothing is happening, so an agent that runs a handful of times a day costs close to nothing between runs. When a request arrives, the container starts and handles it.

Your agent container stays stateless, which is what makes this work. Files, versions, search indexes, and the audit trail all live in the Fastio workspace rather than on the container's disk, so an instance can be destroyed mid-life without losing anything. That is the property that lets you scale to zero at all.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/). For the endpoints and auth options your agent will use, see the [Fastio MCP server integration guide](/resources/fastio-mcp-server-integration-developers/).

## Prerequisites and Initial Setup

Before starting the deployment, check that your local environment and Google Cloud project are configured correctly. This step prevents common permission errors later.

Verify that you have a Google Cloud account with an active billing profile. Create a new project for this deployment or use an existing one meant for your AI infrastructure. After creating the project, enable the Cloud Run API, Cloud Build API, and Artifact Registry API in the Google Cloud Console.

Install the Google Cloud CLI (`gcloud`) on your local machine. This command-line tool handles authentication with your GCP account and executes the deployment commands. Run `gcloud auth login` to authenticate. Then run `gcloud config set project [YOUR_PROJECT_ID]` to set your active project context. You can check your setup by running `gcloud config list`.

You also need Fastio credentials for the agent to authenticate with. A Cloud Run service has no browser, so the OAuth path is not available to it and you want a scoped API key instead. Have a human create a dedicated key for this service rather than reusing a personal one, and scope it to the specific workspace the agent needs. A dedicated, narrowly scoped key is what makes rotation cheap and what limits the damage if the service is ever compromised.

## Containerizing your agent

Package your agent as a container the same way you would any other web service. Cloud Run requires the container to listen on the port given in the `PORT` environment variable, so read it rather than hardcoding a port.

Your agent's dependencies are its model client and its MCP client, whatever those are in your language. There is nothing of Fastio's to install: the MCP server is remote, so your agent reaches it by opening a connection to a URL. If your framework has no MCP support at all, call the [Fastio REST API](https://api.fast.io/current/) directly with the language's ordinary HTTP library. Do not go looking for a Fastio client library, because there is not one in any language.

Create a `Dockerfile` in the root of your project. Use a lightweight base image for your runtime. Copy your dependency manifest and install before copying the rest of your source, so the dependency layer stays cached across builds. Multi-stage builds keep the final image small, which speeds up deployment and shortens cold starts.

Run the container as a non-root user. On a Node base image, add a `USER node` directive before the final execution step. This costs nothing and removes a whole class of container escape concerns.

After finishing your `Dockerfile`, use Google Cloud Build to create the image and push it to the Artifact Registry. The command `gcloud builds submit --tag gcr.io/[YOUR_PROJECT_ID]/my-agent` builds and uploads the image at the same time, so you avoid building and tagging locally before pushing.

## Configuring IAM Roles and Secrets

Security matters when deploying a system that gives AI agents access to your files. Google Cloud offers Identity and Access Management (IAM) and Secret Manager to protect your Fastio credentials.

Do not hardcode your Fastio API key in your source code or Dockerfile. Use Google Cloud Secret Manager to store the credential. Create a new secret named `FASTIO_API_KEY` and paste your key as the value. You can do this in the Google Cloud Console or by running the `gcloud secrets create` command.

Cloud Run services execute under a service account. By default, this uses the Compute Engine default service account. Create a dedicated service account with least privilege instead, such as `my-agent-runner@[YOUR_PROJECT_ID].iam.gserviceaccount.com`. This isolates the agent's permissions from other workloads in your GCP project.

Grant this new service account permission to access the secret. Assign the `Secret Manager Secret Accessor` role to the service account, scoped specifically to the `FASTIO_API_KEY` secret. The container can then retrieve the key during startup without gaining access to other secrets.

If your agent interacts with other Google Cloud services like Cloud Storage or Vertex AI, grant those roles to the service account too. Tightly scoped permissions limit the risk if the service is compromised or an agent issues an unexpected command.

Scope the Fastio key with the same discipline. An agent that writes a weekly report into one workspace needs a key for one workspace, not for everything the person who created it can see.

## Deploying with the gcloud CLI

After building your container and setting up security, you can deploy the service to Cloud Run. The deployment requires your container image, service account, and secrets mapping.

Run the deployment using this command:

`gcloud run deploy my-agent `
`  --image gcr.io/[YOUR_PROJECT_ID]/my-agent `
`  --service-account my-agent-runner@[YOUR_PROJECT_ID].iam.gserviceaccount.com `
`  --set-secrets="FASTIO_API_KEY=FASTIO_API_KEY:latest" `
`  --region us-central1`

This pulls the image from the Artifact Registry and starts the service. The `--set-secrets` flag maps the secret value into an environment variable inside the container, so your code reads it from the environment without the plain text value appearing in the Cloud Run interface.

Think carefully before adding `--allow-unauthenticated`. It makes your agent's endpoint reachable by anyone on the internet, and an agent endpoint is a more attractive target than a static site. Prefer requiring IAM authentication on the service and invoking it from an authenticated caller, or put it behind an internal load balancer if only internal services trigger it.

Note that the outbound direction needs no ingress configuration at all. Your agent connects out to `https://mcp.fast.io/mcp`, and outbound HTTPS works from Cloud Run by default.

## Timeouts and long agent turns

Agent turns are long by the standards of a web request, and this is where Cloud Run deployments usually break first.

Cloud Run enforces a request timeout that defaults to a few minutes. An agent that plans, calls several tools, and then writes a summary can easily exceed it. Raise it with the `--timeout` flag at deploy time, for example `--timeout=[TIMEOUT_IN_SECONDS]`. If a run can take longer than the maximum Cloud Run allows, restructure it: accept the request, return immediately, and do the work asynchronously rather than holding an HTTP connection open for the whole turn.

Your agent's connection to the Fastio MCP server is a separate concern. Streamable HTTP is the current transport and the one to build against; a legacy SSE endpoint exists at `https://mcp.fast.io/sse` for clients that have not migrated. Whichever your client uses, make sure it reconnects cleanly, because a container that Cloud Run recycles between runs will need to re-establish the connection on the next request rather than assuming a warm one.

For strict network isolation, deploy the Cloud Run service behind an Internal HTTP(S) Load Balancer connected to a VPC. Internal orchestrators can then trigger the agent without traffic crossing the public internet, while the agent still reaches Fastio over outbound HTTPS.

## Scaling Characteristics and Concurrency

Cloud Run containers handle multiple simultaneous requests rather than one at a time, which is the main reason it is cheaper than older function platforms for this workload.

Agent work is mostly I/O bound. Your container spends most of its time waiting on the model provider and on the Fastio API, using very little CPU while it waits. That profile suits high concurrency: one instance can serve several agent runs at once, which keeps the instance count and the bill down.

Memory is the limit you are more likely to hit. Concurrent file uploads or a large directory listing can push a container past its allocation. Adjust it with the `--memory` flag, such as `--memory=1Gi`. When an instance reaches its concurrency limit, Cloud Run starts another to absorb the overflow without dropping requests.

When nothing is running, Cloud Run scales to zero and you stop paying. The cost is a cold start: the first request after an idle period waits a few seconds for the container to initialize. If that latency is unacceptable, set `--min-instances=[YOUR_MIN_INSTANCES]` to keep one warm, and accept that a warm instance bills continuously. For most agent workloads triggered by a schedule or another external service, the cold start is not worth paying to avoid.

## Best Practices for Agent Integration

Once the service is deployed, most of the remaining wins are in how the agent uses its tools.

Tell the agent to search before it reads. Guessing at file paths burns tokens and produces confident errors. When Intelligence is enabled on a workspace, search combines exact matching with meaning-based retrieval and returns the passages that matched, not just the filenames, so one search usually replaces several speculative reads.

Monitor your service logs in Google Cloud Logging. Log every tool invocation your agent makes, with its arguments and the outcome. If an agent gets stuck querying the same folder in a loop, the logs show the pattern immediately, and the fix is almost always in the system prompt rather than the infrastructure.

Watch the two records that matter for different reasons. Cloud Run logs tell you what your container did. The append-only Fastio audit log tells you what actually happened to the files, for human and agent actions alike, and it is not editable by the thing being audited. When you are trying to work out whether an agent really wrote what it claims it wrote, that is the one to read.

Finally, plan for cost on both sides. Cloud Run bills for active execution time. Fastio bills usage-based credits, metered separately for storage, bandwidth, AI tokens, and document ingestion. For a new agent integration the ingestion meter is usually the one to model first, because indexing an existing document set is a one-time cost that dwarfs the steady state. Every organization starts with a 14-day trial, and the trial requires a credit card.

## Frequently asked questions

### Do I deploy the Fastio MCP server itself to Cloud Run?

No. The Fastio MCP server is remote and hosted by Fastio at https://mcp.fast.io/mcp. There is nothing to containerize and no image to build for it. What you deploy to Cloud Run is your own agent, which connects out to that server as a client.

### How should the agent authenticate from Cloud Run?

Use a scoped API key rather than OAuth, because a Cloud Run service has no browser to complete a login. Store the key in Secret Manager, map it into the container with the --set-secrets flag, and point the client at https://mcp.fast.io/mcp/key so it sends the key as an Authorization Bearer header.

### What is the expected cost of running this?

Cloud Run bills only for active execution time and scales to zero between runs, so an intermittent agent costs very little on the Google side. Fastio bills separately as usage-based credits metered on storage, bandwidth, AI tokens, and ingestion, and every organization starts with a 14-day trial that requires a credit card.

### How does the agent handle large file transfers?

Keep the bytes out of your container wherever you can. Have Fastio import the file directly from Google Drive, Dropbox, OneDrive, Box, or any public URL, so the payload never round-trips through Cloud Run. Uploads from the container itself use chunked sessions, and maximum file size depends on the active plan.

### Can I connect the Claude desktop app to this instead?

For desktop clients you do not need Cloud Run at all. Point the client straight at https://mcp.fast.io/mcp with a url field in its server config, since the server is remote and there is no local process to spawn. Cloud Run is for running your own agent unattended, not for reaching Fastio from a desktop.

### How do I update the agent to a new version?

Rebuild your Docker image with the updated code, push it to the Artifact Registry with a new tag, and run the gcloud run deploy command again referencing the new tag. Cloud Run shifts traffic to the new revision with zero downtime.

### What causes connection timeouts during agent operations?

Usually the Cloud Run request timeout, which defaults to a few minutes and is often shorter than a full agent turn. Raise it with the --timeout flag at deploy time. If a run can exceed the maximum Cloud Run allows, accept the request and do the work asynchronously instead of holding the connection open.

### Does this require a dedicated database?

No. Your agent container stays stateless. Files, version history, search indexes, and the audit trail all live in the Fastio workspace, which is what allows the container to be recycled or scaled to zero without losing anything.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.