Projects get isolated runtimes by default. Call awsEmulator.useSharedRuntime(":local-aws", "application") to select another project in the same build as the runtime owner and use its named resource set. This lets an API and a worker communicate through the same queues or tables.

Define The Owner

Include local-aws and the application projects in your settings file. Make the core plugin available in the root build so sharing projects use the same plugin classes, including when some apply the Spring Boot companion:

Root build.gradle.kts
plugins {
    id("io.github.gregwhitaker.aws-emulator") version "0.3.0" apply false
}

This resolves the core plugin from the Gradle Plugin Portal. In Groovy, the root declaration is id 'io.github.gregwhitaker.aws-emulator' version '0.3.0' apply false. Use the same release version for the Spring Boot companion when it is applied. Subprojects omit the core plugin version because the root declaration supplies it. The owner then applies the core plugin and declares its runtime settings and reusable resource sets in its own build script:

local-aws/build.gradle.kts
import io.github.gregwhitaker.awsemulator.aws.sqs.CreateSqsQueueTask

plugins { id("io.github.gregwhitaker.aws-emulator") }

awsEmulator {
    val application = resourceSets.register("application") {
        provision("ordersQueue", CreateSqsQueueTask::class.java) {
            queueName.set("orders")
        }
    }
    scenarios { register("default") { resources(application) } }
}

The owner can be a dedicated infrastructure project or an existing application or root project. It need not apply Java or have consumers of its own.

Select It In Each Application

Apply the core plugin or Spring Boot companion in each participating application, then select the owner:

Kotlin DSL
awsEmulator {
    useSharedRuntime(":local-aws", "application")
    useWith(tasks.named<Test>("test"))
    useWith(tasks.named<JavaExec>("run"))
}
Groovy DSL
awsEmulator {
    useSharedRuntime(':local-aws', 'application')
    useWith(tasks.named('test'))
    useWith(tasks.named('run'))
}

These snippets assume existing test and run tasks. useSharedRuntime selects the runtime but does not opt ordinary tasks into it. Use useWith for Test and JavaExec; the Spring Boot companion already attaches its bootRunLocal and bootRunLocalDebug tasks.

Owner selection also applies to resource and lifecycle tasks in the consumer project. It works before or after useWith, including consumers already realized during configuration. Local resource sets and explicit setup dependencies can still be attached through useWith.

The owner supplies the complete named runtime namespace. Declare names in the owner and select them in applications, for example useWith(tasks.named<Test>("test"), "integration") or springBoot { runtimeName.set("development") }. Consumer runtime definitions and settings are ignored. Lifecycle aliases in consumers select the corresponding owner runtime. Consumer aliases are created on request by a task rule; use the owner’s tasks --all output to list its named lifecycle tasks.

Resource Setup And Modes

An owner can select an external connection. Configure awsEmulator.external in the owner; all consumers use its endpoint and files. In this case both modes share the same external state and no lifecycle cleanup occurs.

The optional names select resource sets declared in the owner. For example, useSharedRuntime(":local-aws", "application", "fixtures") selects two sets; useSharedRuntime(":local-aws") shares just the runtime. Repeated calls for the same owner add names without duplicating setup.

Each selected set’s provisioning and fixtures run in the owner’s project, once per runtime name and mode per Gradle invocation, before all attached JVM consumers. Their usual ordering and includes apply. Unselected sets are not realized. Subsequent invocations rerun resource operations, including with configuration-cache reuse; fixture steps can therefore add data to a persistent instance again.

  • Managed consumers across the participating projects selecting the same name share one fresh managed instance per invocation. Cleanup waits for all participating tasks, including failure handling.

  • Development consumers share the owner’s persistent instance across invocations. It stays running until explicitly stopped.

  • With an owned runtime, managed and development modes remain separate, even when selected together. Automatic port selection is the default, so both can run simultaneously.

  • Spring Boot local tasks automatically receive the shared sets in awsEmulator.springBoot.mode. This explicit selection is independent of autoCreateResources; automatic discovery still considers only local resource tasks.

Sharing does not order application consumers or isolate their data. Declare task dependencies for a finite publisher/consumer workflow, or coordinate long-running applications yourself. Concurrent tests that require independent data should use distinct resource names or keep separate runtime owners.

Configuration And Lifecycle Ownership

The selected owner’s emulator version, Docker image, platform, port, region, telemetry, memory, timeouts, and working directory are authoritative. These runtime settings in consumers are ignored. Connection settings and TLS files are still resolved during execution for each consumer; the Gradle daemon’s credentials and global TLS configuration are unchanged.

Prefer fully qualified lifecycle commands on the owner:

./gradlew :local-aws:statusAwsEmulator
./gradlew :local-aws:seedAwsEmulator
./gradlew :local-aws:resetAwsEmulator
./gradlew :local-aws:stopAwsEmulator

Lifecycle tasks in a sharing consumer also target the shared runtime. Stopping, restarting, or resetting it affects every application using that development instance. Scenario definitions remain project-local: define shared development scenarios in the owner and invoke its scenario commands.

The owner path must be absolute, such as :local-aws or : for the root, and identify a project in the same build with the core plugin applied. Owner metadata is resolved when a participating task is selected. Owner chains, cycles, selecting oneself, and switching to a different owner are rejected. Unknown runtime and resource names fail while resolving consumer dependencies, before Docker starts. Sharing across included builds is not supported.

Gradle Isolated Projects

Default, named, external, and shared runtimes support Isolated Projects, including resource sets, scenarios, parallel project configuration, and configuration-cache reuse. With the repository’s Gradle 8.14.3 wrapper, run:

./gradlew -p examples/multi-project verifySharedRuntime --parallel -Dorg.gradle.unsafe.isolated-projects=true
./gradlew -p examples/multi-project verifySharedRuntime --parallel -Dorg.gradle.unsafe.isolated-projects=true

For Gradle 8.14–9.6, the equivalent gradle.properties setting is org.gradle.unsafe.isolated-projects=true. Gradle 9.7+ uses org.gradle.isolated-projects=true or --isolated-projects. Isolation enables the configuration cache; repeat the same command to verify reuse. See Gradle’s Isolated Projects documentation.

Configure each project’s plugins, runtimes, resources, and consumers in its own build script or a convention plugin. Pass the owner’s absolute project path and resource-set names to useSharedRuntime; do not read another project’s extension or task container. For ordinary dependencies between applications, use task paths such as dependsOn(":orders-api:run").

The plugin exchanges immutable owner metadata through a project dependency and attaches owner setup by task path. Changes to owner settings invalidate affected configuration-cache entries. Unselected resource sets remain lazy, and configuration does not start Docker or read connection credentials. Shared managed instances retain their usual cleanup after all participating consumers finish, including failures.

The Spring Boot companion’s local tasks and resource wiring support isolation. The upstream Spring Boot plugin has a separate limitation in multi-project builds when packaging tasks are realized, including indirectly by tests.

Run The Multi-Project Example

The multi-project example contains local-aws, orders-api, and orders-worker. Both modules have tests; separate finite application processes publish and consume an order through the shared queue.

./gradlew -p examples/multi-project verifySharedRuntime --parallel --configuration-cache
./gradlew -p examples/multi-project verifySharedRuntime --parallel --configuration-cache
./gradlew -p examples/multi-project :orders-worker:run -Pdevelopment=true
./gradlew -p examples/multi-project :local-aws:stopAwsEmulator

The first two commands verify managed sharing and configuration-cache reuse. The development command leaves the shared instance running. See the example README for failure-cleanup commands.