Skip to main content

​
What is debug mode?

Debug mode lets you deploy a separate instance of your container with SSH access and logging enabled. This gives you a way to inspect the enclave runtime, troubleshoot startup issues, and test configuration changes — without affecting your production container.

​
When to use debug mode

  • Container startup failures: SSH in to check why your application isn’t starting
  • Configuration issues: Verify that environment variables and secrets are set correctly
  • Runtime debugging: Inspect processes, network, and filesystem inside the enclave
  • Testing changes: Validate a new config or image is working as expected before deploying to production

​
How it works

Debug containers are fully independent instances. They run on a separate domain and have their own lifecycle, so you can deploy, update, and delete them without touching production instances.
Debug containers do not pass attestation. Tinfoil’s SecureClient will refuse to connect to a debug instance because debug enclaves are not confidential. This is by design as debug mode trades confidentiality for inspectability. Never inject production secrets or send production or otherwise sensitive data to a debug container.
A container named api can have both a production and a debug instance running simultaneously.

​
Deploying a debug container

  1. In the All Containers tab, click New Container
  2. Toggle Debug Mode on
  3. Select one or more SSH keys from your organization’s key list (see below)
  4. Configure the rest of the container as normal
  5. Click Deploy Container

​
Managing SSH keys

Before deploying a debug container, add your SSH public keys to the organization.

​
Adding keys

  1. Go to the SSH Keys tab in the Containers section
  2. Click Add SSH Key
  3. Paste your public key

​
Connecting via SSH

Once your debug container is running, the dashboard shows the SSH connection command on the container’s card. It looks like:
This opens the Tinfoil Containers debug toolbox inside the enclave. The toolbox can inspect and enter your workload containers, read their logs, and restart the debug deployment with an edited configuration.

​
Using the debug toolbox

The toolbox workflow below is available with CVM image 0.11.0 and later.
The shell starts in a home directory containing README.md, with a concise command reference, and AGENTS.md, with instructions for coding agents. Both vi and vim are available for editing files. Start by checking the deployment and its containers:
If the workload image has Bash but no sh, use bash. Omit -it when running a noninteractive command.

​
Add a temporary SSH key from the toolbox

After connecting with an existing authorized key, you can grant another developer temporary access without restarting the toolbox. Add their public key to the toolbox’s authorized_keys file:
The new key works immediately.

​
Try a configuration change

The initial deployment configuration is copied to ~/tinfoil-config.debug.yml. Edit that file, then boot the debug runtime again:
tindbg boot replaces and restarts the workload containers. Expect a brief interruption to the debug instance. The toolbox remains available so you can fix the configuration and retry if the boot fails. To discard your edits and restore the configuration used to create the debug instance:

​
Run additional diagnostic tools

The toolbox itself is read-only and does not support apt install. Run a disposable container instead. Its container layer is writable, so you can install packages and experiment without modifying the toolbox:
The --rm flag deletes the diagnostic container and all installed packages when you exit. Omit --rm and add --name debug-tools if you want to stop and resume the same temporary environment:
To use tools in the same network namespace as a workload:
For a GPU diagnostic, launch a temporary CUDA container:
The toolbox has direct Docker access to the workload containers in this debug instance. Commands such as docker stop, docker rm, and tindbg boot can interrupt or replace them.

​
Promoting to production

Once you’ve finished testing with a debug container, you can deploy it as a production enclave directly from the dashboard:
  1. On the debug container, click Update
  2. In the modal, select Deploy to prod
  3. The container deploys as a production enclave with the same configuration but with debug access and logging disabled
For CPU-only and single-GPU instances, this uses a blue-green deployment and the debug container keeps running until the production instance is ready. An 8-GPU conversion is disruptive because the old instance must be removed before the production replacement can start.

​
Using the CLI

The Tinfoil CLI handles the SSH key registry and the debug-mode deploy:
When two containers share a name (one debug, one production), --debug-mode selects the debug container. You can also use its UUID.