# Cloud Run

> Run Cloud Run locally with LocalCloud: connection settings, supported workflows, known limits, and code examples.
>
> Source: https://local.cloud/services/cloud-run/

Cloud Run runs containerized applications behind HTTP endpoints on Google Cloud. LocalCloud runs supported service containers through Docker for local request tests.

## Typical uses

Use when you can package an HTTP application in a container image and test it through a service URL. LocalCloud runs supported service containers with Docker.

Examples

- Containerized HTTP APIs
- Service deployment and update tests

Cloud Run is opt-in to save memory. Add `cloudrun` to the services you start, for example `localcloud start --local-only --services cloudrun,gcs,pubsub`; `--services` sets the exact list.

Connection

Environment variable

`CLOUD_RUN_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** metadata
- **Implementation:** Local Facade

## Example usage

Service ID: `cloudrun`. Enable this service in the exact list of services your project starts; see the opt-in instruction above. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. [First-time setup](https://local.cloud/docs/)

```bash
# Export GOOGLE_CLOUD_PROJECT and CLOUD_RUN_EMULATOR_HOST
eval "$(localcloud env)"
```

Java:

### Java

### List local container services

List deployed container services; Cloud Run turns an application image into an HTTP endpoint.

Use the Cloud Run SDK over the local gRPC endpoint with a plaintext channel and no credentials. Requires JDK 17+ and Maven.

Discovery check · reads existing local state.

SDK dependencies

Run in a new example directory

```bash
cat > pom.xml <<'XML'
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId><artifactId>local-example</artifactId><version>1</version>
  <dependencies><dependency>
    <groupId>com.google.cloud</groupId><artifactId>google-cloud-run</artifactId><version>0.99.0</version>
  </dependency></dependencies>
</project>
XML
mvn -q dependency:build-classpath -Dmdep.outputFile=classpath.txt
```

#### Save as Hello.java

```java
import com.google.api.gax.core.NoCredentialsProvider;
import com.google.api.gax.grpc.GrpcTransportChannel;
import com.google.api.gax.rpc.FixedTransportChannelProvider;
import com.google.cloud.run.v2.*;
import io.grpc.ManagedChannelBuilder;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var host = Objects.requireNonNull(System.getenv("CLOUD_RUN_EMULATOR_HOST"));
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var channel = ManagedChannelBuilder.forTarget(host).usePlaintext().build();
    var settings = ServicesSettings.newBuilder()
        .setTransportChannelProvider(FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel)))
        .setCredentialsProvider(NoCredentialsProvider.create()).build();
    try (var client = ServicesClient.create(settings)) {
      for (var service : client.listServices("projects/" + project + "/locations/us-central1").iterateAll()) {
        System.out.println(service.getName());
      }
    } finally {
      channel.shutdownNow();
    }
  }
}
```

#### Run the example

```bash
java --class-path "$(cat classpath.txt)" Hello.java
```

#### Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check `localcloud status --verbose`, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

## Documented workflows

- ### Service/revision metadata

    Create or update a service and poll its long-running operation. Read back revision metadata and inspect failures before using the returned service endpoint.

- ### Docker container execution on service create/update

    Give LocalCloud Docker access, deploy an application image, and call the local HTTP endpoint. Assert response content and test how deployment code handles a failed container launch.

## Service boundaries

- Requires Docker runtime access
- No jobs, domain mappings, or full revision traffic splitting

## Code examples and integrations

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Agent testing

## Use Cloud Run with an AI agent

Before the agent changes application logic, have it create local Cloud Run state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

### Configure this repo

```
Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.
```

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

[Agent resources](https://local.cloud/ai/) has more prompts and the AGENTS.md template.

## Related guides

- [Compatibility](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Official Cloud Run documentation](https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run): service concepts and cloud usage.