What Are Servers

A server defines protocol port of a process that runs in a machine. It also has a name, path, attributes. Path defines base path of service that is exposed via server. Attributes are optional and may be used to tune server or identify it if this is a special purpose server, for example a link:TODO: language-servers[Language Server]. In simple words, if you need to access a process in your workspace machine, you need to add a server. You can do it in User Dashboard or by editing workspace machine config:

"node": {
    "port": "3000",
    "protocol": "http",
    "path": "/",
    "attributes": {}
servers dashboard

If your workspace is running, saving a new server will restart a workspace.

Preview URLs

Just adding a server with port 3000 does not mean you can use this port to access a server. Each server is assigned with a URL in the runtime, i.e. when a workspace is running. In case of Docker, port 3000 will be published to a random port from the ephemeral port range (32768-65535). In case of OpenShift, a route bound to a service is created. Routes are persistent URLS, while server URLS provided in a Docker implementation of Che change every time your start a workspace.

What Is My Preview?

Say, you have added a server with port 3000 and started a workspace. There are multiple ways to get its preview URL:

  • Using a macro in a command

  • In the IDE, + icon in the bottom panel under the editor

  • In User Dashboard, Workspaces > YourWorkspace > Servers tab

You will also see URLS of some of the internal servers - agents that server launches when the workspace container/pod is up.

Internal Servers

Sometimes it is needed to expose port for accessing to process internally withing workspace, but public access should be forbidden. An example of such server may be a database which should be exposed only for web application and because of security concerns it should not be accessible publicly. Then server may be exposed as internal.

To expose server as internal it is needed to add the corresponding attribute into server config:

"db": {
    "port": "3200",
    "protocol": "tcp",
    "attributes": {
        "internal": "true"

Now, an application should be able to fetch db URL from workspace runtime and access to database using it while this URL won’t be accessible publicly from browser.

Secure Servers

Server may require to be exposed publicly but access should be restricted only for users which have permissions to workspace. For such cases Che has secure servers concept. Authentication proxy will be set up in from of exposed server and machine token will be required to request it. There are the corresponding attributes for exposing server as secure one:

"tooling": {
    "port": "4921",
    "protocol": "http",
    "attributes": {
        "secure": "true",
        "unsecuredPaths": "/liveness",
        "cookiesAuthEnabled": "true"


  • secure - is an attribute that indicates whether server should be exposed as secure one. False value is a default one;

  • unsecuredPaths - is an attribute for configuring secure servers and it contains an comma-separated list of URI-s which are considered as non-secure on the given server and can be accessible without token. It may be needed when server provide any public APIs, like API endpoint for health checks;

  • cookiesAuthEnabled - is an attribute that indicates whether token should be searched in cookies. By default it is disabled. And server developer may enable it if he is sure that his servers can’t be attacked by CSRF or has special protection from it.

Note that this functionality is in beta phase now and it is disabled by default. The instructions how it can be enabled by in the corresponding section of the Secure Servers article.