1. Help Center
  2. Testcontainers Cloud for CI

How to connect to a cloud worker for troubleshooting?

For advanced troubleshooting use cases, it can be useful to connect to a Testcontainers Cloud worker from your machine. This article describes how.

1. Obtain the "Worker ID"

By navigating to dashboards, it's possible to see "live sessions" for which cloud workers are available. By hovering over the card and clicking on the "kebab menu" (the 3 dots) it's possible to copy the "Worker ID" to the clipboard.


2. Download the CI agent and make it executable

The connect feature is part of the Testcontainers Cloud binary. If you don't already have the agent, you can download it from the install page or directly at https://get.testcontainers.cloud/bash.

curl -o tcc-agent -L https://app.testcontainers.cloud/download/testcontainers-cloud-agent_next_darwin_arm64
chmod +x tcc-agent

3. Connect to the cloud worker

In a terminal window, use the agen'ts `connect` method with the Worker ID as parameter:

./tcc-agent connect <worker-id>

Assuming that you run Testcontainers Desktop and are signed-in, the Testcontainers Cloud agent should automatically reuse the authentication token and no further step is required. If that's not the case, see the next section.

4. (optional) Provide a Testcontainers Cloud authentication token

If you'd like to pass the token manually, you can either set the `TC_CLOUD_TOKEN` environment variable or provide it as a command line argument:

./tcc-agent --token <token> connect <worker-id>