# Cloud Tasks

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

Cloud Tasks queues work for later delivery to a handler. Rate limits, retries, and scheduling help control how background requests reach application workers.

## Typical uses

Use when a known handler should process queued work with controlled dispatch rates, scheduled delivery, and per-task retry behavior.

Examples

- Deferred HTTP work
- Rate-limited background processing

Connection

Environment variable

`CLOUD_TASKS_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC :5380
- **Minimum tier:** Community
- **Persistence:** service-data
- **Implementation:** Local Facade

## Example usage

Service ID: `cloudtasks`. Starts by default. 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_TASKS_EMULATOR_HOST
eval "$(localcloud env)"
```

Java:

### Java

### List local task queues

List the queues that hold deferred work; Cloud Tasks controls how requests reach your background handlers.

Use the Cloud Tasks 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-tasks</artifactId><version>2.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.tasks.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_TASKS_EMULATOR_HOST"));
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var channel = ManagedChannelBuilder.forTarget(host).usePlaintext().build();
    var settings = CloudTasksSettings.newBuilder()
        .setTransportChannelProvider(FixedTransportChannelProvider.create(GrpcTransportChannel.create(channel)))
        .setCredentialsProvider(NoCredentialsProvider.create()).build();
    try (var client = CloudTasksClient.create(settings)) {
      for (var queue : client.listQueues("projects/" + project + "/locations/us-central1").iterateAll()) {
        System.out.println(queue.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

- ### Queue lifecycle, pause/resume, purge, and HTTP target overrides

    Create a queue, change dispatch settings, and configure HTTP target URI, method, or header overrides. Check delivered requests, then pause, resume, or purge the queue for the next test run.

- ### Task CRUD, BufferTask, and manual/automatic HTTP dispatch

    Create an HTTP task or POST a raw body through BufferTask on a queue with an HTTP target host. Trigger dispatch and assert the received body, delivery headers, and observed response.

- ### Rate/concurrency limits, deadlines, retries, and attempt history

    Make the handler fail or exceed a deadline, then inspect attempt history and retry timing. Test rate and concurrency settings with enough tasks to observe their effect.

- ### HTTP delivery with locally issued OAuth/OIDC credentials

    Set a task OAuth or OIDC credential and have the receiver verify the local token. Exercise queue-level credential overrides separately from the task-level configuration.

## Service boundaries

- No App Engine dispatch or logging sampling; queue target overrides need exact-image validation
- Authenticated receivers must trust the local issuer/JWKS
- Restart can redeliver; pause, purge, and delete cannot cancel in-flight requests. Inspect attempts before replaying

## Code examples and integrations

- [Provision resources with Terraform](https://local.cloud/docs/terraform/#supported-terraform-resources): Documented resources, provider configuration, and local routing setup.
- [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 Tasks with an AI agent

Before the agent changes application logic, have it create local Cloud Tasks 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 Tasks documentation](https://docs.cloud.google.com/tasks/docs/dual-overview): service concepts and cloud usage.