---
url: /en/workspaces/double-container.md
description: >
  Explains the difference between single-container mode (development environment
  and code-server in one container) and double-container mode (in separate
  containers) for Workspaces, and describes when each mode is used.
---
Cloud-native development supports two launch modes:

* **Single Container Mode**: Development environment and `code-server` run in the same container
* **Double Container Mode**: Development environment and `code-server` run in
  separate containers, with shared workspace (`/workspace`) directory

**Development Environment**: A container specified via `.ide/Dockerfile` or a custom image,
or the default CNB container environment, containing user-installed or pre-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](./default-dev-env.md) for details.

### Starting with Custom Configuration

When a startup pipeline or `.ide/Dockerfile` is configured,
and the custom image or `.ide/Dockerfile` 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):

* [Specifying development environment via Docker
  image](./custom-dev-env.md#specifying-development-environment-via-docker-image)
* [Customizing development environment via
  Dockerfile](./custom-dev-env.md#customizing-development-environment-via-dockerfile)
* [Customizing both development environment and startup
  process](./custom-dev-env.md#customizing-both-development-environment-and-startup-process)

## Double Container Mode

When the development environment container doesn't have `code-server` installed,
the system will start an additional `code-server` container to provide code service — this is double container mode.
The workspace (`/workspace`) directories are shared between the two containers.

The following two methods will start in double container mode:

```yaml title=".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
```

```dockerfile title=".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 a `code-server` container, forming the double container mode.

## Double Container Mode — Cross-Container Terminal

In double container mode, accessing WebIDE or VSCode actually connects to the `code-server` container.
To access the development environment container,
you can use the cross-container terminal provided in WebIDE or VSCode
— the default terminal is a cross-container terminal named `CNB`.

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