Testcontainers Cloud: Run Containers Remotely in CI Without Docker

Testcontainers Cloud: Run Containers Remotely in CI Without Docker

Testcontainers works beautifully when Docker is available. But in many CI environments — serverless runners, sandboxed agents, resource-constrained pipelines — Docker either is not installed, requires privileged mode, or competes with the test process for CPU and memory. Testcontainers Cloud solves this by running your containers on a remote daemon while your tests continue to run locally in the CI process.

What Is Testcontainers Cloud?

Testcontainers Cloud (TCC) is an AtomicJar/Docker-maintained service that provides an on-demand, remote Docker environment. When you enable TCC, the Testcontainers library connects to a remote daemon instead of the local Docker socket. Your test code is unchanged — you still call new PostgreSQLContainer<>() or new KafkaContainer() — but the containers run in the cloud, not on the CI agent.

The test process runs locally. Container ports are forwarded back to localhost so your code can connect to localhost:5432 just as if PostgreSQL were running on the same machine.

Key Benefits Over Local Docker

Local Docker Testcontainers Cloud
Docker required on CI agent Yes No
Memory contention Yes (containers + JVM/Python/Node) No (containers are remote)
Parallel container starts Slow (shared CPU) Fast (dedicated remote capacity)
Works on serverless runners No Yes
Works on macOS GitHub Actions Requires extra setup Yes, out of the box
Cost Free Paid (free tier available)

The biggest practical benefit is that your CI agent can be smaller and cheaper. The heavy Docker work happens on Testcontainers Cloud infrastructure, not on the runner paying by the minute.

Getting Started

1. Create an Account

Sign up at testcontainers.cloud. You will receive a service token.

2. Install the Agent (for local use)

For local development, install the TCC agent which handles the connection to the remote daemon:

# macOS
brew install testcontainers/tap/testcontainers-cloud-agent

# Linux
curl -fsSL https://get.testcontainers.cloud | bash

Start it:

testcontainers-cloud agent start

The agent authenticates using your token and creates a local proxy that Testcontainers connects through.

3. Configure CI

In CI, set the service token as an environment variable and use the TCC GitHub Action:

# .github/workflows/integration-tests.yml
name: Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Testcontainers Cloud
        uses: atomicjar/testcontainers-cloud-setup-action@v1
        with:
          token: ${{ secrets.TC_CLOUD_TOKEN }}

      - uses: actions/setup-java@v4
        with:
          java-version: "21"
          distribution: temurin

      - run: ./mvnw test

No Docker daemon configuration changes needed. The action sets TESTCONTAINERS_HOST_OVERRIDE and other environment variables that Testcontainers reads automatically.

For non-Java projects:

# Python
- name: Set up Testcontainers Cloud
  uses: atomicjar/testcontainers-cloud-setup-action@v1
  with:
    token: ${{ secrets.TC_CLOUD_TOKEN }}

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"

- run: pip install -r requirements.txt && pytest
# Node.js
- name: Set up Testcontainers Cloud
  uses: atomicjar/testcontainers-cloud-setup-action@v1
  with:
    token: ${{ secrets.TC_CLOUD_TOKEN }}

- uses: actions/setup-node@v4
  with:
    node-version: "20"

- run: npm ci && npm test

Your Test Code Does Not Change

This is the core promise of Testcontainers Cloud: zero test-code changes. If you have this:

@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
    .withDatabaseName("testdb");

It works as-is with TCC. The library detects the remote daemon from the environment and routes container operations there. Connection strings, mapped ports, and log streaming all work identically.

Parallel Containers and Turbo Mode

One of the biggest wins with TCC is parallel container startup. Locally, starting four containers simultaneously means all four compete for the same Docker daemon, CPU, and memory. On TCC, each container request goes to a remote environment with dedicated resources.

Enable Turbo Mode in the TCC dashboard to pre-warm a pool of container environments. When your test suite starts, pre-warmed environments are assigned instantly — no cold-start overhead for the first set of containers.

Measure the difference:

# Local: sequential startup
[00:00] Starting postgres...    8s
[00:08] Starting redis...       4s
[00:12] Starting kafka...       15s
[00:27] Tests begin

# TCC with Turbo Mode: parallel startup
[00:00] Starting postgres...  \
[00:00] Starting redis...      | all parallel, remote
[00:00] Starting kafka...     /
[00:06] Tests begin            (limited by slowest container, not sum)

Using TCC on GitLab CI

integration-tests:
  image: eclipse-temurin:21
  variables:
    TC_CLOUD_TOKEN: $TC_CLOUD_TOKEN  # set in GitLab CI/CD settings
  before_script:
    - curl -fsSL https://get.testcontainers.cloud | bash
    - testcontainers-cloud agent start --background
  script:
    - ./mvnw test -Dgroups=integration

Scoped Access Tokens

TCC supports scoped tokens — you can create separate tokens per team or per repository and revoke them independently. Tokens are read at runtime from the TC_CLOUD_TOKEN environment variable, so rotating a token is a CI secrets change, not a code change.

When to Stick with Local Docker

TCC is not always the right choice:

  • Local development with fast machines: if your laptop has 32 GB RAM and Docker Desktop is fast, local Docker is zero-cost and equally fast
  • Simple test suites: if you only start one container and your CI agent is a large runner, the TCC round-trip may not be faster than local Docker startup
  • Air-gapped environments: TCC requires outbound HTTPS to the TCC service; if your CI is isolated, local Docker is the only option

TCC pays off most on:

  • Resource-constrained runners (2-core, 7 GB)
  • Large test suites starting many containers
  • Environments where Docker cannot be installed (serverless, restricted corporate CI)
  • Teams that want to standardise on a Docker-free agent image

Debugging Container Issues in TCC

Container logs are streamed back to your test process exactly as they are locally. If your container fails to start, container.getLogs() returns the remote container's output. The TESTCONTAINERS_CLOUD_LOGS=true environment variable adds verbose TCC connection and proxy logs to help diagnose connectivity issues.

Closing Thoughts

Testcontainers Cloud removes the last remaining friction point for teams who want real-infrastructure tests but cannot easily install or run Docker on their CI agents. Your test code stays clean, CI agents stay lightweight, and containers start faster thanks to remote capacity and Turbo Mode.

Once your containers are in the cloud, your test outcomes should be too. HelpMeTest provides 24/7 monitoring so your real services are continuously tested in production — not just on every pull request.

Read more

Start now free