Cloud-native development environments use an on-demand approach with automatic destruction when idle. To prevent loss of uncommitted code and configuration, the system automatically performs backups and file roaming.

Workspace Code Backup

No need to worry about losing uncommitted code after the environment is destroyed — the system provides two backup methods to ensure code safety.

Tips

For team development, it is recommended to create personal branches for development. One branch is developed by only one person, which can reduce conflicts caused by code restoration.

Backup on Development Environment Destruction

After modifying code in the workspace directory /workspace, even if not committed in time, the system automatically backs it up when the environment is recycled. After rebuilding, the code is automatically restored to the workspace.

1. Backup and Restore Methods

• Backup: Package uncommitted code and back up on environment destruction. Each branch retains only one backup. New backups overwrite old ones. If two environments are started for the same branch simultaneously, the backup from the later destroyed environment overwrites the earlier one.
• Restore: Download the backup and restore it to the workspace on environment rebuild.

Tips

The following situations will not be backed up:

• Individual code files or individual diff files larger than 100MB will be filtered out; only files not exceeding 100MB will be packaged
• If the total backup file size exceeds 100MB, it will not be backed up

Large files are recommended to be ignored using .gitignore

2. Backup Content

• Stashes in the workspace
• Commits in the workspace that have not been pushed
• Uncommitted code in the workspace (workspace modifications, staging area modifications, untracked files, excluding files ignored by .gitignore)

3. When Backup Code Is Deleted

• Each branch retains only the latest backup; new backups overwrite old ones.
• When a branch is deleted, all users' backup code under that branch is automatically cleaned up.

4. Restore Policy Description

When rebuilding or creating a new environment, it starts with the latest branch code and attempts to restore the latest backup. Conflicts may occur if code was committed outside of cloud-native development environments; in this case, the restored code can be discarded.

Tips

Workspace code backups are automatically deleted from remote storage after successful restoration, meaning each backup can only be restored once. A new backup is created when the new environment is destroyed.

Non-workspace file roaming backups (such as .gitconfig, custom roaming directories, etc.) are not deleted and will be retained for reuse across future environments.

The following content will not be backed up:

• Content declared in .gitignore
• Modified content in submodules
• Modifications outside the workspace

Scheduled Backup Strategy

To improve backup reliability, the system also uses a scheduled backup strategy, automatically packaging and backing up uncommitted code every 5 minutes.

• Download: Download the backup code package from the "My Cloud-Native Development" list page.
• Deletion: The backup is deleted when you delete the development environment history record.

Tips

• Files larger than 100MB will not be backed up.
• Backup code packages larger than 100MB will not be backed up either.

Non-Workspace File Roaming

Workspaces supports file roaming for directories outside the workspace — roaming files are automatically restored after the environment is destroyed and a new one is created.

Maximum roaming capacity: 100 MB. Exceeding this limit will cause an error and prevent roaming.

Default Roaming Content

The following files or folders roam by user dimension and apply to all projects (~ is the current user's home directory, generally /root):

• ~/.gitconfig: Git global configuration. If this file already exists in the container (e.g., pre-configured in a custom environment), it is skipped during both restore and save. It's recommended to modify /etc/gitconfig instead to avoid conflicts.
• ~/.local/share/code-server/User/settings.json: WebIDE configuration file
• ~/.local/share/code-server/User/snippets/*: WebIDE related configurations
• ~/.local/share/code-server/User/keybindings.json: WebIDE shortcut key configuration

Users can add personal environment configuration files in the ~/.cnb directory. For example, add .env.local in ~/.cnb for personal environment variables, then use script tasks to copy or symlink it to the working directory, and add it to .gitignore.

Example: Link roaming files to the working directory

To modify the roaming config file, edit /root/.cnb/.env.local directly. The example below links it to the working directory (repository root /workspace), choose copy or symlink as needed:

Copy (cp)

.cnb.yml

$:
  vscode:
    - services:
        - vscode
      stages:
        - name: Link .env.local to working directory
          script: cp -f /root/.cnb/.env.local ./ 2>/dev/null || echo "File does not exist"

Symlink (ln)

To have changes in the working directory sync back to the roaming file, use a symlink instead:

.cnb.yml

$: # Fallback matching all branches not matched by glob
  vscode:
    - services:
        - vscode
      stages:
        - name: Link .env.local to working directory
          script: ln -sf /root/.cnb/.env.local ./.env.local

Custom Roaming Directories or Files

In addition to the default roaming content above, users can also customize the directories or files to be roamed.

On the [Profile

Workspaces](https://cnb.build/profile/workspaces) page, you can configure custom roaming directory or file paths. Once configured, these directories or files will be automatically roamed and saved when the cloud-native development environment is destroyed, and automatically restored when a new environment is created or rebuilt.

Configuration notes:

• Absolute paths are required, Glob patterns are supported
• Multiple paths can be separated by newlines

Examples:

/root/.bashrc
/root/.config/

Roaming Principle and Timing

Roaming timing: Modified roaming files are not immediately saved, they are extracted and persisted when the environment is destroyed.

How to restore: Roaming files are automatically restored when rebuilding the environment.

How to verify: You need to destroy the environment and recreate it to see the roaming effect.

Tips

Note:

• When multiple development environments are open simultaneously, the roaming content from the later destroyed environment overwrites the earlier one
• Closing the development environment using kill 1 will not successfully roam the files
• If the file to be roamed is a soft link, the original file will be roamed rather than the soft link itself, to prevent the loss of the original file
• If the original file of the soft link does not exist, roaming will be skipped

Previous pageWorkspaces Recycling Mechanism

Next pageRecommended Workspaces Usage