# How to: Use Docker Remote Contexts with SSH

> A simple and secure guide to configuring SSH-based Docker remote contexts for offloading resource-intensive Docker operations to a remote host while keeping your local environment lightweight.

- Published: 2025-10-10
- Author: Sven Scharmentke
- Canonical: https://svnscha.de/posts/docker-remote-context/
- Tags: docker, devops, remote-development, ssh

---

## The Problem: When Your Laptop Becomes a Jet Engine

Working on resource-intensive Docker projects often turns laptops into jet engines. The fans spin up, the CPU overheats, and performance degrades significantly. This is especially problematic when working with limited resources - lightweight laptops, VDI sessions, or simply wanting to preserve your hardware.

An SSH-based Docker context keeps the development tools on your local machine while running Docker workloads on a more capable remote host. Your laptop stays responsive and the remote system handles the heavier work.

## Step 1: Prerequisites

Before we start, ensure you have:

1. **SSH access configured** to your remote Docker host with a proper SSH config entry like:

```
# ~/.ssh/config
Host docker-remote
  HostName 10.10.10.10
  IdentityFile ~/.ssh/id_rsa
  User ubuntu
```

2. **Your user is in the docker group** on the remote host:

```bash
sudo usermod -aG docker $USER
```

That's all the setup needed! Now let's create the Docker context.

## Step 2: Create the SSH-Based Docker Context

Creating the Docker context is incredibly simple when you have SSH properly configured.

### Create Your SSH-Based Remote Context

Create a new context using your SSH config host:

```bash
docker context create docker-remote --docker host=ssh://docker-remote
```

That's it! Docker will use your existing SSH configuration, including the hostname, user, and identity file you've already set up.

**The beauty of this approach:** No daemon.json changes, no TCP configuration, no port forwarding, no firewall rules, no TLS certificate generation - just leverage your existing SSH security infrastructure. Simple and elegant!

### Check Your Current Contexts

First, let's see what contexts you currently have:

```bash
docker context ls
```

You'll probably see something like:

```
NAME              DESCRIPTION                               DOCKER ENDPOINT
default *         Current DOCKER_HOST based configuration   npipe:////./pipe/docker_engine
desktop-linux     Docker Desktop                            npipe:////./pipe/dockerDesktopLinuxEngine
desktop-windows   Docker Desktop                            npipe:////./pipe/dockerDesktopWindowsEngine
docker-remote                                               ssh://docker-remote
```

### Test the Connection

Let's verify everything works:

```bash
docker --context docker-remote container ls
```

If you see your remote containers listed (or an empty list if none are running), congratulations! You're successfully connected to your remote Docker host via SSH.

## Step 3: Make It Your Default (Optional)

If you want to use the remote context by default, you can switch to it:

```bash
docker context use docker-remote
```

Now all your `docker` commands will automatically use the remote host:

```bash
docker container ls
# This now runs on your remote host!
```

### Environment Variable Override

For more granular control, you can also use the `DOCKER_CONTEXT` environment variable:

```bash
# Windows PowerShell
$env:DOCKER_CONTEXT = "docker-remote"

# Linux/macOS
export DOCKER_CONTEXT=docker-remote
```

This approach is particularly useful in CI/CD scenarios or when you want different shells to use different contexts.

## Why SSH is Better

Using SSH for Docker remote contexts offers several advantages over TCP:

- **Security**: All communication is encrypted by default
- **Authentication**: Leverages existing SSH keys and authentication methods  
- **No daemon configuration**: No need to modify Docker daemon settings on the remote host
- **Firewall friendly**: Uses standard SSH port (22)
- **Audit trail**: SSH logging provides better security monitoring

## Switching Between Contexts

Need to switch back to local Docker for something? Easy:

```bash
# List available contexts
docker context ls

# Switch to local Docker
docker context use default

# Or use a specific context for one command
docker --context default container ls
```

## Bonus: PowerShell Function for Quick Context Switching

Here's a handy PowerShell function to make switching contexts even easier. Add this to your PowerShell profile for instant remote Docker activation:

### Edit Your PowerShell Profile

First, open your PowerShell profile for editing:

```powershell
notepad $PROFILE
```

If the file doesn't exist yet, PowerShell will ask if you want to create it - say yes.

### Add the Function

Add this function to your profile:

```powershell
function docker-remote-activate {
    $env:DOCKER_CONTEXT = "docker-remote"
    Write-Host "Docker context switched to remote host"
}
```

Replace `"docker-remote"` with whatever you named your remote context.

### Save and Reload

Save the file and reload your PowerShell profile:

```powershell
. $PROFILE
```

### Usage

Now you can instantly activate remote Docker in any PowerShell session:

```powershell
# Activate remote Docker for this session only
docker-remote-activate

# Now all Docker commands run remotely
docker ps
docker images
docker build .
```

The beauty of this approach is that it only affects the current PowerShell session - open a new terminal window and you're back to local Docker by default!

### Global vs Terminal-Specific Context Switching

You have two ways to switch between local and remote Docker contexts:

#### Global Context Switching

Affects all terminals system-wide:

```bash
# Switch globally to remote
docker context use docker-remote

# Switch back to local
docker context use default
```

#### Terminal-Specific Context

Affects only the current terminal session:

```powershell
# Terminal 1: Remote context
docker-remote-activate
docker ps  # runs remotely

# Terminal 2: Still local context  
docker ps  # runs locally
```

Whether you prefer global context switching or terminal-specific control, Docker remote contexts give you the flexibility to work exactly how you want.

## Summary

Using SSH-based Docker remote contexts provides a secure, simple solution for offloading resource-intensive Docker operations to remote hosts. With just a single command and proper SSH configuration, you can transform your development workflow without compromising security.

The SSH approach eliminates the complexity of daemon configuration while providing enterprise-grade security through encrypted communication and existing authentication infrastructure.

**Key Benefits:**
- Secure by default (encrypted communication)
- No daemon configuration required  
- Uses standard SSH authentication
- Works with existing SSH infrastructure
- Simple one-command setup

**References:**
- [Docker Context Documentation](https://docs.docker.com/engine/manage-resources/contexts/)
- [Docker SSH Documentation](https://docs.docker.com/engine/context/remote/)
- [SSH Key Authentication](https://www.ssh.com/academy/ssh/public-key-authentication)