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

# Connect to Workloads

> Open an interactive shell session inside a running workload container.

The `cpln workload connect` command opens an interactive terminal session to a running container, similar to `docker exec -it` or `kubectl exec -it`. Use it to inspect container state, debug issues, or run commands interactively.

## When to use this

<CardGroup cols={2}>
  <Card title="Interactive debugging" icon="bug">
    Explore container filesystem, check processes, and inspect state
  </Card>

  <Card title="Troubleshooting" icon="wrench">
    Diagnose issues directly inside the running container
  </Card>

  <Card title="Manual operations" icon="terminal">
    Run one-off commands, database migrations, or maintenance tasks
  </Card>

  <Card title="Log inspection" icon="file-lines">
    View logs and files that aren't exposed externally
  </Card>
</CardGroup>

## Prerequisites

<AccordionGroup>
  <Accordion title="CLI installed">
    Install the Control Plane CLI. See [Installation](/cli-reference/installation).
  </Accordion>

  <Accordion title="Running workload">
    You need a running [workload](/reference/workload) in at least one location. See the [Create a Workload](/guides/create-workload) guide.
  </Accordion>

  <Accordion title="Required permissions">
    You need `exec` permission on the workload. See [Workload Permissions](/reference/workload#permissions).
  </Accordion>
</AccordionGroup>

## Connect via Console

You can connect to workloads directly from the Control Plane Console:

<Steps>
  <Step title="Navigate to workload">
    Open your workload in the Console.
  </Step>

  <Step title="Click Connect">
    In the left pane, click **Connect**.
  </Step>

  <Step title="Configure connection">
    Use the dropdowns to select:

    * **Location**: The deployment location to connect to
    * **Container**: The container within the workload
    * **Replica**: The specific replica instance
  </Step>

  <Step title="Enter command">
    Type the shell command to use (e.g., `bash`, `sh`, `node`).
  </Step>

  <Step title="Connect">
    Click **Connect** to open an interactive terminal session in your browser.
  </Step>
</Steps>

<Tip>
  You can copy the generated `cpln workload connect` command from the Console and paste it into your terminal to connect from the CLI instead.
</Tip>

## Connect via CLI

### Basic usage

```bash theme={null}
cpln workload connect <workload>
```

This opens a `bash` shell in the first available container and replica.

### Options

| Option        | Description                                               |
| ------------- | --------------------------------------------------------- |
| `--location`  | Target location (defaults to first available in GVC)      |
| `--replica`   | Target a specific replica (defaults to first replica)     |
| `--container` | Target a specific container (defaults to first container) |
| `--shell, -s` | Shell to use (default: `bash`)                            |

### Connect to a specific location

```bash theme={null}
cpln workload connect my-app --location aws-eu-central-1
```

<Tip>
  List available locations with `cpln workload get-deployments my-app`.
</Tip>

### Connect to a specific replica

When a workload has multiple replicas, target a specific one:

```bash theme={null}
# List replicas
cpln workload replica get my-app --location aws-eu-central-1

# Connect to a specific replica
cpln workload connect my-app --replica my-app-7f8d9c-abc12
```

### Connect to a specific container

For workloads with multiple containers (sidecars, init containers):

```bash theme={null}
cpln workload connect my-app --container sidecar
```

### Use a different shell

Some containers don't have `bash`. Use `sh` or another shell:

<Tabs>
  <Tab title="sh">
    ```bash theme={null}
    cpln workload connect my-app --shell sh
    ```
  </Tab>

  <Tab title="ash (Alpine)">
    ```bash theme={null}
    cpln workload connect my-app --shell ash
    ```
  </Tab>

  <Tab title="zsh">
    ```bash theme={null}
    cpln workload connect my-app --shell zsh
    ```
  </Tab>
</Tabs>

### Common workflows

#### Debug a crashing container

```bash theme={null}
# Connect and check logs
cpln workload connect my-app
cat /var/log/app.log

# Check processes
ps aux

# Check environment
env | grep -i config
```

#### Inspect database state

```bash theme={null}
cpln workload connect postgres-db --shell sh

# Inside the container
psql -U postgres -c "SELECT * FROM users LIMIT 10;"
```

#### Check filesystem

```bash theme={null}
cpln workload connect my-app

# Check disk usage
df -h

# Find large files
du -sh /app/*
```

#### Run a migration

```bash theme={null}
cpln workload connect my-app

# Run database migration for example
npm run migrate
# or
python manage.py migrate
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="bash: not found">
    The container doesn't have bash. Use a different shell:

    ```bash theme={null}
    cpln workload connect my-app --shell sh
    ```

    Alpine-based images typically use `ash` or `sh`.
  </Accordion>

  <Accordion title="No replicas found">
    The workload may not be running:

    ```bash theme={null}
    cpln workload get my-app
    cpln workload replica get my-app
    ```

    Wait for replicas to start or check the workload configuration.
  </Accordion>

  <Accordion title="Connection closed immediately">
    The shell may be exiting. Try with a different shell or check container health:

    ```bash theme={null}
    cpln workload get-deployments my-app
    ```
  </Accordion>

  <Accordion title="Permission denied">
    You need `exec` permission on the workload. Check your policies or contact your admin.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Execute Commands" href="/guides/cli/workload/exec" icon="terminal">
    Run non-interactive commands
  </Card>

  <Card title="Copy Files" href="/guides/cli/cpln-cp" icon="copy">
    Transfer files to/from workloads
  </Card>

  <Card title="Port Forwarding" href="/guides/cli/cpln-port-forward" icon="network-wired">
    Access workload ports locally
  </Card>

  <Card title="Command Reference" href="/cli-reference/commands/workload#workload-connect" icon="book">
    Full connect command reference
  </Card>
</CardGroup>