# code-server Documentation > code-server runs VS Code on a remote server, accessible through the browser. Every page below is also available as raw Markdown by appending `.md` to its URL or by sending `Accept: text/markdown`. Full corpus: https://coder.com/docs/code-server/llms-full.txt ## Pages - [Home](https://coder.com/docs/code-server.md): Learn how to install and run code-server. - [Requirements](https://coder.com/docs/code-server/requirements.md): Learn about what you need to run code-server. - [Install](https://coder.com/docs/code-server/install.md): How to install code-server. - [npm](https://coder.com/docs/code-server/npm.md): How to install code-server using npm - [Helm](https://coder.com/docs/code-server/helm.md): How to install code-server using the Helm package manager - [Usage](https://coder.com/docs/code-server/guide.md): How to set up and use code-server. - [Coder](https://coder.com/docs/code-server/coder.md): How to run code-server in Coder - [iPad](https://coder.com/docs/code-server/ipad.md): How to access your code-server installation using an iPad. - [Termux](https://coder.com/docs/code-server/termux.md): How to install Termux to run code-server on an Android device. - [iOS](https://coder.com/docs/code-server/ios.md): How to use code-server on iOS with iSH. - [Android](https://coder.com/docs/code-server/android.md): How to run code-server on an Android device using UserLAnd. - [Collaboration](https://coder.com/docs/code-server/collaboration.md): How to setup real time collaboration using code server. - [Upgrade](https://coder.com/docs/code-server/upgrade.md): How to upgrade code-server. - [FAQ](https://coder.com/docs/code-server/FAQ.md): Frequently asked questions on installing and running code-server. - [Contributing](https://coder.com/docs/code-server/CONTRIBUTING.md): How to contribute to code-server. - [Code of conduct](https://coder.com/docs/code-server/CODE_OF_CONDUCT.md): Coder expects contributors to code-server to behave in a manner that creates an open and welcoming environment. - [Maintenance](https://coder.com/docs/code-server/MAINTAINING.md): Learn about the workflow followed by code-server's maintainers. - [Triage](https://coder.com/docs/code-server/triage.md): How the maintainers triage issues with code-server. - [Security](https://coder.com/docs/code-server/SECURITY.md): Learn about the tools used to detect vulnerabilities in code-server, and how you can report vulnerabilities. --- # Home Source: https://coder.com/docs/code-server # code-server [!["GitHub Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/coder/code-server/discussions) [!["Join us on Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://coder.com/community) [![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) [![Discord](https://img.shields.io/discord/747933592273027093)](https://discord.com/invite/coder) [![codecov](https://codecov.io/gh/coder/code-server/branch/main/graph/badge.svg?token=5iM9farjnC)](https://codecov.io/gh/coder/code-server) [![See latest](https://img.shields.io/static/v1?label=Docs&message=see%20latest&color=blue)](https://coder.com/docs/code-server/latest) Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and access it in the browser. ![Screenshot](./assets/screenshot-1.png) ![Screenshot](./assets/screenshot-2.png) ## Highlights - Code on any device with a consistent development environment - Use cloud servers to speed up tests, compilations, downloads, and more - Preserve battery life when you're on the go; all intensive tasks run on your server ## Requirements See [requirements](https://coder.com/docs/code-server/latest/requirements) for minimum specs, as well as instructions on how to set up a Google VM on which you can install code-server. **TL;DR:** Linux machine with WebSockets enabled, 1 GB RAM, and 2 vCPUs ## Getting started There are five ways to get started: 1. Using the [install script](https://github.com/coder/code-server/blob/main/install.sh), which automates most of the process. The script uses the system package manager if possible. 2. Manually [installing code-server](https://coder.com/docs/code-server/latest/install) 3. Deploy code-server to your team with [coder/coder](https://cdr.co/coder-github) 4. Using our one-click buttons and guides to [deploy code-server to a cloud provider](https://github.com/coder/deploy-code-server) ⚡ 5. Using the [code-server feature for devcontainers](https://github.com/coder/devcontainer-features/blob/main/src/code-server/README.md), if you already use devcontainers in your project. If you use the install script, you can preview what occurs during the install process: ```bash curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run ``` To install, run: ```bash curl -fsSL https://code-server.dev/install.sh | sh ``` When done, the install script prints out instructions for running and starting code-server. > **Note** > To manage code-server for a team on your infrastructure, see: [coder/coder](https://cdr.co/coder-github) We also have an in-depth [setup and configuration](https://coder.com/docs/code-server/latest/guide) guide. ## Questions? See answers to [frequently asked questions](https://coder.com/docs/code-server/latest/FAQ). ## Want to help? See [Contributing](https://coder.com/docs/code-server/latest/CONTRIBUTING) for details. ## Hiring Interested in [working at Coder](https://coder.com/careers)? Check out [our open positions](https://coder.com/careers#openings)! ## For Teams We develop [coder/coder](https://cdr.co/coder-github) to help teams to adopt remote development. --- # Requirements Source: https://coder.com/docs/code-server/requirements # Requirements You'll need a machine on which you can run code-server. You can use a physical machine you have, or you can use a VM on GCP/AWS. At the minimum, we recommend: - 1 GB of RAM - 2 CPU cores You can use any Linux distribution, but [our docs](https://coder.com/docs/code-server/latest/guide) assume that you're using Debian hosted by Google Cloud (see the following section for instructions on setting this up). Your environment must have WebSockets enabled, since code-server uses WebSockets for communication between the browser and the server. ## Set up a VM on Google Cloud The following steps walk you through setting up a VM running Debian using Google Cloud (though you are welcome to use any machine or VM provider). If you're [signing up with Google](https://console.cloud.google.com/getting-started) for the first time, you should get a 3-month trial with \$300 of credits. After you sign up and create a new Google Cloud Provider (GCP) project, create a new Compute Engine VM instance: 1. Using the sidebar, navigate to **Compute Engine** > **VM Instances**. 2. Click **Create Instance**. 3. Provide a **name** for new instance. 4. Choose the **region** that's closest to you based on [GCP ping](https://gcping.com/). 5. Choose a **zone** (any option is fine). 6. We recommend choosing an **E2 series instance** from the [general-purpose family](https://cloud.google.com/compute/docs/machine-types#general_purpose). 7. Change the instance type to **custom** and set at least **2 cores** and **2 GB of RAM**. You can add more resources if desired, though you can also edit your instance at a later point. 8. Though optional, we highly recommend switching the persistent disk to an SSD with at least 32 GB. To do so, click **change** under **Boot Disk**. Then, change the type to **SSD Persistent Disk**, and set the size to **32**. (You can also grow your disk at a later date). 9. Go to **Networking** > **Networking Interfaces** and edit the existing interface to use a static internal IP. Click **Done** to save. 10. If you don't have a [project-wide SSH key](https://cloud.google.com/compute/docs/instances/adding-removing-ssh-keys#project-wide), go to **Security** > **SSH Keys** to add your public key. 11. Click **Create** to proceed. Notes: - To lower costs, you can shut down your server when you're not using it. - We recommend using the `gcloud cli` to avoid using the GCP Dashboard if possible. - For serving code-server over HTTPS, we recommend using an external domain name along with a service such as Let's Encrypt --- # Install Source: https://coder.com/docs/code-server/install # Install - [install.sh](#installsh) - [Detection reference](#detection-reference) - [npm](#npm) - [Standalone releases](#standalone-releases) - [Debian, Ubuntu](#debian-ubuntu) - [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse) - [Arch Linux](#arch-linux) - [Artix Linux](#artix-linux) - [macOS](#macos) - [Docker](#docker) - [Helm](#helm) - [Windows](#windows) - [Raspberry Pi](#raspberry-pi) - [Termux](#termux) - [Cloud providers](#cloud-providers) - [Uninstall](#uninstall) - [install.sh](#installsh-1) - [Homebrew](#homebrew) - [npm](#npm-1) - [Debian, Ubuntu](#debian-ubuntu-1) This document demonstrates how to install `code-server` on various distros and operating systems. ## install.sh The easiest way to install code-server is to use our [install script](https://github.com/coder/code-server/blob/main/install.sh) for Linux, macOS and FreeBSD. The install script [attempts to use the system package manager](#detection-reference) if possible. You can preview what occurs during the install process: ```bash curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run ``` To install, run: ```bash curl -fsSL https://code-server.dev/install.sh | sh ``` You can modify the installation process by including one or more of the following flags: - `--dry-run`: echo the commands for the install process without running them. - `--method`: choose the installation method. - `--method=detect`: detect the package manager but fallback to `--method=standalone`. - `--method=standalone`: install a standalone release archive into `~/.local`. - `--prefix=/usr/local`: install a standalone release archive system-wide. - `--version=X.X.X`: install version `X.X.X` instead of latest version. - `--help`: see usage docs. - `--edge`: install the latest edge version (i.e. pre-release) When done, the install script prints out instructions for running and starting code-server. > If you're concerned about the install script's use of `curl | sh` and the > security implications, please see [this blog > post](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) > by [sandstorm.io](https://sandstorm.io). If you prefer to install code-server manually, despite the [detection references](#detection-reference) and `--dry-run` feature, then continue on for information on how to do this. The [`install.sh`](https://github.com/coder/code-server/blob/main/install.sh) script runs the _exact_ same commands presented in the rest of this document. ### Detection reference - For Debian and Ubuntu, code-server will install the latest deb package. - For Fedora, CentOS, RHEL and openSUSE, code-server will install the latest RPM package. - For Arch Linux, code-server will install the AUR package. - For any unrecognized Linux operating system, code-server will install the latest standalone release into `~/.local`. - Ensure that you add `~/.local/bin` to your `$PATH` to run code-server. - For macOS, code-server will install the Homebrew package (if you don't have Homebrew installed, code-server will install the latest standalone release into `~/.local`). - Ensure that you add `~/.local/bin` to your `$PATH` to run code-server. - For FreeBSD, code-server will install the [npm package](#npm) with `npm` - If you're installing code-server onto architecture with no releases, code-server will install the [npm package](#npm) with `npm` - We currently offer releases for amd64 and arm64. - The [npm package](#npm) builds the native modules on post-install. ## npm We recommend installing with `npm` when: 1. You aren't using a machine with `amd64` or `arm64`. 2. You are installing code-server on Windows. 3. You're on Linux with `glibc` < v2.28 or `glibcxx` < v3.4.21. 4. You're running Alpine Linux or are using a non-glibc libc. See [#1430](https://github.com/coder/code-server/issues/1430#issuecomment-629883198) for more information. Installing code-server with `npm` builds native modules on install. This process requires C dependencies; see our guide on [installing with npm](./npm.md) for more information. ## Standalone releases We publish self-contained `.tar.gz` archives for every release on [GitHub](https://github.com/coder/code-server/releases). The archives bundle the node binary and node modules. We create the standalone releases using the [npm package](#npm), and we then create the remaining releases using the standalone version. The only requirement to use the standalone release is `glibc` >= 2.28 and `glibcxx` >= v3.4.21 on Linux (for macOS, there is no minimum system requirement). To use a standalone release: 1. Download the latest release archive for your system from [GitHub](https://github.com/coder/code-server/releases). 2. Unpack the release. 3. Run code-server by executing `./bin/code-server`. You can add `./bin/code-server` to your `$PATH` so that you can execute `code-server` without providing full path each time. Here is a sample script for installing and using a standalone code-server release on Linux: ```bash mkdir -p ~/.local/lib ~/.local/bin curl -fL https://github.com/coder/code-server/releases/download/v$VERSION/code-server-$VERSION-linux-amd64.tar.gz \ | tar -C ~/.local/lib -xz mv ~/.local/lib/code-server-$VERSION-linux-amd64 ~/.local/lib/code-server-$VERSION ln -s ~/.local/lib/code-server-$VERSION/bin/code-server ~/.local/bin/code-server PATH="~/.local/bin:$PATH" code-server # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ## Debian, Ubuntu > The standalone arm64 .deb does not support Ubuntu 16.04 or earlier. Please > upgrade or [build with npm](#npm). ```bash curl -fOL https://github.com/coder/code-server/releases/download/v$VERSION/code-server_${VERSION}_amd64.deb sudo dpkg -i code-server_${VERSION}_amd64.deb sudo systemctl enable --now code-server@$USER # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ## Fedora, CentOS, RHEL, SUSE > The standalone arm64 .rpm does not support CentOS 7. Please upgrade or [build > with npm](#npm). ```bash curl -fOL https://github.com/coder/code-server/releases/download/v$VERSION/code-server-$VERSION-amd64.rpm sudo rpm -i code-server-$VERSION-amd64.rpm sudo systemctl enable --now code-server@$USER # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ## Arch Linux ```bash # Install code-server from the AUR using yay. yay -S code-server sudo systemctl enable --now code-server@$USER # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ```bash # Install code-server from the AUR with plain makepkg. git clone https://aur.archlinux.org/code-server.git cd code-server makepkg -si sudo systemctl enable --now code-server@$USER # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ## Artix Linux ```bash # Install code-server from the AUR git clone https://aur.archlinux.org/code-server.git cd code-server makepkg -si ``` Save the file as `code-server` in `/etc/init.d/` and make it executable with `chmod +x code-server`. Put your username in line 3. ```bash #!/sbin/openrc-run name=$RC_SVCNAME description="$name - VS Code on a remote server" user="" # your username here homedir="/home/$user" command="$(which code-server)" # Just because you can do this does not mean you should. Use ~/.config/code-server/config.yaml instead #command_args="--extensions-dir $homedir/.local/share/$name/extensions --user-data-dir $homedir/.local/share/$name --disable-telemetry" command_user="$user:$user" pidfile="/run/$name/$name.pid" command_background="yes" extra_commands="report" depend() { use logger dns need net } start_pre() { checkpath --directory --owner $command_user --mode 0755 /run/$name /var/log/$name } start() { default_start report } stop() { default_stop } status() { default_status report } report() { # Report to the user einfo "Reading configuration from ~/.config/code-server/config.yaml" } ``` Start on boot with default runlevel ``` rc-update add code-server default ``` Start the service immediately ``` rc-service code-server start ``` ## macOS ```bash brew install code-server brew services start code-server # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ## Docker ```bash # This will start a code-server container and expose it at http://127.0.0.1:8080. # It will also mount your current directory into the container as `/home/coder/project` # and forward your UID/GID so that all file system operations occur as your user outside # the container. # # Your $HOME/.config is mounted at $HOME/.config within the container to ensure you can # easily access/modify your code-server config in $HOME/.config/code-server/config.json # outside the container. mkdir -p ~/.config docker run -it --name code-server -p 127.0.0.1:8080:8080 \ -v "$HOME/.local:/home/coder/.local" \ -v "$HOME/.config:/home/coder/.config" \ -v "$PWD:/home/coder/project" \ -u "$(id -u):$(id -g)" \ -e "DOCKER_USER=$USER" \ codercom/code-server:latest ``` Our official image supports `amd64` and `arm64`. For `arm32` support, you can use a [community-maintained code-server alternative](https://hub.docker.com/r/linuxserver/code-server). ## Helm You can install code-server using the [Helm package manager](https://coder.com/docs/code-server/latest/helm). ## Windows We currently [do not publish Windows releases](https://github.com/coder/code-server/issues/1397). We recommend installing code-server onto Windows with [`npm`](#npm). ## Raspberry Pi We recommend installing code-server onto Raspberry Pi with [`npm`](#npm). If you see an error related to `node-gyp` during installation, See [#5174](https://github.com/coder/code-server/issues/5174) for more information. ## Termux Please see code-server's [Termux docs](./termux.md#installation) for more information. ## Cloud providers We maintain [one-click apps and install scripts for cloud providers](https://github.com/coder/deploy-code-server) such as DigitalOcean, Railway, Heroku, and Azure. ## Uninstall code-server can be completely uninstalled by removing the application directory, and your user configuration directory. To delete settings and data: ```shell rm -rf ~/.local/share/code-server ~/.config/code-server ``` ### install.sh If you installed with the install script, by default code-server will be in `~/.local/lib/code-server-` and you can remove it with `rm -rf`. e.g. ```shell rm -rf ~/.local/lib/code-server-* ``` ### Homebrew To remove the code-server homebrew package, run: ```shell brew remove code-server # Alternatively brew uninstall code-server ``` ### npm To remove the code-server global module, run: ```shell npm uninstall --global code-server ``` ### Debian, Ubuntu To uninstall, run: ```shell sudo apt remove code-server ``` --- # npm Source: https://coder.com/docs/code-server/npm # npm Install Requirements - [Node.js version](#nodejs-version) - [Ubuntu, Debian](#ubuntu-debian) - [Fedora, CentOS, RHEL](#fedora-centos-rhel) - [Alpine](#alpine) - [macOS](#macos) - [FreeBSD](#freebsd) - [Windows](#windows) - [Installing](#installing) - [Troubleshooting](#troubleshooting) - [Issues with Node.js after version upgrades](#issues-with-nodejs-after-version-upgrades) - [Debugging install issues with npm](#debugging-install-issues-with-npm) If you're installing code-server via `npm`, you'll need to install additional dependencies required to build the native modules used by VS Code. This article includes installing instructions based on your operating system. > **WARNING**: Do not use `yarn` to install code-server. Unlike `npm`, it does not respect > lockfiles for distributed applications. It will instead use the latest version > available at installation time - which might not be the one used for a given > code-server release, and [might lead to unexpected behavior](https://github.com/coder/code-server/issues/4927). ## Node.js version We use the same major version of Node.js shipped with Code's remote, which is currently `22.x`. VS Code also [lists Node.js requirements](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites). Using other versions of Node.js [may lead to unexpected behavior](https://github.com/coder/code-server/issues/1633). ## Ubuntu, Debian ```bash sudo apt-get install -y \ build-essential \ pkg-config \ python3 npm config set python python3 ``` Proceed to [installing](#installing) ## Fedora, CentOS, RHEL ```bash sudo yum groupinstall -y 'Development Tools' sudo yum config-manager --set-enabled PowerTools # unnecessary on CentOS 7 sudo yum install -y python2 npm config set python python2 ``` Proceed to [installing](#installing) ## Alpine ```bash apk add alpine-sdk bash libstdc++ libc6-compat python3 krb5-dev ``` Proceed to [installing](#installing) ## macOS ```bash xcode-select --install ``` Proceed to [installing](#installing) ## FreeBSD ```sh pkg install -y git python npm-node22 pkgconf pkg install -y libinotify ``` Proceed to [installing](#installing) ## Windows Installing code-server requires all of the [prerequisites for VS Code development](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites). When installing the C++ compiler tool chain, we recommend using "Option 2: Visual Studio 2019" for best results. Next, install code-server with: ```bash npm install --global code-server code-server # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` A `postinstall.sh` script will attempt to run. Select your terminal (e.g., Git bash) as the default shell for npm run-scripts. If an additional dialog does not appear, run the install command again. If the `code-server` command is not found, you'll need to [add a directory to your PATH](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/). To find the directory, use the following command: ```shell npm config get prefix ``` For help and additional troubleshooting, see [#1397](https://github.com/coder/code-server/issues/1397). ## Installing After adding the dependencies for your OS, install the code-server package globally: ```bash npm install --global code-server code-server # Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml ``` ## Troubleshooting If you need further assistance, post on our [GitHub Discussions page](https://github.com/coder/code-server/discussions). ### Issues with Node.js after version upgrades Occasionally, you may run into issues with Node.js. If you install code-server using `npm`, and you upgrade your Node.js version, you may need to reinstall code-server to recompile native modules. Sometimes, you can get around this by navigating into code-server's `lib/vscode` directory and running `npm rebuild` to recompile the modules. A step-by-step example of how you might do this is: 1. Install code-server: `brew install code-server` 2. Navigate into the directory: `cd /usr/local/Cellar/code-server//libexec/lib/vscode/` 3. Recompile the native modules: `npm rebuild` 4. Restart code-server ### Debugging install issues with npm To debug installation issues, install with `npm`: ```shell # Uninstall npm uninstall --global code-server > /dev/null 2>&1 # Install with logging npm install --loglevel verbose --global code-server ``` --- # Helm Source: https://coder.com/docs/code-server/helm # code-server Helm Chart [![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square)](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) [![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)](https://img.shields.io/badge/Type-application-informational?style=flat-square) [![AppVersion: 4.8.0](https://img.shields.io/badge/AppVersion-4.8.0-informational?style=flat-square)](https://img.shields.io/badge/AppVersion-4.8.0-informational?style=flat-square) [code-server](https://github.com/coder/code-server) code-server is VS Code running on a remote server, accessible through the browser. This chart is community maintained by [@Matthew-Beckett](https://github.com/Matthew-Beckett) and [@alexgorbatchev](https://github.com/alexgorbatchev) ## Quickstart ```console $ git clone https://github.com/coder/code-server $ cd code-server $ helm upgrade --install code-server ci/helm-chart ``` ## Introduction This chart bootstraps a code-server deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager. ## Prerequisites - Kubernetes 1.6+ ## Installing the Chart To install the chart with the release name `code-server`: ```console $ git clone https://github.com/coder/code-server $ cd code-server $ helm upgrade --install code-server ci/helm-chart ``` The command deploys code-server on the Kubernetes cluster in the default configuration. The [configuration](#configuration) section lists the parameters that can be configured during installation. > **Tip**: List all releases using `helm list` ## Uninstalling the Chart To uninstall/delete the `code-server` deployment: ```console $ helm delete code-server ``` The command removes all the Kubernetes components associated with the chart and deletes the release. ## Configuration The following table lists the configurable parameters of the code-server chart and their default values. ## Values | Key | Type | Default | | ------------------------------------------- | ------ | ------------------------ | | affinity | object | `{}` | | extraArgs | list | `[]` | | extraConfigmapMounts | list | `[]` | | extraContainers | string | `""` | | extraInitContainers | string | `""` | | extraSecretMounts | list | `[]` | | extraVars | list | `[]` | | extraVolumeMounts | list | `[]` | | fullnameOverride | string | `""` | | hostnameOverride | string | `""` | | image.pullPolicy | string | `"Always"` | | image.repository | string | `"codercom/code-server"` | | image.tag | string | `"4.8.0"` | | imagePullSecrets | list | `[]` | | ingress.enabled | bool | `false` | | nameOverride | string | `""` | | nodeSelector | object | `{}` | | persistence.accessMode | string | `"ReadWriteOnce"` | | persistence.annotations | object | `{}` | | persistence.enabled | bool | `true` | | persistence.size | string | `"1Gi"` | | podAnnotations | object | `{}` | | podSecurityContext | object | `{}` | | replicaCount | int | `1` | | resources | object | `{}` | | securityContext.enabled | bool | `true` | | securityContext.fsGroup | int | `1000` | | securityContext.runAsUser | int | `1000` | | service.port | int | `8443` | | service.type | string | `"ClusterIP"` | | serviceAccount.create | bool | `true` | | serviceAccount.name | string | `nil` | | tolerations | list | `[]` | | volumePermissions.enabled | bool | `true` | | volumePermissions.securityContext.runAsUser | int | `0` | Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example, ```console $ helm upgrade --install code-server \ ci/helm-chart \ --set persistence.enabled=false ``` The above command sets the the persistence storage to false. Alternatively, a YAML file that specifies the values for the above parameters can be provided while installing the chart. For example, ```console $ helm upgrade --install code-server ci/helm-chart -f values.yaml ``` > **Tip**: You can use the default [values.yaml](values.yaml) # Extra Containers There are two parameters which allow to add more containers to pod. Use `extraContainers` to add regular containers and `extraInitContainers` to add init containers. You can read more about init containers in [k8s documentation](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/). Both parameters accept strings and use them as a templates Example of using `extraInitContainers`: ```yaml extraInitContainers: | - name: customization image: {{ .Values.image.repository }}:{{ .Values.image.tag }} imagePullPolicy: IfNotPresent env: - name: SERVICE_URL value: https://open-vsx.org/vscode/gallery - name: ITEM_URL value: https://open-vsx.org/vscode/item command: - sh - -c - | code-server --install-extension ms-python.python code-server --install-extension golang.Go volumeMounts: - name: data mountPath: /home/coder ``` With this yaml in file `init.yaml`, you can execute ```console $ helm upgrade --install code-server \ ci/helm-chart \ --values init.yaml ``` to deploy code-server with python and golang extensions preinstalled before main container have started. --- # Usage Source: https://coder.com/docs/code-server/guide # Setup Guide - [Expose code-server](#expose-code-server) - [Port forwarding via SSH](#port-forwarding-via-ssh) - [Using Let's Encrypt with Caddy](#using-lets-encrypt-with-caddy) - [Using Let's Encrypt with NGINX](#using-lets-encrypt-with-nginx) - [Using a self-signed certificate](#using-a-self-signed-certificate) - [TLS 1.3 and Safari](#tls-13-and-safari) - [External authentication](#external-authentication) - [HTTPS and self-signed certificates](#https-and-self-signed-certificates) - [Accessing web services](#accessing-web-services) - [Using a subdomain](#using-a-subdomain) - [Using a subpath](#using-a-subpath) - [Using your own proxy](#using-your-own-proxy) - [Stripping `/proxy/` from the request path](#stripping-proxyport-from-the-request-path) - [Proxying to create a React app](#proxying-to-create-a-react-app) - [Proxying to a Vue app](#proxying-to-a-vue-app) - [Proxying to an Angular app](#proxying-to-an-angular-app) - [Proxying to a Svelte app](#proxying-to-a-svelte-app) - [Prefixing `/absproxy/` with a path](#prefixing-absproxyport-with-a-path) - [Preflight requests](#preflight-requests) - [Internationalization and customization](#internationalization-and-customization) - [Available keys and placeholders](#available-keys-and-placeholders) - [Legacy flag](#legacy-flag) This article will walk you through exposing code-server securely once you've completed the [installation process](install.md). ## Expose code-server **Never** expose code-server directly to the internet without some form of authentication and encryption, otherwise someone can take over your machine via the terminal. By default, code-server uses password authentication. As such, you must copy the password from code-server's config file to log in. To avoid exposing itself unnecessarily, code-server listens on `localhost`; this practice is fine for testing, but it doesn't work if you want to access code-server from a different machine. > **Rate limits:** code-server rate limits password authentication attempts to > two per minute plus an additional twelve per hour. There are several approaches to operating and exposing code-server securely: - Port forwarding via SSH - Using Let's Encrypt with Caddy - Using Let's Encrypt with NGINX - Using a self-signed certificate ### Port forwarding via SSH We highly recommend using [port forwarding via SSH](https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding) to access code-server. If you have an SSH server on your remote machine, this approach doesn't require any additional setup at all. The downside to SSH forwarding, however, is that you can't access code-server when using machines without SSH clients (such as iPads). If this applies to you, we recommend using another method, such as [Let's Encrypt](#let-encrypt) instead. > To work properly, your environment should have WebSockets enabled, which > code-server uses to communicate between the browser and server. 1. SSH into your instance and edit the code-server config file to disable password authentication: ```console # Replaces "auth: password" with "auth: none" in the code-server config. sed -i.bak 's/auth: password/auth: none/' ~/.config/code-server/config.yaml ``` 2. Restart code-server: ```console sudo systemctl restart code-server@$USER ``` 3. Forward local port `8080` to `127.0.0.1:8080` on the remote instance by running the following command on your local machine: ```console # -N disables executing a remote shell ssh -N -L 8080:127.0.0.1:8080 [user]@ ``` 4. At this point, you can access code-server by pointing your web browser to `http://127.0.0.1:8080`. 5. If you'd like to make the port forwarding via SSH persistent, we recommend using [mutagen](https://mutagen.io/documentation/introduction/installation) to do so. Once you've installed mutagen, you can port forward as follows: ```shell # This is the same as the above SSH command, but it runs in the background # continuously. Be sure to add `mutagen daemon start` to your ~/.bashrc to # start the mutagen daemon when you open a shell. mutagen forward create --name=code-server tcp:127.0.0.1:8080 < instance-ip > :tcp:127.0.0.1:8080 ``` 6. Optional, but highly recommended: add the following to `~/.ssh/config` so that you can detect bricked SSH connections: ```bash Host * ServerAliveInterval 5 ExitOnForwardFailure yes ``` > You can [forward your > SSH](https://developer.github.com/v3/guides/using-ssh-agent-forwarding/) and > [GPG agent](https://wiki.gnupg.org/AgentForwarding) to the instance to > securely access GitHub and sign commits without having to copy your keys. ### Using Let's Encrypt with Caddy Using [Let's Encrypt](https://letsencrypt.org) is an option if you want to access code-server on an iPad or do not want to use SSH port forwarding. 1. This option requires that the remote machine be exposed to the internet. Make sure that your instance allows HTTP/HTTPS traffic. 2. You'll need a domain name (if you don't have one, you can purchase one from [Google Domains](https://domains.google.com) or the domain service of your choice). Once you have a domain name, add an A record to your domain that contains your instance's IP address. 3. Install [Caddy](https://caddyserver.com/docs/download#debian-ubuntu-raspbian): ```console sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo apt update sudo apt install caddy ``` 4. Replace `/etc/caddy/Caddyfile` using `sudo` so that the file looks like this: ```text mydomain.com { reverse_proxy 127.0.0.1:8080 } ``` If you want to serve code-server from a sub-path, you can do so as follows: ```text mydomain.com/code/* { uri strip_prefix /code reverse_proxy 127.0.0.1:8080 } ``` Remember to replace `mydomain.com` with your domain name! 5. Reload Caddy: ```console sudo systemctl reload caddy ``` At this point, you should be able to access code-server via `https://mydomain.com`. ### Using Let's Encrypt with NGINX 1. This option requires that the remote machine be exposed to the internet. Make sure that your instance allows HTTP/HTTPS traffic. 2. You'll need a domain name (if you don't have one, you can purchase one from [Google Domains](https://domains.google.com) or the domain service of your choice). Once you have a domain name, add an A record to your domain that contains your instance's IP address. 3. Install NGINX: ```bash sudo apt update sudo apt install -y nginx certbot python3-certbot-nginx ``` 4. Update `/etc/nginx/sites-available/code-server` using sudo with the following configuration: ```text server { listen 80; listen [::]:80; server_name mydomain.com; location / { proxy_pass http://localhost:8080/; proxy_set_header Host $http_host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Accept-Encoding gzip; } } ``` Be sure to replace `mydomain.com` with your domain name! 5. Enable the config: ```console sudo ln -s ../sites-available/code-server /etc/nginx/sites-enabled/code-server sudo certbot --non-interactive --redirect --agree-tos --nginx -d mydomain.com -m me@example.com ``` Be sure to replace `me@example.com` with your actual email. At this point, you should be able to access code-server via `https://mydomain.com`. ### Using a self-signed certificate > Self signed certificates do not work with iPad; see [./ipad.md](./ipad.md) for > more information. Before proceeding, we recommend familiarizing yourself with the [risks of self-signing a certificate for SSL](https://security.stackexchange.com/questions/8110). We recommend self-signed certificates as a last resort, since self-signed certificates do not work with iPads and may cause unexpected issues with code-server. You should only proceed with this option if: - You do not want to buy a domain or you cannot expose the remote machine to the internet - You do not want to use port forwarding via SSH To use a self-signed certificate: 1. This option requires that the remote machine be exposed to the internet. Make sure that your instance allows HTTP/HTTPS traffic. 1. SSH into your instance and edit your code-server config file to use a randomly generated self-signed certificate: ```console # Replaces "cert: false" with "cert: true" in the code-server config. sed -i.bak 's/cert: false/cert: true/' ~/.config/code-server/config.yaml # Replaces "bind-addr: 127.0.0.1:8080" with "bind-addr: 0.0.0.0:443" in the code-server config. sed -i.bak 's/bind-addr: 127.0.0.1:8080/bind-addr: 0.0.0.0:443/' ~/.config/code-server/config.yaml # Allows code-server to listen on port 443. sudo setcap cap_net_bind_service=+ep /usr/lib/code-server/lib/node ``` 1. Restart code-server: ```console sudo systemctl restart code-server@$USER ``` At this point, you should be able to access code-server via `https://`. If you'd like to avoid the warnings displayed by code-server when using a self-signed certificate, you can use [mkcert](https://mkcert.dev) to create a self-signed certificate that's trusted by your operating system, then pass the certificate to code-server via the `cert` and `cert-key` config fields. ### TLS 1.3 and Safari If you will be using Safari and your configuration does not allow anything less than TLS 1.3 you will need to add support for TLS 1.2 since Safari does not support TLS 1.3 for web sockets at the time of writing. If this is the case you should see OSSStatus: 9836 in the browser console. ## External authentication If you want to use external authentication mechanism (e.g., Sign in with Google), you can do this with a reverse proxy such as: - [Pomerium](https://www.pomerium.com/docs/guides/code-server.html) - [oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) - [Cloudflare Access](https://www.cloudflare.com/zero-trust/products/access/) ## HTTPS and self-signed certificates For HTTPS, you can use a self-signed certificate by: - Passing in `--cert` - Passing in an existing certificate by providing the path to `--cert` and the path to the key with `--cert-key` The self signed certificate will be generated to `~/.local/share/code-server/self-signed.crt`. If you pass a certificate to code-server, it will respond to HTTPS requests and redirect all HTTP requests to HTTPS. > You can use [Let's Encrypt](https://letsencrypt.org/) to get a TLS certificate > for free. Note: if you set `proxy_set_header Host $host;` in your reverse proxy config, it will change the address displayed in the green section of code-server in the bottom left to show the correct address. ## Accessing web services If you're working on web services and want to access them locally, code-server can proxy to any port using either a subdomain or a subpath, allowing you to securely access these services using code-server's built-in authentication. ### Using a subdomain You will need a DNS entry that points to your server for each port you want to access. You can either set up a wildcard DNS entry for `*.` if your domain name registrar supports it, or you can create one for every port you want to access (`3000.`, `8080.`, etc). You should also set up TLS certificates for these subdomains, either using a wildcard certificate for `*.` or individual certificates for each port. To set your domain, start code-server with the `--proxy-domain` flag: ```console code-server --proxy-domain ``` For instance, if you have code-server exposed on `domain.tld` and a Python server running on port 8080 of the same machine code-server is running on, you could run code-server with `--proxy-domain domain.tld` and access the Python server via `8080.domain.tld`. Note that this uses the host header, so ensure your reverse proxy (if you're using one) forwards that information. ### Using a subpath Simply browse to `/proxy//`. For instance, if you have code-server exposed on `domain.tld` and a Python server running on port 8080 of the same machine code-server is running on, you could access the Python server via `domain.tld/proxy/8000`. ### Using your own proxy You can make extensions and the ports panel use your own proxy by setting `VSCODE_PROXY_URI`. For example if you set `VSCODE_PROXY_URI=https://{{port}}.kyle.dev` when an application is detected running on port 3000 of the same machine code-server is running on the ports panel will create a link to https://3000.kyle.dev instead of pointing to the built-in subpath-based proxy. Note: relative paths are also supported i.e. `VSCODE_PROXY_URI=./proxy/{{port}}` ### Stripping `/proxy/` from the request path You may notice that the code-server proxy strips `/proxy/` from the request path. HTTP servers should use relative URLs to avoid the need to be coupled to the absolute path at which they are served. This means you must [use trailing slashes on all paths with subpaths](https://blog.cdivilly.com/2019/02/28/uri-trailing-slashes). This reasoning is why the default behavior is to strip `/proxy/` from the base path. If your application uses relative URLs and does not assume the absolute path at which it is being served, it will just work no matter what port you decide to serve it off or if you put it in behind code-server or any other proxy. However, some prefer the cleaner aesthetic of no trailing slashes. Omitting the trailing slashes couples you to the base path, since you cannot use relative redirects correctly anymore. If you're okay with this tradeoff, use `/absproxy` instead and the path will be passed as is (e.g., `/absproxy/3000/my-app-path`). ### Proxying to create a React app You must use `/absproxy/` with `create-react-app` (see [#2565](https://github.com/coder/code-server/issues/2565) and [#2222](https://github.com/coder/code-server/issues/2222) for more information). You will need to inform `create-react-app` of the path at which you are serving via `$PUBLIC_URL` and webpack via `$WDS_SOCKET_PATH`: ```sh PUBLIC_URL=/absproxy/3000 \ WDS_SOCKET_PATH=$PUBLIC_URL/sockjs-node \ BROWSER=none yarn start ``` You should then be able to visit `https://my-code-server-address.io/absproxy/3000` to see your app exposed through code-server. > We highly recommend using the subdomain approach instead to avoid this class of issue. ### Proxying to a Vue app Similar to the situation with React apps, you have to make a few modifications to proxy a Vue app. 1. add `vue.config.js` 2. update the values to match this (you can use any free port): ```js module.exports = { devServer: { port: 3454, sockPath: "sockjs-node", }, publicPath: "/absproxy/3454", } ``` 3. access app at `/absproxy/3454` e.g. `http://localhost:8080/absproxy/3454` Read more about `publicPath` in the [Vue.js docs](https://cli.vuejs.org/config/#publicpath) ### Proxying to an Angular app In order to use code-server's built-in proxy with Angular, you need to make the following changes in your app: 1. use `` in `src/index.html` 2. add `--serve-path /absproxy/4200` to `ng serve` in your `package.json` For additional context, see [this GitHub Discussion](https://github.com/coder/code-server/discussions/5439#discussioncomment-3371983). ### Proxying to a Svelte app In order to use code-server's built-in proxy with Svelte, you need to make the following changes in your app: 1. Add `svelte.config.js` if you don't already have one 2. Update the values to match this (you can use any free port): ```js const config = { kit: { paths: { base: "/absproxy/5173", }, }, } ``` 3. Access app at `/absproxy/5173/` e.g. `http://localhost:8080/absproxy/5173/ For additional context, see [this Github Issue](https://github.com/sveltejs/kit/issues/2958) ### Prefixing `/absproxy/` with a path This is a case where you need to serve an application via `absproxy` as explained above while serving code-server itself from a path other than the root in your domain. For example: `http://my-code-server.com/user/123/workspace/my-app`. To achieve this result: 1. Start code-server with the switch `--abs-proxy-base-path=/user/123/workspace` 2. Follow one of the instructions above for your framework. ### Preflight requests By default, if you have auth enabled, code-server will authenticate all proxied requests including preflight requests. This can cause issues because preflight requests do not typically include credentials. To allow all preflight requests through the proxy without authentication, use `--skip-auth-preflight`. ## Internationalization and customization code-server allows you to provide a JSON file to configure certain strings. This can be used for both internationalization and customization. Create a JSON file with your custom strings: ```json { "WELCOME": "Welcome to {{app}}", "LOGIN_TITLE": "{{app}} Access Portal", "LOGIN_BELOW": "Please log in to continue", "PASSWORD_PLACEHOLDER": "Enter Password" } ``` Then reference the file: ```shell code-server --i18n /path/to/custom-strings.json ``` Or this can be done in the config file: ```yaml i18n: /path/to/custom-strings.json ``` You can combine this with the `--locale` flag to configure language support for both code-server and VS Code in cases where code-server has no support but VS Code does. If you are using this for internationalization, please consider sending us a pull request to contribute it to `src/node/i18n/locales`. ### Available keys and placeholders Refer to [../src/node/i18n/locales/en.json](../src/node/i18n/locales/en.json) for a full list of the available keys for translations. Note that the only placeholders supported for each key are the ones used in the default string. The `--app-name` flag controls the `{{app}}` placeholder in templates. If you want to change the name, you can either: 1. Set `--app-name` (potentially alongside `--i18n`) 2. Use `--i18n` and hardcode the name in your strings ### Legacy flag The `--welcome-text` flag is now deprecated. Use the `WELCOME` key instead. --- # Coder Source: https://coder.com/docs/code-server/coder # Coder To install and run code-server in a Coder workspace, we suggest using the `install.sh` script in your template like so: ```terraform resource "coder_agent" "dev" { arch = "amd64" os = "linux" startup_script = < # iPad - [Using the code-server progressive web app (PWA)](#using-the-code-server-progressive-web-app-pwa) - [Access code-server using Servediter](#access-code-server-using-servediter) - [Raspberry Pi USB-C network](#raspberry-pi-usb-c-network) - [Recommendations](#recommendations) - [Known issues](#known-issues) - [Workaround for issue with `ctrl+c` not stopping a running process in the terminal](#workaround-for-issue-with-ctrlc-not-stopping-a-running-process-in-the-terminal) - [Access code-server with a self-signed certificate on an iPad](#access-code-server-with-a-self-signed-certificate-on-an-ipad) - [Certificate requirements](#certificate-requirements) - [Sharing a self-signed certificate with an iPad](#sharing-a-self-signed-certificate-with-an-ipad) Once you've installed code-server, you can access it from an iPad. ## Using the code-server progressive web app (PWA) To use code-server on an iPad, we recommend installing the code-server progressive web app (PWA): 1. Open code-server in Safari. 2. Click the **Share** icon. 3. Click **Add to Home Screen**. You can now open code-server from the Home screen, and when you do, you'll be using the PWA. Running code-server as a PWA gets you more screen real estate and access to top-level keyboard shortcuts since its running like a native app. For example, you can use `cmd+w` to close an active file in the workbench. You can add this to `keybindings.json`: 1. Open code-server 2. Go to **Command Palette** > **Open Keyboard Shortcuts (JSON)** 3. Add the following to `keybindings.json` ```json { "key": "cmd+w", "command": "workbench.action.closeActiveEditor" } ``` 4. Test the command by using `cmd+w` to close an active file. ## Access code-server using Servediter If you are unable to get the self-signed certificate working, or you do not have a domain name to use, you can use [Servediter for code-server](https://apps.apple.com/us/app/servediter-for-code-server/id1504491325). > Servediter for code-server is **not** officially supported by the code-server team! To use Servediter: 1. Download the app from the App Store. 2. When prompted, provide your server information. If you are running a local server or a [Raspberry Pi connected via USB-C](#raspberry-pi-usb-c-network), you will input your settings into **Self Hosted Server**. ## Raspberry Pi USB-C network We've heard of users having great success using code-server on an iPad connected to a Raspberry Pi via USB-C (the Raspberry Pi provides both power and direct network access). Setting this up requires you to turn on **Network over USB-C** on the Raspberry Pi, then continuing with code-server as usual on the iPad. For more information, see: - [General introduction to Pi as an iPad accessory](https://www.youtube.com/watch?v=IR6sDcKo3V8) - [iPad with Pi FAQ](https://www.youtube.com/watch?v=SPSlyqo5Q2Q) - [Technical guide to connecting a Raspberry Pi to an iPad](https://www.geeky-gadgets.com/connect-a-raspberry-pi-4-to-an-ipad-pro-21-01-2020/) You may also find the following tips from [Acker Apple](http://github.com/ackerapple/) helpful: > Here are my keys to success. I bought a 4" touch screen with fan included that > attaches as a case to the Pi. I use the touch screen for anytime I have > connection issues, otherwise I turn off the Pi screen. I gave my Pi a network > name so I can easily connect at home on wifi or when on go with 1 usb-c cable > that supplys both power and network connectivity. Lastly, not all usb-c cables > are equal and not all will work so try different usb-c cables if you are going > mad (confirm over wifi first then move to cable). ## Recommendations Once you can access code-server on your iPad, you may find the following tips and tricks helpful: - Use multi-task mode to make code changes and see the browser at the same time - This prevents the iOS background from dropping an app's state if you are switching between code-server and browser (with both in full-screen) - Be sure you are using the debug/terminal that is built into VS Code so that you don’t need another terminal app running - This also prevents switching between full screen apps and losing your view due to iOS' background app memory management ## Known issues - Getting self-signed certificates to work [is an involved process](#access-code-server-with-a-self-signed-certificate-on-an-ipad) - Keyboard issues: - The keyboard disappear sometimes [#979](https://github.com/coder/code-server/issues/979) - Some expectations regarding shortcuts may not be met: - `cmd + n` opens new browser window instead of new file, and it's difficult to set alternative as a workaround - In general, expect to edit your keyboard shortcuts - There's no escape key by default on the Magic Keyboard, so most users set the globe key to be an escape key - Trackpad scrolling does not work on iPadOS < 14.5 ([#1455](https://github.com/coder/code-server/issues/1455)) - [WebKit fix](https://bugs.webkit.org/show_bug.cgi?id=210071#c13) - Keyboard may lose focus in Safari / split view [#4182](https://github.com/coder/code-server/issues/4182) - Terminal text does not appear by default [#3824](https://github.com/coder/code-server/issues/3824) - Copy & paste in terminal does not work well with keyboard shortcuts [#3491](https://github.com/coder/code-server/issues/3491) - `ctrl+c` does not stop a long-running process in the browser - Tracking upstream issue here: [#114009](https://github.com/microsoft/vscode/issues/114009) - See [workaround](#ctrl-c-workaround) Additionally, see [issues in the code-server repo that are tagged with the `os-ios` label](https://github.com/coder/code-server/issues?q=is%3Aopen+is%3Aissue+label%3Aos-ios) for more information. ### Workaround for issue with `ctrl+c` not stopping a running process in the terminal This's currently an issue with `ctrl+c` not stopping a running process in the integrated terminal. We have filed an issue upstream and are tracking [here](https://github.com/microsoft/vscode/issues/114009). In the meantime, you can manually define a shortcut as a workaround: 1. Open the Command Palette 2. Look for **Preferences: Open Keyboard Shortcuts (JSON)** 3. Add the following snippet: ```json { "key": "ctrl+c", "command": "workbench.action.terminal.sendSequence", "args": { "text": "\u0003" }, "when": "terminalFocus" } ``` _Source: [StackOverflow](https://stackoverflow.com/a/52735954/3015595)_ ## Access code-server with a self-signed certificate on an iPad If you've installed code-server and are [running it with a self-signed certificate](./guide.md#using-a-self-signed-certificate), you may see multiple security warnings from Safari. To fix this, you'll need to install the self-signed certificate generated by code-server as a profile on your device (you'll also need to do this to enable WebSocket connections). ### Certificate requirements - We're assuming that you're using the self-signed certificate code-server generates for you (if not, make sure that your certificate [abides by the guidelines issued by Apple](https://support.apple.com/en-us/HT210176)). - We've noticed that the certificate has to include `basicConstraints=CA:true`. - Your certificate must have a subject alt name that matches the hostname you'll use to access code-server from the iPad. You can pass this name to code-server so that it generates the certificate correctly using `--cert-host`. ### Sharing a self-signed certificate with an iPad To share a self-signed certificate with an iPad: 1. Get the location of the certificate code-server generated; code-server prints the certificate's location in its logs: ```console [2020-10-30T08:55:45.139Z] info - Using generated certificate and key for HTTPS: ~/.local/share/code-server/mymbp_local.crt ``` 2. Send the certificate to the iPad, either by emailing it to yourself or using Apple's Airdrop feature. 3. Open the `*.crt` file so that you're prompted to go into Settings to install. 4. Go to **Settings** > **General** > **Profile**, and select the profile. Tap **Install**. 5. Go to **Settings** > **About** > **Certificate Trust Settings** and [enable full trust for your certificate](https://support.apple.com/en-us/HT204477). You should be able to access code-server without all of Safari's warnings now. **warning**: Your iPad must access code-server via a domain name. It could be local DNS like `mymacbookpro.local`, but it must be a domain name. Otherwise, Safari will not allow WebSockets connections. --- # Termux Source: https://coder.com/docs/code-server/termux # Termux - [Install](#install) - [NPM Installation](#npm-installation) - [Upgrade](#upgrade) - [Known Issues](#known-issues) - [Git won't work in `/sdcard`](#git-wont-work-in-sdcard) - [Many extensions including language packs fail to install](#many-extensions-including-language-packs-fail-to-install) - [Extra](#extra) - [Keyboard Shortcuts and Tab Key](#keyboard-shortcuts-and-tab-key) - [Create a new user](#create-a-new-user) - [Install Go](#install-go) - [Install Python](#install-python) ## Install 1. Get [Termux](https://f-droid.org/en/packages/com.termux/) from **F-Droid**. 2. Run `pkg install tur-repo` 3. Run `pkg install code-server` 4. You can now start code server by simply running `code-server`. ## NPM Installation 1. Get [Termux](https://f-droid.org/en/packages/com.termux/) from **F-Droid**. 2. We will now change using the following command. ```sh termux-change-repo ``` Now select `Main Repository` then change repo to `Mirrors by Grimler Hosted on grimler.se`. 3. After successfully updating of repository update and upgrade all the packages by the following command ```sh pkg update pkg upgrade -y ``` 4. Now let's install requirement dependancy. ```sh pkg install -y \ build-essential \ binutils \ pkg-config \ python3 \ nodejs-lts npm config set python python3 node -v ``` you will get Node version `v22` 5. Now install code-server following our guide on [installing with npm](./npm.md) 6. Congratulation code-server is installed on your device using the following command. ```sh code-server --auth none ``` 7. If already installed then use the following command for upgradation. ``` npm update --global code-server ``` ## Upgrade 1. Remove all previous installs `rm -rf ~/.local/lib/code-server-*` 2. Run the install script again `curl -fsSL https://code-server.dev/install.sh | sh` ## Known Issues ### Git won't work in `/sdcard` Issue : Using git in the `/sdcard` directory will fail during cloning/commit/staging/etc...\ Fix : None\ Potential Workaround : 1. Create a soft-link from the debian-fs to your folder in `/sdcard` 2. Use git from termux (preferred) ### Many extensions including language packs fail to install Issue: Android is not seen as a Linux environment but as a separate, unsupported platform, so code-server only allows [Web Extensions](https://code.visualstudio.com/api/extension-guides/web-extensions), refusing to download extensions that run on the server.\ Fix: None\ Potential workarounds : Either - Manually download extensions as `.vsix` file and install them via `Extensions: Install from VSIX...` in the Command Palette. - Use an override to pretend the platform is Linux: Create a JS script that patches `process.platform`: ```js // android-as-linux.js Object.defineProperty(process, "platform", { get() { return "linux" }, }) ``` Then use Node's `--require` option to make sure it is loaded before `code-server` starts: ```sh NODE_OPTIONS="--require /path/to/android-as-linux.js" code-server ``` ⚠️ Note that Android and Linux are not 100% compatible, so use these workarounds at your own risk. Extensions that have native dependencies other than Node or that directly interact with the OS might cause issues. ## Extra ### Keyboard Shortcuts and Tab Key In order to support the tab key and use keyboard shortcuts, add this to your settings.json: ```json { "keyboard.dispatch": "keyCode" } ``` ### Create a new user To create a new user follow these simple steps - 1. Create a new user by running `useradd -m`. 2. Change the password by running `passwd `. 3. Give your new user sudo access by running `visudo`, scroll down to `User privilege specification` and add the following line after root `username ALL=(ALL:ALL) ALL`. 4. Now edit the `/etc/passwd` file with your command line editor of choice and at the end of the line that specifies your user change `/bin/sh` to `/bin/bash`. 5. Now switch users by running `su - ` - Remember the `-` betweeen `su` and username is required to execute `/etc/profile`,\ since `/etc/profile` may have some necessary things to be executed you should always add a `-`. ### Install Go > From https://golang.org/doc/install 1. Go to https://golang.org/dl/ and copy the download link for `linux arm` and run the following: ```bash wget download_link ``` 2. Extract the downloaded archive. (This step will erase all previous GO installs, make sure to create a backup if you have previously installed GO) ```bash rm -rf /usr/local/go && tar -C /usr/local -xzf archive_name ``` 3. Run `nano /etc/profile` and add the following line `export PATH=$PATH:/usr/local/go/bin`. 4. Now run `exit` (depending on if you have switched users or not, you may have to run `exit` multiple times to get to normal termux shell) and start Debian again. 5. Check if your install was successful by running `go version` ### Install Python > Run these commands as root 1. Run the following commands to install required packages to build python: ```bash sudo apt-get update sudo apt-get install make build-essential libssl-dev zlib1g-dev \ libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \ libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev ``` 2. Install [pyenv](https://github.com/pyenv/pyenv/) from [pyenv-installer](https://github.com/pyenv/pyenv-installer) by running: ```bash curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash ``` 3. Run `nano /etc/profile` and add the following: ```bash export PYENV_ROOT="/root/.pyenv" export PATH="/root/.pyenv/bin:$PATH" eval "$(pyenv init --path)" eval "$(pyenv virtualenv-init -)" ``` 4. Exit and start Debian again. 5. Run `pyenv versions` to list all installable versions. 6. Run `pyenv install version` to install the desired python version. > The build process may take some time (an hour or 2 depending on your device). 7. Run `touch /root/.pyenv/version && echo "your_version_here" > /root/.pyenv/version` 8. (You may have to start Debian again) Run `python3 -V` to verify if PATH works or not. > If `python3` doesn't work but pyenv says that the install was successful in step 6 then try running `$PYENV_ROOT/versions/your_version/bin/python3`. --- # iOS Source: https://coder.com/docs/code-server/ios # Using code-server on iOS with iSH 1. Install iSH from the [App Store](https://apps.apple.com/us/app/ish-shell/id1436902243) 2. Install `curl` and `nano` with `apk add curl nano` 3. Configure iSH to use an earlier version of NodeJS with `nano /etc/apk/repositories` and edit `v3.14` to `v3.12` on both repository links. 4. Install `nodejs` and `npm` with `apk add nodejs npm` 5. Install code-server with `curl -fsSL https://code-server.dev/install.sh | sh` 6. Run code-server with `code-server` 7. Access on localhost:8080 in your browser --- # Android Source: https://coder.com/docs/code-server/android # Running code-server using UserLAnd 1. Install UserLAnd from [Google Play](https://play.google.com/store/apps/details?id=tech.ula&hl=en_US&gl=US) 2. Install an Ubuntu VM 3. Start app 4. Install Node.js and `curl` using `sudo apt install nodejs npm curl -y` 5. Install `nvm`: ```shell curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash ``` 6. Exit the terminal using `exit` and then reopen the terminal 7. Install and use Node.js 22: ```shell nvm install 22 nvm use 22 ``` 8. Install code-server globally on device with: `npm install --global code-server` 9. Run code-server with `code-server` 10. Access on localhost:8080 in your browser # Running code-server using Nix-on-Droid 1. Install Nix-on-Droid from [F-Droid](https://f-droid.org/packages/com.termux.nix/) 2. Start app 3. Spawn a shell with code-server by running `nix-shell -p code-server` 4. Run code-server with `code-server` 5. Access on localhost:8080 in your browser --- # Collaboration Source: https://coder.com/docs/code-server/collaboration # Collaboration With third-party extensions, you can use code-server to collaborate with other developers in real time. ## Code sharing using Duckly [Duckly](https://duckly.com/) allows you to share your code in real-time even with people using different IDEs (like JetBrains and VSCode). - Cross-IDE support, - Real-time typing, - P2P encrypted, - Voice and audio chat, - Terminal sharing ### Installing the Duckly Extension Duckly uses an extension to provide real time sharing features 1. Install the Duckly extension from OpenVSX on `code-server`. ```bash SERVICE_URL=https://open-vsx.org/vscode/gallery \ ITEM_URL=https://open-vsx.org/vscode/item \ code-server --install-extension gitduck.code-streaming ``` 2. Refresh you `code-server` window. You should now be able to see the Duckly extension. ### Sharing with Duckly As `code-server` is based on VS Code, you can follow the steps described on Duckly's [Pair programming with VS Code](https://duckly.com/tools/vscode) page and skip the installation step. ## Code sharing using CodeTogether [CodeTogether](https://www.codetogether.com/) is a real-time cross-IDE replacement for Microsoft Live Share providing: - Cross-IDE support - between VS Code, Eclipse, IntelliJ and IDEs based on them (browser or desktop) - Real-time editing - shared or individual cursors for pairing, mobbing, swarming, or whatever - P2P encrypted - servers can't decrypt the traffic ([Security Details](https://codetogether.com/download/security/)) - SaaS or [On-premises](https://codetogether.com/on-premises/) options - Shared servers, terminals, and consoles - Unit Testing - with support for Red, Green, Refactor TDD - Joining via a web browser or your preferred IDE - Free unlimited 1 hour sessions with 4 participants - Multiple plans including [free or paid options](https://www.codetogether.com/pricing/) ### Installing the CodeTogether extension 1. Install the CodeTogether extension from OpenVSX on `code-server`. ```sh SERVICE_URL=https://open-vsx.org/vscode/gallery \ ITEM_URL=https://open-vsx.org/vscode/item \ code-server --install-extension genuitecllc.codetogether ``` 2. CodeTogether requires VS Code's proposed API to run. Start code-server with the following flag: ```sh code-server --enable-proposed-api genuitecllc.codetogether ``` Another option would be to add a value in code-server's [config file](https://coder.com/docs/code-server/latest/FAQ#how-does-the-config-file-work). 3. Refresh code-server and navigate to the CodeTogether icon in the sidebar to host or join a coding session. --- # Upgrade Source: https://coder.com/docs/code-server/upgrade # Upgrade To upgrade code-server, install the new version over the old version. All user data is in `~/.local/share/code-server`, so they are preserved between installations. --- # FAQ Source: https://coder.com/docs/code-server/FAQ # FAQ - [Questions?](#questions) - [How should I expose code-server to the internet?](#how-should-i-expose-code-server-to-the-internet) - [Can I use code-server on the iPad?](#can-i-use-code-server-on-the-ipad) - [How does the config file work?](#how-does-the-config-file-work) - [How do I make my keyboard shortcuts work?](#how-do-i-make-my-keyboard-shortcuts-work) - [Why can't code-server use Microsoft's extension marketplace?](#why-cant-code-server-use-microsofts-extension-marketplace) - [How can I request an extension that's missing from the marketplace?](#how-can-i-request-an-extension-thats-missing-from-the-marketplace) - [How do I install an extension?](#how-do-i-install-an-extension) - [How do I install an extension manually?](#how-do-i-install-an-extension-manually) - [How do I use my own extensions marketplace?](#how-do-i-use-my-own-extensions-marketplace) - [Where are extensions stored?](#where-are-extensions-stored) - [Where is VS Code configuration stored?](#where-is-vs-code-configuration-stored) - [How can I reuse my VS Code configuration?](#how-can-i-reuse-my-vs-code-configuration) - [How does code-server decide what workspace or folder to open?](#how-does-code-server-decide-what-workspace-or-folder-to-open) - [How do I access my Documents/Downloads/Desktop folders in code-server on macOS?](#how-do-i-access-my-documentsdownloadsdesktop-folders-in-code-server-on-macos) - [How do I direct server-side requests through a proxy?](#how-do-i-direct-server-side-requests-through-a-proxy) - [How do I debug issues with code-server?](#how-do-i-debug-issues-with-code-server) - [What is the healthz endpoint?](#what-is-the-healthz-endpoint) - [What is the heartbeat file?](#what-is-the-heartbeat-file) - [How do I change the reconnection grace time?](#how-do-i-change-the-reconnection-grace-time) - [How do I change the password?](#how-do-i-change-the-password) - [Can I store my password hashed?](#can-i-store-my-password-hashed) - [Is multi-tenancy possible?](#is-multi-tenancy-possible) - [Can I use Docker in a code-server container?](#can-i-use-docker-in-a-code-server-container) - [How do I disable telemetry?](#how-do-i-disable-telemetry) - [What's the difference between code-server and Coder?](#whats-the-difference-between-code-server-and-coder) - [What's the difference between code-server and Theia?](#whats-the-difference-between-code-server-and-theia) - [What's the difference between code-server and OpenVSCode-Server?](#whats-the-difference-between-code-server-and-openvscode-server) - [What's the difference between code-server and GitHub Codespaces?](#whats-the-difference-between-code-server-and-github-codespaces) - [What's the difference between code-server and VS Code web?](#whats-the-difference-between-code-server-and-vs-code-web) - [Does code-server have any security login validation?](#does-code-server-have-any-security-login-validation) - [Are there community projects involving code-server?](#are-there-community-projects-involving-code-server) - [How do I change the port?](#how-do-i-change-the-port) - [How do I hide the coder/coder promotion in Help: Getting Started?](#how-do-i-hide-the-codercoder-promotion-in-help-getting-started) - [How do I disable the proxy?](#how-do-i-disable-the-proxy) - [How do I disable file download?](#how-do-i-disable-file-download) - [Why do web views not work?](#why-do-web-views-not-work) ## Questions? Please file all questions and support requests at . ## How should I expose code-server to the internet? Please see [our instructions on exposing code-server safely to the internet](./guide.md). ## Can I use code-server on the iPad? See [iPad](./ipad.md) for information on using code-server on the iPad. ## How does the config file work? When `code-server` starts up, it creates a default config file in `~/.config/code-server/config.yaml`: ```yaml bind-addr: 127.0.0.1:8080 auth: password password: mew...22 # Randomly generated for each config.yaml cert: false ``` The default config defines the following behavior: - Listen on the loopback IP port 8080 - Enable password authorization - Do not use TLS Each key in the file maps directly to a `code-server` flag (run `code-server --help` to see a listing of all the flags). Any flags passed to `code-server` will take priority over the config file. You can change the config file's location using the `--config` flag or `$CODE_SERVER_CONFIG` environment variable. The default location respects `$XDG_CONFIG_HOME`. ## How do I make my keyboard shortcuts work? Many shortcuts will not work by default, since they'll be "caught" by the browser. If you use Chrome, you can work around this by installing the progressive web app (PWA): 1. Start the editor 2. Click the **plus** icon in the URL toolbar to install the PWA If you use Firefox, you can use the appropriate extension to install PWA. 1. Go to the installation [website](https://addons.mozilla.org/en-US/firefox/addon/pwas-for-firefox/) of the add-on 2. Add the add-on to Firefox 3. Follow the os-specific instructions on how to install the runtime counterpart For other browsers, you'll have to remap keybindings for shortcuts to work. ## Why can't code-server use Microsoft's extension marketplace? Though code-server takes the open-source core of VS Code and allows you to run it in the browser, it is not entirely equivalent to Microsoft's VS Code. One major difference is in regards to extensions and the marketplace. The core of VS code is open source, while the marketplace and many published Microsoft extensions are not. Furthermore, Microsoft prohibits the use of any non-Microsoft VS Code from accessing their marketplace. Per the [Terms of Service](https://cdn.vsassets.io/v/M146_20190123.39/_content/Microsoft-Visual-Studio-Marketplace-Terms-of-Use.pdf): > Marketplace Offerings are intended for use only with Visual Studio Products > and Services, and you may only install and use Marketplace Offerings with > Visual Studio Products and Services. Because of this, we can't offer any extensions on Microsoft's marketplace. Instead, we use the [Open-VSX extension gallery](https://open-vsx.org), which is also used by various other forks. It isn't perfect, but its getting better by the day with more and more extensions. We also offer our own marketplace for open source extensions, but plan to deprecate it at a future date and completely migrate to Open-VSX. These are the closed-source extensions that are presently unavailable: 1. [Live Share](https://visualstudio.microsoft.com/services/live-share). We may implement something similar (see [#33](https://github.com/coder/code-server/issues/33)) 1. [Remote Extensions (SSH, Containers, WSL)](https://github.com/microsoft/vscode-remote-release). We may implement these again at some point, see ([#1315](https://github.com/coder/code-server/issues/1315)). For more about the closed source portions of VS Code, see [vscodium/vscodium](https://github.com/VSCodium/vscodium#why-does-this-exist). ## How can I request an extension that's missing from the marketplace? To add an extension to Open-VSX, please see [open-vsx/publish-extensions](https://github.com/open-vsx/publish-extensions). We no longer plan to add new extensions to our legacy extension gallery. ## How do I install an extension? You can install extensions from the marketplace using the extensions sidebar in code-server or from the command line: ```console code-server --install-extension # example: code-server --install-extension wesbos.theme-cobalt2 # From the Coder extension marketplace code-server --install-extension ms-python.python # From a downloaded VSIX on the file system code-server --install-extension downloaded-ms-python.python.vsix ``` ## How do I install an extension manually? If there's an extension unavailable in the marketplace or an extension that doesn't work, you can download the VSIX from its GitHub releases or build it yourself. Once you have downloaded the VSIX to the remote machine, you can either: - Run the **Extensions: Install from VSIX** command in the Command Palette. - Run `code-server --install-extension ` in the terminal You can also download extensions using the command line. For instance, downloading from OpenVSX can be done like this: ```shell code-server --install-extension ``` ## How do I use my own extensions marketplace? If you own a marketplace that implements the VS Code Extension Gallery API, you can point code-server to it by setting `$EXTENSIONS_GALLERY`. This corresponds directly with the `extensionsGallery` entry in in VS Code's `product.json`. For example: ```bash export EXTENSIONS_GALLERY='{"serviceUrl": "https://my-extensions/api"}' ``` Though you can technically use Microsoft's marketplace in this manner, we strongly discourage you from doing so since this is [against their Terms of Use](#why-cant-code-server-use-microsofts-extension-marketplace). For further information, see [this discussion](https://github.com/microsoft/vscode/issues/31168#issue-244533026) regarding the use of the Microsoft URLs in forks, as well as [VSCodium's docs](https://github.com/VSCodium/vscodium/blob/master/DOCS.md#extensions--marketplace). ## Where are extensions stored? Extensions are stored in `~/.local/share/code-server/extensions` by default. On Linux and macOS if you set the `XDG_DATA_HOME` environment variable, the extensions directory will be `$XDG_DATA_HOME/code-server/extensions`. In general, we try to follow the XDG directory spec. ## Where is VS Code configuration stored? VS Code configuration such as settings and keybindings are stored in `~/.local/share/code-server` by default. On Linux and macOS if you set the `XDG_DATA_HOME` environment variable, the data directory will be `$XDG_DATA_HOME/code-server`. In general, we try to follow the XDG directory spec. ## How can I reuse my VS Code configuration? You can use the [Settings Sync](https://marketplace.visualstudio.com/items?itemName=Shan.code-settings-sync) extension for this purpose. Alternatively, you can also pass `--user-data-dir ~/.vscode` or copy `~/.vscode` into `~/.local/share/code-server` to reuse your existing VS Code extensions and configuration. ## How does code-server decide what workspace or folder to open? code-server tries the following in this order: 1. The `workspace` query parameter 2. The `folder` query parameter 3. The workspace or directory passed via the command line 4. The last opened workspace or directory ## How do I access my Documents/Downloads/Desktop folders in code-server on macOS? Newer versions of macOS require permission through a non-UNIX mechanism for code-server to access the Desktop, Documents, Pictures, Downloads, and other folders. You may have to give Node.js full disk access, since it doesn't implement any of the macOS permission request features natively: 1. Find where Node.js is installed on your machine ```console $ which node /usr/local/bin/node ``` 2. Grant Node.js full disk access. Open **System Preferences** > **Security & Privacy** > **Privacy** > **Full Disk Access**. Then, click the 🔒 to unlock, click **+**, and select the Node.js binary you located in the previous step. See [#2794](https://github.com/coder/code-server/issues/2794) for additional context. ## How do I direct server-side requests through a proxy? > code-server proxies only server-side requests. To direct server-side requests through a proxy, code-server supports the following environment variables: - `$HTTP_PROXY` - `$HTTPS_PROXY` - `$NO_PROXY` ```sh export HTTP_PROXY=https://134.8.5.4 export HTTPS_PROXY=https://134.8.5.4 # Now all of code-server's server side requests will go through # https://134.8.5.4 first. code-server ``` - See [proxy-from-env](https://www.npmjs.com/package/proxy-from-env#environment-variables) for a detailed reference on these environment variables and their syntax (note that code-server only uses the `http` and `https` protocols). - See [proxy-agent](https://www.npmjs.com/package/proxy-agent) for information on on the supported proxy protocols. ## How do I debug issues with code-server? First, run code-server with the `debug` logging (or `trace` to be really thorough) by setting the `--log` flag or the `LOG_LEVEL` environment variable. `-vvv` and `--verbose` are aliases for `--log trace`. First, run code-server with `debug` logging (or `trace` logging for more thorough messages) by setting the `--log` flag or the `LOG_LEVEL` environment variable. ```text code-server --log debug ``` > Note that the `-vvv` and `--verbose` flags are aliases for `--log trace`. Next, replicate the issue you're having so that you can collect logging information from the following places: 1. The most recent files from `~/.local/share/code-server/coder-logs` 2. The browser console 3. The browser network tab Additionally, collecting core dumps (you may need to enable them first) if code-server crashes can be helpful. ## What is the healthz endpoint? You can use the `/healthz` endpoint exposed by code-server to check whether code-server is running without triggering a heartbeat. The response includes a status (e.g., `alive` or `expired`) and a timestamp for the last heartbeat (the default is `0`). ```json { "status": "alive", "lastHeartbeat": 1599166210566 } ``` This endpoint doesn't require authentication. ## What is the heartbeat file? As long as there is an active browser connection, code-server touches `~/.local/share/code-server/heartbeat` once a minute. If you want to shutdown code-server if there hasn't been an active connection after a predetermined amount of time, you can use the --idle-timeout-seconds flag or set an `CODE_SERVER_IDLE_TIMEOUT_SECONDS` environment variable. ## How do I change the reconnection grace time? Pass `--reconnection-grace-time ` to `code-server`, set `CODE_SERVER_RECONNECTION_GRACE_TIME=`, or add `reconnection-grace-time: ` to `~/.config/code-server/config.yaml`. The default is `10800` (3 hours). If a client stays disconnected longer than this, it must reload the window. ## How do I change the password? Edit the `password` field in the code-server config file at `~/.config/code-server/config.yaml`, then restart code-server: ```bash sudo systemctl restart code-server@$USER ``` ## Can I store my password hashed? Yes, you can do so by setting the value of `hashed-password` instead of `password`. Generate the hash with: ```shell echo -n "thisismypassword" | npx argon2-cli -e $argon2i$v=19$m=4096,t=3,p=1$wst5qhbgk2lu1ih4dmuxvg$ls1alrvdiwtvzhwnzcm1dugg+5dto3dt1d5v9xtlws4 ``` Replace `thisismypassword` with your actual password and **remember to put it inside quotes**! For example: ```yaml auth: password hashed-password: "$argon2i$v=19$m=4096,t=3,p=1$wST5QhBgk2lu1ih4DMuxvg$LS1alrVdIWtvZHwnzCM1DUGg+5DTO3Dt1d5v9XtLws4" ``` The `hashed-password` field takes precedence over `password`. If you're using Docker Compose file, in order to make this work, you need to change all the single $ to $$. For example: ```yaml - HASHED_PASSWORD=$$argon2i$$v=19$$m=4096,t=3,p=1$$wST5QhBgk2lu1ih4DMuxvg$$LS1alrVdIWtvZHwnzCM1DUGg+5DTO3Dt1d5v9XtLws4 ``` ## Is multi-tenancy possible? If you want to run multiple code-servers on shared infrastructure, we recommend using virtual machines (provide one VM per user). This will easily allow users to run a Docker daemon. If you want to use Kubernetes, you'll want to use [kubevirt](https://kubevirt.io) or [sysbox](https://github.com/nestybox/sysbox) to give each user a VM-like experience instead of just a container. ## Can I use Docker in a code-server container? If you'd like to access Docker inside of code-server, mount the Docker socket in from `/var/run/docker.sock`. Then, install the Docker CLI in the code-server container, and you should be able to access the daemon. You can even make volume mounts work. Let's say you want to run a container and mount into `/home/coder/myproject` from inside the `code-server` container. You need to make sure the Docker daemon's `/home/coder/myproject` is the same as the one mounted inside the `code-server` container, and the mount will work. If you want Docker enabled when deploying on Kubernetes, look at the `values.yaml` file for the 3 fields: `extraVars`, `lifecycle.postStart`, and `extraContainers`. ## How do I disable telemetry? Use the `--disable-telemetry` flag to disable telemetry. > We use the data collected only to improve code-server. ## What's the difference between code-server and Coder? code-server and Coder are both applications that can be installed on any machine. The main difference is who they serve. Out of the box, code-server is simply VS Code in the browser while Coder is a tool for provisioning remote development environments via Terraform. code-server was built for individuals while Coder was built for teams. In Coder, you create Workspaces which can have applications like code-server. If you're looking for a team solution, you should reach for [Coder](https://github.com/coder/coder). ## What's the difference between code-server and Theia? At a high level, code-server is a patched fork of VS Code that runs in the browser whereas Theia takes some parts of VS Code but is an entirely different editor. [Theia](https://github.com/eclipse-theia/theia) is a browser IDE loosely based on VS Code. It uses the same text editor library ([Monaco](https://github.com/Microsoft/monaco-editor)) and extension API, but everything else is different. Theia also uses [Open VSX](https://open-vsx.org) for extensions. Theia doesn't allow you to reuse your existing VS Code config. ## What's the difference between code-server and OpenVSCode-Server? code-server and OpenVSCode-Server both allow you to access VS Code via a browser. OpenVSCode-Server is a direct fork of VS Code with changes comitted directly while code-server pulls VS Code in via a submodule and makes changes via patch files. However, OpenVSCode-Server is scoped at only making VS Code available as-is in the web browser. code-server contains additional changes to make the self-hosted experience better (see the next section for details). ## What's the difference between code-server and GitHub Codespaces? Both code-server and GitHub Codespaces allow you to access VS Code via a browser. GitHub Codespaces, however, is a closed-source, paid service offered by GitHub and Microsoft. On the other hand, code-server is self-hosted, free, open-source, and can be run on any machine with few limitations. Specific changes include: - Password authentication - The ability to host at sub-paths - Self-contained web views that do not call out to Microsoft's servers - The ability to use your own marketplace and collect your own telemetry - Built-in proxy for accessing ports on the remote machine integrated into VS Code's ports panel - Settings are stored on disk like desktop VS Code, instead of in browser storage (note that state is still stored in browser storage). - Wrapper process that spawns VS Code on-demand and has a separate CLI - Notification when updates are available - [Some other things](https://github.com/coder/code-server/tree/main/patches) Some of these changes appear very unlikely to ever be adopted by Microsoft. Some may make their way upstream, further closing the gap, but at the moment it looks like there will always be some subtle differences. ## What's the difference between code-server and VS Code web? VS Code web (which can be ran using `code serve-web`) has the same differences as the Codespaces section above. VS Code web can be a better choice if you need access to the official Microsoft marketplace. ## Does code-server have any security login validation? code-server supports setting a single password and limits logins to two per minute plus an additional twelve per hour. ## Are there community projects involving code-server? Visit the [awesome-code-server](https://github.com/coder/awesome-code-server) repository to view community projects and guides with code-server! Feel free to add your own! ## How do I change the port? There are two ways to change the port on which code-server runs: 1. with an environment variable e.g. `PORT=3000 code-server` 2. using the flag `--bind-addr` e.g. `code-server --bind-addr localhost:3000` ## How do I hide the coder/coder promotion in Help: Getting Started? You can pass the flag `--disable-getting-started-override` to `code-server` or you can set the environment variable `CS_DISABLE_GETTING_STARTED_OVERRIDE=1` or `CS_DISABLE_GETTING_STARTED_OVERRIDE=true`. ## How do I disable the proxy? You can pass the flag `--disable-proxy` to `code-server` or you can set the environment variable `CS_DISABLE_PROXY=1` or `CS_DISABLE_PROXY=true`. Note, this option currently only disables the proxy routes to forwarded ports, including the domain and path proxy routes over HTTP and WebSocket; however, it does not disable the automatic port forwarding in the VS Code workbench itself. In other words, user will still see the Ports tab and notifications, but will not be able to actually use access the ports. It is recommended to set `remote.autoForwardPorts` to `false` when using the option. ## How do I disable file download? You can pass the flag `--disable-file-downloads` to `code-server` ## Why do web views not work? Web views rely on service workers, and service workers are only available in a secure context, so most likely the answer is that you are using an insecure context (for example an IP address). If this happens, in the browser log you will see something like: > Error loading webview: Error: Could not register service workers: SecurityError: Failed to register a ServiceWorker for scope with script: An SSL certificate error occurred when fetching the script.. To fix this, you must either: - Access over localhost/127.0.0.1 which is always considered secure. - Use a domain with a real certificate (for example with Let's Encrypt). - Use a trusted self-signed certificate with [mkcert](https://mkcert.dev) (or create and trust a certificate manually). - Disable security if your browser allows it. For example, in Chromium see `chrome://flags/#unsafely-treat-insecure-origin-as-secure` --- # Contributing Source: https://coder.com/docs/code-server/CONTRIBUTING # Contributing - [Requirements](#requirements) - [Linux-specific requirements](#linux-specific-requirements) - [Development workflow](#development-workflow) - [Version updates to Code](#version-updates-to-code) - [Patching Code](#patching-code) - [Build](#build) - [Troubleshooting](#troubleshooting) - [I see "Forbidden access" when I load code-server in the browser](#i-see-forbidden-access-when-i-load-code-server-in-the-browser) - ["Can only have one anonymous define call per script"](#can-only-have-one-anonymous-define-call-per-script) - [Help](#help) - [Test](#test) - [Unit tests](#unit-tests) - [Script tests](#script-tests) - [Integration tests](#integration-tests) - [End-to-end tests](#end-to-end-tests) - [Structure](#structure) - [Modifications to Code](#modifications-to-code) - [Currently Known Issues](#currently-known-issues) ## Requirements The prerequisites for contributing to code-server are almost the same as those for [VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites). Here is what is needed: - `node` v22.x - `git` v2.x or greater - [`git-lfs`](https://git-lfs.github.com) - [`npm`](https://www.npmjs.com/) - Used to install JS packages and run scripts - [`nfpm`](https://nfpm.goreleaser.com/) - Used to build `.deb` and `.rpm` packages - [`jq`](https://stedolan.github.io/jq/) - Used to build code-server releases - [`gnupg`](https://gnupg.org/index.html) - All commits must be signed and verified; see GitHub's [Managing commit signature verification](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification) or follow [this tutorial](https://joeprevite.com/verify-commits-on-github) - `quilt` - Used to manage patches to Code - `rsync` and `unzip` - Used for code-server releases - `bats` - Used to run script unit tests ### Linux-specific requirements If you're developing code-server on Linux, make sure you have installed or install the following dependencies: ```shell sudo apt-get install build-essential g++ libx11-dev libxkbfile-dev libsecret-1-dev libkrb5-dev python-is-python3 ``` These are required by Code. See [their Wiki](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites) for more information. ## Development workflow 1. `git clone https://github.com/coder/code-server.git` - Clone `code-server` 2. `git submodule update --init` - Clone `vscode` submodule 3. `quilt push -a` - Apply patches to the `vscode` submodule. 4. `npm install` - Install dependencies 5. `npm run watch` - Launch code-server localhost:8080. code-server will be live reloaded when changes are made; the browser needs to be refreshed manually. When pulling down changes that include modifications to the patches you will need to apply them with `quilt`. If you pull down changes that update the `vscode` submodule you will need to run `git submodule update --init` and re-apply the patches. When you make a change that affects people deploying the marketplace please update the changelog as part of your PR. Note that building code-server takes a very, very long time, and loading it in the browser in development mode also takes a very, very long time. Display language (Spanish, etc) support only works in a full build; it will not work in development mode. Generally we prefer that PRs be squashed into `main` but you can rebase or merge if it is important to keep the individual commits (make sure to clean up the commits first if you are doing this). ### Version updates to Code 1. Remove any patches with `quilt pop -a`. 2. Update the `lib/vscode` submodule to the desired upstream version branch. 1. `cd lib/vscode && git checkout release/1.66 && cd ../..` 2. `git add lib && git commit -m "chore: update to Code "` 3. Apply the patches one at a time (`quilt push`). If the application succeeds but the lines changed, update the patch with `quilt refresh`. If there are conflicts, then force apply with `quilt push -f`, manually add back the rejected code, then run `quilt refresh`. 4. From the code-server **project root**, run `npm install`. 5. Check the Node.js version that's used by Electron (which is shipped with VS Code. If necessary, update our version of Node.js to match. ### Patching Code 1. You can go through the patch stack with `quilt push` and `quilt pop`. 2. Create a new patch (`quilt new {name}.diff`) or use an existing patch. 3. Add the file(s) you are patching (`quilt add [-P patch] {file}`). A file **must** be added before you make changes to it. 4. Make your changes. Patches do not need to be independent of each other but each patch must result in a working code-server without any broken in-between states otherwise they are difficult to test and modify. 5. Add your changes to the patch (`quilt refresh`) 6. Add a comment in the patch about the reason for the patch and how to reproduce the behavior it fixes or adds. Every patch should have an e2e test as well. ### Build You can build a full production release as follows: ```shell git submodule update --init quilt push -a npm install npm run build VERSION=0.0.0 npm run build:vscode KEEP_MODULES=1 npm run release ``` You can omit `KEEP_MODULES` if you intend to use this in a platform-agnostic way (like for publishing to NPM), but since the VS Code build process does post-processing deletion of the modules, it is recommended to keep the modules when possible, since if you install them later you will have more than is required. `KEEP_MODULES` will also bundle Node and the code-server entry script. Run your build: ```shell ./release/bin/code-server ``` Or if you omitted `KEEP_MODULES`: ```shell cd release npm install --omit=dev node . ``` Then, to package the release: ```shell npm run package ``` > On Linux, the currently running distro will become the minimum supported > version. In our GitHub Actions CI, we use CentOS 8 for maximum compatibility. > If you need your builds to support older distros, run the build commands > inside a Docker container with all the build requirements installed. ### Troubleshooting #### I see "Forbidden access" when I load code-server in the browser This means your patches didn't apply correctly. We have a patch to remove the auth from vanilla Code because we use our own. Try popping off the patches with `quilt pop -a` and reapplying with `quilt push -a`. #### "Can only have one anonymous define call per script" Code might be trying to use a dev or prod HTML in the wrong context. You can try re-running code-server and setting `VSCODE_DEV=1`. ### Help If you get stuck or need help, you can always start a new GitHub Discussion [here](https://github.com/coder/code-server/discussions). One of the maintainers will respond and help you out. ## Test There are four kinds of tests in code-server: 1. Unit tests 2. Script tests 3. Integration tests 4. End-to-end tests ### Unit tests Our unit tests are written in TypeScript and run using [Jest](https://jestjs.io/), the testing framework]. These live under [test/unit](../test/unit). We use unit tests for functions and things that can be tested in isolation. The file structure is modeled closely after `/src` so it's easy for people to know where test files should live. ### Script tests Our script tests are written in bash and run using [bats](https://github.com/bats-core/bats-core). These tests live under `test/scripts`. We use these to test anything related to our scripts (most of which live under `ci`). ### Integration tests These are a work in progress. We build code-server and run tests with `npm run test:integration`, which ensures that code-server builds work on their respective platforms. Our integration tests look at components that rely on one another. For example, testing the CLI requires us to build and package code-server. ### End-to-end tests The end-to-end (e2e) tests are written in TypeScript and run using [Playwright](https://playwright.dev/). These live under [test/e2e](../test/e2e). Before the e2e tests run, we run `globalSetup`, which eliminates the need to log in before each test by preserving the authentication state. Take a look at `codeServer.test.ts` to see how you would use it (see `test.use`). We also have a model where you can create helpers to use within tests. See [models/CodeServer.ts](../test/e2e/models/CodeServer.ts) for an example. ## Structure code-server essentially serves as an HTTP API for logging in and starting a remote Code process. The CLI code is in [src/node](../src/node) and the HTTP routes are implemented in [src/node/routes](../src/node/routes). Most of the meaty parts are in the Code portion of the codebase under [lib/vscode](../lib/vscode), which we describe next. ### Modifications to Code Our modifications to Code can be found in the [patches](../patches) directory. We pull in Code as a submodule pointing to an upstream release branch. In v1 of code-server, we had Code as a submodule and used a single massive patch that split the codebase into a front-end and a server. The front-end consisted of the UI code, while the server ran the extensions and exposed an API to the front-end for file access and all UI needs. Over time, Microsoft added support to Code to run it on the web. They had made the front-end open source, but not the server. As such, code-server v2 (and later) uses the Code front-end and implements the server. We did this by using a Git subtree to fork and modify Code. Microsoft eventually made the server open source and we were able to reduce our changes significantly. Some time later we moved back to a submodule and patches (managed by `quilt` this time instead of the mega-patch). As the web portion of Code continues to mature, we'll be able to shrink and possibly eliminate our patches. In the meantime, upgrading the Code version requires us to ensure that our changes are still applied correctly and work as intended. In the future, we'd like to run Code unit tests against our builds to ensure that features work as expected. > We have [extension docs](../ci/README.md) on the CI and build system. If the functionality you're working on does NOT depend on code from Code, please move it out and into code-server. ### Currently Known Issues - Creating custom Code extensions and debugging them doesn't work - Extension profiling and tips are currently disabled --- # Code of conduct Source: https://coder.com/docs/code-server/CODE_OF_CONDUCT # Contributor Covenant Code of Conduct - [Contributor Covenant Code of Conduct](#contributor-covenant-code-of-conduct) - [Our Pledge](#our-pledge) - [Our Standards](#our-standards) - [Our Responsibilities](#our-responsibilities) - [Scope](#scope) - [Enforcement](#enforcement) - [Attribution](#attribution) # Contributor Covenant Code of Conduct ## Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. ## Our Standards Examples of behavior that contributes to creating a positive environment include: - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members Examples of unacceptable behavior by participants include: - The use of sexualized language or imagery and unwelcome sexual attention or advances - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information, such as a physical or electronic address, without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. ## Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at opensource@coder.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq --- # Maintenance Source: https://coder.com/docs/code-server/MAINTAINING # Maintaining - [Releasing](#releasing) - [Release Candidates](#release-candidates) - [AUR](#aur) - [Docker](#docker) - [nixpkgs](#nixpkgs) - [npm](#npm) - [Testing](#testing) - [Documentation](#documentation) - [Troubleshooting](#troubleshooting) We keep code-server up to date with VS Code releases (there are usually two or three a month) but we are not generally actively developing code-server aside from fixing regressions. Most of the work is keeping on top of issues and discussions. ## Releasing 1. Check that the changelog lists all the important changes. 2. Make sure the changelog entry lists the current version of VS Code. 3. Go to GitHub Actions > Draft release > Run workflow on the commit you want to release. For the version we match VS Code's minor and patch version. The patch number may become temporarily out of sync if we need to put out a patch, but if we make our own minor change then we will not release it until the next minor VS Code release. 4. CI will build an NPM package and platform-specific packages, and upload those to a draft release. 5. Update the resulting draft release with the changelog contents. 6. Publish the draft release after validating it. 7. Update the changelog with the release date and bump the Helm chart version once the Docker images have published. 8. Merge the PR submitted to coder/code-server-aur repo. #### Release Candidates We prefer to do release candidates so the community can test things before a full-blown release. To do this follow the same steps as above but: 1. Add a `-rc.` suffix to the version. 2. When you publish the release select "pre-release". CI will not automatically publish pre-releases. 3. Do not update the chart version or merge in the changelog until the final release. #### AUR We publish to AUR as a package [here](https://aur.archlinux.org/packages/code-server/). This process is manual and can be done by following the steps in [this repo](https://github.com/coder/code-server-aur). #### Docker We publish code-server as a Docker image [here](https://hub.docker.com/r/codercom/code-server), tagging it both with the version and latest. This is currently automated with the release process. #### nixpkgs We publish code-server in nixpkgs but it must be updated manually. #### npm We publish code-server as a npm package [here](https://www.npmjs.com/package/code-server/v/latest). This is currently automated with the release process. ## Testing Our testing structure is laid out under our [Contributing docs](https://coder.com/docs/code-server/latest/CONTRIBUTING#test). If you're ever looking to add more tests, here are a few ways to get started: - run `npm run test:unit` and look at the coverage chart. You'll see all the uncovered lines. This is a good place to start. - look at `test/scripts` to see which scripts are tested. We can always use more tests there. - look at `test/e2e`. We can always use more end-to-end tests. Otherwise, talk to a current maintainer and ask which part of the codebase is lacking most when it comes to tests. ## Documentation ### Troubleshooting Our docs are hosted on [Vercel](https://vercel.com/). Vercel only shows logs in realtime, which means you need to have the logs open in one tab and reproduce your error in another tab. Since our logs are private to Coder the organization, you can only follow these steps if you're a Coder employee. Ask a maintainer for help if you need it. Taking a real scenario, let's say you wanted to troubleshoot [this docs change](https://github.com/coder/code-server/pull/4042). Here is how you would do it: 1. Go to https://vercel.com/codercom/codercom 2. Click "View Function Logs" 3. In a separate tab, open the preview link from github-actions-bot 4. Now look at the function logs and see if there are errors in the logs --- # Triage Source: https://coder.com/docs/code-server/triage # Triage Triaging code-server issues is done with the following issue filter: ```text is:issue is:open no:project sort:created-asc -label:blocked -label:upstream -label:waiting-for-info -label:extension-request ``` This will show issues that: 1. Are open. 1. Have no assigned project. 1. Are not `blocked` or tagged for work by `upstream` (the VS Code core team). If an upstream issue is detrimental to the code-server experience we may fix it in our patch instead of waiting for the VS Code team to fix it. Someone should periodically go through these issues to see if they can be unblocked! 1. Are not labeled `waiting-for-info`. 1. Are not extension requests. ## Triage process 1. If an issue is a question/discussion, it should be converted into a GitHub discussion. 1. Otherwise, give the issue the appropriate labels (feel free to create new ones if necessary). There are no hard and set rules for labels. We don't have many so look through and see how they've been used throughout the repository. They all also have descriptions. 1. If more information is required, please ask the submitter and tag as `waiting-for-info` and wait. 1. Finally, the issue should be moved into the [code-server](https://github.com/coder/code-server/projects/1) project where we pick out issues to fix and track their progress. We also use [milestones](https://github.com/coder/code-server/milestones) to track what issues are planned/or were closed for what release. --- # Security Source: https://coder.com/docs/code-server/SECURITY # Security Policy Coder and the code-server team want to keep the code-server project secure and safe for end-users. ## Tools We use the following tools to help us stay on top of vulnerability mitigation. - [dependabot](https://dependabot.com/) - Submits pull requests to upgrade dependencies. We use dependabot's version upgrades as well as security updates. - code-scanning - [CodeQL](https://securitylab.github.com/tools/codeql/) - Semantic code analysis engine that runs on a regular schedule (see `codeql-analysis.yml`) - [trivy](https://github.com/aquasecurity/trivy) - Comprehensive vulnerability scanner that runs on PRs into the default branch and scans both our container image and repository code (see `trivy-scan-repo` and `trivy-scan-image` jobs in `build.yaml`) - `npm audit` - Audits NPM dependencies. ## Supported Versions Coder sponsors the development and maintenance of the code-server project. We will fix security issues within 90 days of receiving a report and publish the fix in a subsequent release. The code-server project does not provide backports or patch releases for security issues at this time. | Version | Supported | | ------------------------------------------------------- | ------------------ | | [Latest](https://github.com/coder/code-server/releases) | :white_check_mark: | ## Reporting a Vulnerability To report a vulnerability, please send an email to security[@]coder.com, and our security team will respond to you. ---