Single/Double Container Mode
About 537 wordsAbout 2 min
Single/Double Container Mode explains the difference between the two launch modes and when each is used.
When to use: when a custom image is missing tools you expect, or when plugin features misbehave — check which mode you are in, then decide whether to install code-server into the image.
Cloud-native development supports two launch modes — single container and double container — explained below along with the conditions and limitations of each.
Development Environment: the environment provided by .ide/Dockerfile, a custom image, or the default CNB container, with pre-installed or user-installed software.
Single Container Mode
The development environment and code-server run in one container.
Single container mode is recommended. The following methods start in single container mode.
Starting with Default Configuration
When no configuration is set (i.e., no startup pipeline and .ide/Dockerfile), the development environment starts with default configuration. The default environment has code-server and ssh installed, so it uses single container mode, supporting both WebIDE and VSCode remote development. See Default Development Environment for details.
Starting with Custom Configuration
When a startup pipeline or .ide/Dockerfile is configured and the image has code-server installed, single container mode is used. The following three methods all start in single container mode (all launch images have code-server installed):
- Customizing both development environment and startup process
- Customizing development environment via Dockerfile
- Specifying development environment via Docker image
Double Container Mode
The development environment and code-server run in separate containers, with a shared workspace (/workspace) directory. When the development environment container has no code-server, the system starts an additional code-server container to provide the code service. The following two methods will start in double container mode:
# Method 1: use a Docker image without code-server
$:
vscode:
- docker:
image: node:22
services:
- vscode
- docker
stages:
- name: ls
script: ls -al# Method 2: use a custom Dockerfile without code-server
FROM node:20
RUN apt-get update && apt-get install -y git wget unzip openssh-server
ENV LANG C.UTF-8
ENV LANGUAGE C.UTF-8In both cases the dev container lacks code-server, so the system automatically adds that container, forming double container mode.
Cross-Container Terminal
This is only needed in double container mode: WebIDE or VSCode actually connects to the code-server container. To reach the development environment container, use the cross-container terminal — the default terminal (named CNB) connects to the development environment.
If the development environment container doesn't support git, switch to a non-CNB terminal to use the built-in code-server terminal for git operations.
Plugin Capability Limitations
In double container mode, VSCode plugins are installed in the code-server container and may not be able to access the development environment container (such as Debug and other features that require access to it).