code-server

Edit code in your browser with a persistent private development workspace.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up code-server

Editable Compose files in your own directory.

Start the app and sign in using PASSWORD from the private .env file.
Workspace files, editor configuration and extensions persist under /home/coder.

selfhost app --directory ./code-server init code-server

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./code-server start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd code-server
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose code-server, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "code-server",
  "name": "code-server",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Actions for a linked container

List installed extensions

Show installed editor extensions and their versions.

selfhost existing action EXISTING_ID list-extensions

Before configuring integrations

Use the extension actions with an exact publisher.name identifier. Extensions execute inside your workspace.
HASHED_PASSWORD takes precedence over the generated PASSWORD.
No native OIDC integration is assumed. An authentication proxy is a separate deployment decision.

code-server integrations

Compose service: code-server. These operations use the profile saved when this deployment is created.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (4)

Hashed login password hashed-password: Argon2 PHC hash. Takes precedence over PASSWORD; Selfhost preserves the existing generated password. secret
Log level log-level: stringChoices: trace, debug, info, warn, error, off
Idle shutdown timeout idle-timeout: Seconds before an idle server exits. Container restart policy still applies. string
Reconnection grace time reconnect-timeout: Seconds an editor session waits for a disconnected client. string

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./code-server config code-server
selfhost app --directory ./code-server plan code-server changes.json
selfhost app --directory ./code-server apply code-server changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

List installed extensions

Show installed editor extensions and their versions.

selfhost app --directory ./code-server action code-server list-extensions

Install editor extension

Download and install a trusted extension by publisher.name or publisher.name@version. Extensions execute code inside the workspace.

Extension ID extension: stringLength: 3 to 180 characters

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./code-server action code-server install-extension --inputs action-inputs.json

Remove editor extension

Uninstall the selected extension while preserving workspace files.

Extension ID extension: stringLength: 3 to 180 characters

Save the input IDs and selected values in a private action-inputs.json file.

selfhost app --directory ./code-server action code-server remove-extension --inputs action-inputs.json

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

code-server: codercom/code-server:4.139.1

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · code-server documentation