CNB Docs

English

简体中文

English

简体中文
简体中文

Appearance

Preview Mode Only

Copy page

About 878 wordsAbout 3 min

Preview Mode Only explains how to make the "Cloud Native Development" button open the business preview page directly.

When to use: when you only want a quick look at the running service and do not need to edit code in the browser — the button skips WebIDE and goes straight to the preview page.

Preview Mode is a derivative capability of cloud-native development: clicking the Cloud Native Development button opens the preview page instead of WebIDE, so previewing is faster.

Notes

  1. This feature is in beta; configuration and usage may change.
  2. Preview Mode does not support WebIDE; use Custom Buttons to create a separate entry with WebIDE support.
  3. To use SSH, install openssh in the image yourself.
  4. Preview Mode does not support proxy, and $CNB_VSCODE_PROXY_URI is not available here; use standard Cloud Development Mode if proxy is needed.

How to Configure?

Minimal configuration:

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

Complete configuration (with all optional parameters):

.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 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 opens the preview page instead of WebIDE. To use SSH, 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. When no HTTP connection is detected for longer than this duration, the environment shuts 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:

  • Startup logs are visible in real time, which helps with troubleshooting;
  • The platform waits for launch to exit on its own before checking whether the service is ready;
  • Therefore, the launch script should exit by itself once the service is up and the port is ready (move the service to the background first, then exit);
  • If launch does not exit for a long time (for example, a service running in the foreground for more than 5 minutes), the execution fails 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 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.

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.

In either mode, once launch finishes, the platform repeatedly checks whether port 8686 inside the container is being listened on (every 10 seconds, for up to about 200 seconds), and only opens the preview page when 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 in the project root directory.
  2. Configure it as shown above.
  3. Ensure the business service listens on port 8686.
  4. Click the Cloud-Native Development button.
  5. The system starts the environment and opens 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:

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.

© 2026 cnb.cool