# Cloud Scheduler

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

Cloud Scheduler runs jobs on a cron schedule. It triggers HTTP endpoints or messaging targets for recurring application work.

## Typical uses

Use when work must recur on a cron schedule in a chosen time zone, with an HTTP endpoint or messaging target receiving each scheduled trigger.

Examples

- Scheduled reports and maintenance
- Recurring HTTP or Pub/Sub triggers

Connection

Environment variable

`CLOUD_SCHEDULER_EMULATOR_HOST=localhost:5380`

Runtime details

- **Endpoints:** gRPC + HTTP/REST :5380
- **Minimum tier:** Community
- **Restart behavior:** Kept across restarts

## Example usage

Service ID: `cloudscheduler`. Starts by default. Requires a running LocalCloud runtime.

Export these variables in the process that runs your tests, then use the client settings below. [First-time setup](https://local.cloud/docs/)

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

REST gateway examples use the generated HTTP address in `SERVICE_USAGE_EMULATOR_HOST`; native SDKs can use a different protocol.

Java · REST:

### Java · REST

### List scheduled jobs

List scheduled jobs; Cloud Scheduler triggers recurring application work on a cron schedule.

Call the Google Cloud REST API with the JDK HTTP client. Requires JDK 17+. Results reflect resources already created in your local project.

Read-only: lists what already exists and creates nothing.

#### Save as Hello.java

```java
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var endpoint = Objects.requireNonNull(System.getenv("SERVICE_USAGE_EMULATOR_HOST"));
    var url = URI.create(endpoint.replaceAll("/+$", "") + "/v1/projects/" + project + "/locations/us-central1/jobs");
    var request = HttpRequest.newBuilder(url).timeout(Duration.ofSeconds(30)).GET().build();
    var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 400) {
      throw new IllegalStateException(response.statusCode() + ": " + response.body());
    }
    System.out.println(response.body());
  }
}
```

#### Run the example

```bash
java Hello.java
```

#### Verify the result

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

gcloud CLI:

### gcloud CLI

### List scheduled jobs

List scheduled jobs; Cloud Scheduler triggers recurring application work on a cron schedule.

Use the Google Cloud CLI against the local gateway in its default open IAM mode. Run these exports in a terminal dedicated to local development.

Read-only: lists what already exists and creates nothing.

#### Configure gcloud CLI

```bash
: "${SERVICE_USAGE_EMULATOR_HOST:?Export the LocalCloud environment first}"
export CLOUDSDK_CORE_PROJECT="${GOOGLE_CLOUD_PROJECT:?Export the LocalCloud environment first}"
export CLOUDSDK_AUTH_DISABLE_CREDENTIALS=true
export CLOUDSDK_API_ENDPOINT_OVERRIDES_CLOUDSCHEDULER="${SERVICE_USAGE_EMULATOR_HOST%/}/"
```

#### Run in your terminal

```bash
gcloud scheduler jobs list --location=us-central1
```

#### Verify the result

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

## Clean up test state

Create test data, run the operation, read it back, and delete only what the test created, even after a failure.

If a call reaches Google Cloud instead of localhost, check the exported endpoint variables. For connection failures, run `localcloud status --verbose` and confirm the service is enabled.

## Workflows you can test

- ### Job CRUD, pause/resume, and manual runs

    Create a job with a local target, pause and resume it, and request a manual run. Inspect the resulting job and attempt state before deleting the fixture.

- ### Timezone-aware cron and schedule previews

    Configure a cron expression and timezone, then inspect the next-run preview. Choose a short test schedule and compare observed trigger times with the expected local schedule.

- ### HTTP/Pub/Sub delivery, retries, deadlines, and attempt history

    Point an HTTP job at a test receiver or a Pub/Sub job at a local topic. Introduce a failure and inspect retries, deadlines, and attempt history.

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

    Configure an OAuth or OIDC credential on an HTTP job and verify the token at the receiver. Trust the LocalCloud issuer and JWKS for this local delivery test.

## Limits to plan around

- Authenticated receivers verify tokens against the local issuer and JWKS. App Engine targets: use Google Cloud
- Interrupted attempts aren't replayed, and a job that came due while LocalCloud was stopped runs once without backfilling the rest; validate catch-up behavior in Google Cloud
- Strict mode checks the gateway access policy, not Google IAM roles on jobs; validate authorization in Google Cloud

## 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 Scheduler with an AI agent

Before the agent changes application logic, have it create local Cloud Scheduler 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.

See [Agent resources](https://local.cloud/ai/) for 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 Scheduler documentation](https://docs.cloud.google.com/scheduler/docs/overview): service concepts and cloud usage.
