---
url: /en/workspaces/only-preview.md
description: >
  Describes the Cloud Development Preview Mode, a derivative of Workspaces that
  skips WebIDE and directly opens a preview page for faster previewing,
  including configuration via `.cnb.yml` and its limitations.
---
Preview Mode is a derivative capability of cloud-native development. In this mode,
clicking the `Cloud Native Development` button opens the preview page directly instead of WebIDE,
providing a faster preview experience.

:::tip Notes

1. This feature is in beta; related configurations and usage methods are subject to change in the future.
2. Preview Mode does not support WebIDE. Use [Custom Buttons](../build/web-trigger.md)
   to create a Cloud Development button entry with WebIDE support.
3. To use SSH connections, please install openssh in the image yourself.
4. Preview Mode does not support proxy. The `$CNB_VSCODE_PROXY_URI` environment variable is not available.
   Use standard Cloud Development Mode if proxy is needed.
   :::

## How to Configure?

**Minimal configuration**:

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        build: .ide/Dockerfile
      services:
        - name: vscode
          options:
            onlyPreview: true
            launch: node index.js
```

**Complete configuration** (with all optional parameters):

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        build: .ide/Dockerfile
      services:
        - docker # Optional: additionally mount the docker service
        - name: vscode
          options:
            onlyPreview: true # Required: enable preview-only mode
            launch: node index.js # Required: command to start the business service
            keepAliveTimeout: 10m # Optional: offline keep-alive time, default 10 minutes
            daemon: true # Optional: daemon mode
            backup: true # Optional: backup/restore user data
      stages:
        - name: prepare # Optional: custom preparation step before startup
          script: ls -al
```

See [Parameter Details](#parameter-details) below for detailed explanations of each option.

## Parameter Details

### onlyPreview

* Type: `Boolean`
* Description: Whether to enable Preview Mode only.
* Effect: When set to `true`,
  clicking the Cloud-Native Development button will open the preview page instead of WebIDE.
  To use SSH connections, install openssh in the image yourself.

### launch

* Type: `String`
* Description: The command to start the business service.
* Note: The business service must be started on port `8686`.
* Examples: `node index.js`, `npm start`, `python app.py`, etc.

### keepAliveTimeout

* Type: `Number` | `String` (unit defaults to: milliseconds)
* Default Value: `600000` (10 minutes)
* Description: The offline keep-alive time for the development environment.
  If no HTTP connection is detected within the specified duration,
  the environment will automatically shut down.
* Example: `7200000` represents 2 hours.

You can write a number directly (milliseconds), or a string with units, such as `10m` for 10 minutes. Supported units:

* `ms`: milliseconds (default)
* `s`: seconds
* `m`: minutes
* `h`: hours

### daemon

* Type: `Boolean`
* Default Value: `false`
* Description: The execution mode of the `launch` command (daemon mode)

**`daemon: false` (non-daemon mode, default)**

The platform runs the `launch` command in the **foreground** inside the preview environment:

* The startup logs of `launch` are visible in real time, which helps with troubleshooting;
* The platform **waits for the `launch` command to exit** before continuing to check whether the service is ready;
* Therefore, the `launch` script should **exit by itself** after the service is started and the port is ready
  (it is recommended to move the service to the background inside the script before exiting);
* If `launch` does not exit for a long time (for example, a service running in the foreground for more than
  5 minutes without exiting), the execution will fail due to a timeout.

**`daemon: true` (daemon mode)**

The platform runs the `launch` command in the **background (detached)** mode:

* The service started by `launch` runs directly in the background, and `docker exec` returns immediately
  without waiting for `launch` to exit;
* Because it runs in the background, **the startup logs of `launch` are not visible**.

::: tip Recommendation
Keep `daemon: false` by default. Implement this inside your `launch` script instead:
after the service is started and the port is ready, move the service to the background and let the script exit.
This way you can view the startup logs for troubleshooting without blocking the flow because the script never exits.
:::

Regardless of the mode, after `launch` finishes, the platform periodically (every 10 seconds, for up to about
200 seconds) checks whether port `8686` inside the container is being listened on, and only opens the preview
page once the service is confirmed ready. Make sure `launch` ultimately starts the business service on port `8686`.

### backup

* Type: `Boolean`
* Default Value: `false`
* Description: Whether to backup/restore user data (only effective in Preview Mode). When set to `true`:
  * On startup: Restore previous user roaming data and uncommitted code changes.
  * During runtime: Periodically backup uncommitted code changes.
  * On shutdown: Backup user roaming data and uncommitted code changes.

## Usage Process

1. Create a `.cnb.yml` file in the project root directory.
2. Configure it according to the example above.
3. Ensure the business service listens on port `8686`.
4. Click the Cloud-Native Development button.
5. The system will automatically start the development environment and open the preview page.

## How to Use SSH Connections in Preview Mode?

Install openssh in your custom development environment. Configure it in `.ide/Dockerfile` as follows:

```Dockerfile
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
```

Once the preview workspace is ready, it opens the preview page directly without showing the client selection page.
For client connections, find the entry under **Avatar → My Cloud Native Development**.