> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinfoil.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug mode

> Deploy debug instances of your Tinfoil Containers with SSH access for troubleshooting.

## 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.

|                    | Production                            | Debug                                       |
| ------------------ | ------------------------------------- | ------------------------------------------- |
| **Domain**         | `<name>.<org>.containers.tinfoil.dev` | `<name>.debug.<org>.containers.tinfoil.dev` |
| **SSH access**     | No                                    | Yes                                         |
| **Docker logging** | No                                    | Optional                                    |
| **Attestation**    | Yes                                   | No                                          |

<Warning>
  **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.
</Warning>

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:

```bash theme={"dark"}
ssh -p <port> root@console.tinfoil.sh
```

This gives you a shell inside the enclave where you can inspect running processes, check logs, verify environment variables, and debug your application.

## 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

This uses a blue-green deployment — the debug container keeps running until the production instance is ready.

## Using the CLI

The [Tinfoil CLI](/containers/cli) handles the SSH key registry and the debug-mode deploy:

```bash theme={"dark"}
# Register your public key (once per developer)
tinfoil ssh-key list
tinfoil ssh-key create laptop --public-key-file ~/.ssh/id_ed25519.pub

# Deploy a debug container (separate from any production container with the same name)
tinfoil container create my-api \
  --repo myorg/my-api-config \
  --tag v1.0.0 \
  --debug \
  --ssh-key laptop

# Promote the debug container to production
tinfoil container relaunch my-api --debug false --debug-mode
```

When two containers share a name (one debug, one production), `--debug-mode` selects the debug container. You can also use its UUID.