Skip to main content
129.5K
HomeFAQ

FAQ

On this page

Questions?

Please file all questions and support requests at https://github.com/coder/code-server/discussions.

How should I expose code-server to the internet?

Please see our instructions on exposing code-server safely to the internet.

Can I use code-server on the iPad?

See iPad 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:

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 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:

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, 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. We may implement something similar (see #33)
  2. Remote Extensions (SSH, Containers, WSL). We may implement these again at some point, see (#1315).

For more about the closed source portions of VS Code, see vscodium/vscodium.

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

code-server --install-extension <extension id> # 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 <path to vsix> in the terminal

You can also download extensions using the command line. For instance, downloading from OpenVSX can be done like this:

code-server --install-extension <extension id>

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:

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.

For further information, see this discussion regarding the use of the Microsoft URLs in forks, as well as VSCodium's docs.

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

Can I open a file at a specific line from a URL?

Yes. In addition to workspace and folder, code-server supports VS Code's payload query parameter, which can open a specific file — optionally at a line and column — once the workbench loads.

payload is a URL-encoded JSON array of [key, value] string pairs. The openFile key takes a vscode-remote://<host>/<absolute path> URI, where <host> is the host you use to reach code-server. Add ["gotoLineMode","true"] to have a trailing :line[:column] suffix on the path interpreted as a cursor position:

https://code.example.com/?folder=/home/coder/project&payload=[["gotoLineMode","true"],["openFile","vscode-remote://code.example.com/home/coder/project/src/app.py:10:5"]]

(with the payload value URL-encoded). Notes:

  • Paths must be absolute; there is no form relative to folder.
  • This is upstream VS Code web behavior (the same mechanism vscode.dev uses), so it works without any code-server-specific configuration.

For example, to generate links from a shell:

#!/bin/sh # usage: code-link <absolute-file> [line[:column]] HOST=code.example.com payload="[[\"gotoLineMode\",\"true\"],[\"openFile\",\"vscode-remote://$HOST$1${2:+:$2}\"]]" printf 'https://%s/?folder=%s&payload=%s\n' "$HOST" "$(dirname "$1")" \ "$(printf '%s' "$payload" | jq -sRr @uri)"

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

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

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

{ "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 <seconds> to code-server, set CODE_SERVER_RECONNECTION_GRACE_TIME=<seconds>, or add reconnection-grace-time: <seconds> 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:

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:

echo -n "thisismypassword" | npx argon2-cli -e $argon2i$v=19$m=4096,t=3,p=1$wst5qhbgk2lu1ih4dmuxvg$ls1alrvdiwtvzhwnzcm1dugg+5dto3dt1d5v9xtlws4

Replace