Single/Double Container Mode

About 539 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 mode: the development environment and code-server run in one container.
Double container mode: the two run in separate containers, with a shared workspace (/workspace) directory.

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

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):

Double Container Mode

When the development environment container has no code-server, the system starts an additional code-server container to provide the code service — this is double container mode. The two containers share the workspace (/workspace) directory.

The following two methods will start in double container mode:

.cnb.yml
# Method 1: use a Docker image without code-server
$:
  vscode:
    - docker:
        image: node:22
      services:
        - vscode
        - docker
      stages:
        - name: ls
          script: ls -al

.ide/Dockerfile
# 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-8

In both cases the dev container lacks code-server, so the system automatically adds that container, forming double container mode.

Double Container Mode — Cross-Container Terminal

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.

Double Container Mode — 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).

Single/Double Container Mode​