Dockside v4.0.0

Dockside v4.0.0

This is the biggest Dockside release since integrated SSH support landed in v3.0.0.

It adds a full command-line interface, a browser-based admin and account-management UI, a second browser IDE choice (OpenVSCode Server), and a set of security fixes to the credential and error-reporting paths — alongside SSH and image-build improvements accumulated since v3.2.0.

Highlights

• New: Admin & account management UI — a browser interface for users, roles, profiles and self-service account editing, alongside the existing container UI.
• New: OpenVSCode Server — a second, fully-supported browser IDE alongside Theia, selectable per devtainer at launch or on the fly.
• New: dockside CLI — manage devtainers, users, roles and profiles from your local machine command line or from scripts, with no dependencies beyond Python 3.6+.
• New: Per-user Github CLI token support - facilitates creating coding agent-assisted Issues, PRs, pushing and pulling.
• New: Responsive mobile navigation and other UI improvements — a bottom tab bar (Containers/Launch/Admin/Account) replaces the desktop-only top nav on small screens.
• New: wstunnel v10 is now the default SSH tunnel protocol; the legacy v6 path is retained for compatibility with existing SSH configs, and new devtainers support both. The wstunnel v10 integration, described when clicking the UI Setup button, offers the CLI's new dockside ssh exec-proxy %n as ssh ProxyCommand, which provides improved security.
• Improved: leaner multi-stage Docker image — dedicated build stages for docs and Vue web app, and removal of unneeded build artifacts, reduce final image size; resources specific to developing Dockside are hived out to a development image stage (see Developing Dockside below).
• Improved, simpler upgrade process — delivers in-place upgrades of the IDE and SSH server versions and bundled git and GH binaries available to launched devtainers (across a devtainer stop/start cycle)
• New/Improved resilience: Comprehensive integration test suite — 100+ tests across admin API, SSH, IDE launch and networking help ensure resilience of each future Dockside release.
• SCP/SFTP support — patched dropbear now invokes a bundled integrated sftp-server, allowing scp to/from devtainers
• Security fixes — a session cookie leaking via the SSH ProxyCommand, secrets leaking through error responses, and mutation endpoints reachable over GET are all closed this release; see Security fixes below.
• Misc — per-user Multi-keypair SSH, customisable profile launch-time options, including for git branch/PR selection.

---

New: Admin and account-management UI

The Vue client gains browser screens for administering users, roles and profiles, plus self-service account editing for any authenticated user — previously only possible by an admin hand-editing users.json/roles.json (or using the new CLI).

• List/detail views for users, roles and profiles, with dedicated editors for permissions, resources and the profile JSON blob.
• Self-service account editing (/account), including your own SSH public keys and (if permitted) GitHub token.
• Sensitive fields (SSH private keys, GitHub tokens) are masked in the UI and API by default, and are preserved correctly on save — editing an unrelated field no longer risks silently overwriting a masked secret with the mask itself.
• A new manageUsers permission gates all of this; it's enabled for the admin role by default and can be denied like any other permission.
• On small screens, a responsive bottom tab bar (Containers / Launch / Admin / Account) replaces the desktop-only top nav, while a hamburger menu opens out the list of containers (Containers screen), or users/roles/profiles (Admin screen).

This UI and the CLI (below) are now just two clients of the same server-side admin and user API — anything one can do, the other can too.

New: Devtainer, user, role and profile management CLI

Dockside now ships a dockside command-line interface (cli/), wrapping the same HTTP API the web frontend uses. It's a zero-dependency Python 3.6+ tool, installable with pip install ./cli or by copying to your PATH, or runnable directly as cli/dockside.

• Devtainers: create, get, list, edit, start, stop, remove, logs — addressable by name, reservation ID, or container ID prefix. Lifecycle commands wait for the target state by default (--no-wait / --timeout to control that), and --from-json FILE|- lets you drive creation/edits from a JSON document.
• Users, roles and profiles: dockside user/role/profile subcommands for full CRUD, with --set KEY=VALUE / --unset KEY for dot-notation nested fields (e.g. --set ssh.publicKeys.laptop=@~/.ssh/id_ed25519.pub) and --sensitive to include private keys/tokens where permitted.
• Multi-server support: dockside login --nickname NAME, server list, server use, and per-command --server let one CLI install manage several Dockside instances, including nested (Dockside-in-Dockside) setups.
• Output formats: text (default), json, yaml on every command.
• Config and cookies live under ~/.config/dockside/, written atomically and validated against path traversal/symlink tricks.

See cli/README.md for the full command reference.

New: OpenVSCode Server, a second browser IDE

Dockside now bundles OpenVSCode Server — the upstream open-source VS Code server — as a full alternative to Theia.

• Selectable per devtainer. Choose Theia or OpenVSCode at launch time from whichever IDEs are available on the host; switch a running devtainer's IDE later via Edit (takes effect on IDE restart, without recreating the devtainer).
• Since OpenVSCode is the actual upstream VS Code server rather than a compatible reimplementation, it offers the broadest VS Code extension compatibility of the two.
• Bundled gh/git wrappers and GitHub-token integration (see below) work the same way regardless of which IDE you pick; OpenVSCode's CLI code is added to each devtainer's PATH and wired up as GIT_EDITOR in its integrated terminals. Run code --help to see how files and workspaces can be opened programatically.
• Its VS Code chat/completion extension is disabled by default — it depends on a GitHub Copilot Chat build only available via the VS Code Marketplace, not OpenVSX.
• OpenVSCode's static assets are, through a wrapper, served compressed and immutably cached, so providing faster reload times on slow network connections.

OpenVSCode ships at v1.109.5. Theia remains fully supported and is upgraded to v1.68.2 (from v1.56.0 at v3.2.0).

SSH and GitHub integration improvements

• Per-user GitHub token. Store a personal access token in your account (gh_token); Dockside passes it into every devtainer you launch so gh commands (e.g. gh pr checkout) work without an interactive login. This also facilitates coding agents, like Claude CLI, creating PRs/issues and reading and acting on PR comments.
• Multi-keypair support. Users can now hold more than one SSH keypair, and Dockside adds all of them to the devtainer's SSH agent at launch. These can be created/edited via the UI or CLI.
• Named public keys. Public keys are now stored as a named map, so individual keys can be added or removed independently, again via UI or CLI with e.g.: dockside user edit alice --set ssh.publicKeys.laptop=@~/.ssh/id_ed25519.pub. Existing records are migrated automatically on load; no action needed. These can also be created/edited via the UI or CLI.
• Hardened git setup in devtainers: branch/PR checkout failures are now hard errors (previously a missing branch could silently create an empty local branch), and launch-time problems (a keypair that failed to load, a failed clone) now surface in your shell via .bashrc/.profile, not just the launch log.
• Branch/PR selection at launch. Profiles can now define arbitrary launch-time options; out of the box, this powers picking a git branch or PR to check out when creating a devtainer (see the example 03-git-repo.json profile).

UI improvements

• A bottom tab bar (Containers/Launch/Admin/Account) replaces the desktop-only top nav on small screens while the hamburger menu now provides full access to a user's accessible resources and an admin's user, role and profile records.
• New confirmation prompt shown before removing a devtainer.
• "Copy Launch URI" is now "Copy Launch Command", emitting an equivalent dockside create … CLI invocation (the old GET-based launch URL no longer works, per the POST migration above).

Security fixes

SSH credential exposure in ProxyCommand, fixed via a wstunnel v6→v10 upgrade. The CLI's SSH integration used to bake your live session cookie directly into the ProxyCommand invoked by ssh — exposing it in ~/.ssh/config and process lists, and (without hidepid) to any other user on the host via /proc/<pid>/cmdline. Dockside now bundles wstunnel v10 alongside the legacy v6 binary, and dockside ssh config generates a ProxyCommand dockside ssh exec-proxy %n entry: the CLI resolves the session live at connection time and hands wstunnel a cookie via a private, 0600 --http-headers-file that never appears in ~/.ssh/config, printed output, or any process's argv. See docs/adr/0004-ssh-tunnel-credential-exposure.md.

• Existing saved ~/.ssh/config blocks using the old proxy-command form keep working against the legacy v6 path — but you should re-run dockside ssh config and update your SSH config to pick up the fix.
• The Dockside UI's SSH info panel now shows three tabs (wstunnel v10+ / Dockside CLI / legacy v6) with guidance on which to use.

Client-facing errors no longer leak internal detail or secrets. The server previously returned both a client-facing message and full internal debug detail — including, in some paths, environment payloads, PEM private-key blocks, and GitHub tokens — to API clients. Error responses are now sanitised and abbreviated before they leave the server; full detail still goes to server-side logs. See docs/adr/0003-error-reporting-surface.md.

All state-changing API routes now require POST. Previously, mutations (creating, editing, starting, stopping and removing users, roles, profiles and containers) were reachable over GET — which is cacheable, prefetchable, and lands in access logs and browser history, and whose argument parsing didn't reliably JSON-decode structured fields like role permissions. Every mutation route now requires POST and is rejected with 405 otherwise; the CLI and Vue client were updated accordingly. See docs/adr/0002-admin-api-post-migration.md.

Alpine and Node version bumps. Dockside bundled 'system' binaries are bumped to Alpine 3.22. The Dockside server is bumped to Node 22.

Other hardening:

• npm dependencies refreshed, clearing all critical and fixable vulnerabilities in the Vue client (axios, sass, and others).
• The login page no longer loads Bootstrap CSS from the long-retired BootstrapCDN; it's served same-origin.
• A crash in nginx's async login handler (dangling callback reference when the request body arrived in a separate TCP write, as CLI connections often do) is fixed.

Bugs fixed

• Fixed a startup race where the launch form could show an empty networks menu if nginx started before the docker-event-daemon had written container/network state.

Image build and release

• Versioned system directory. /opt/dockside/system is now versioned like the IDE directories /opt/dockside/ide/{theia,openvscode}
• Dockside's devtainer resources are now built to /opt/dockside.img and synced by Dockside to the /opt/dockside volume when Dockside starts, delivering in-place upgrades of the IDE and SSH server versions and bundled git and GH binaries available to launched devtainers (across a devtainer stop/start cycle) following a simple docker compose up --pull=always

Developing Dockside

• New development image stage hives out of the production latest images dependencies that are only needed for developing Dockside itself.
• This bakes in Playwright's browser dependencies and the Claude Code CLI, wired up via an admin-managed MCP config so Claude Code's browser tools can reach both the devtainer's Dockside UI and its devtainers regardless of TLS/domain setup.
• Documentation (mkdocs) and the Vue client now build in their own dedicated stages;
• The build.sh script now supports --push-gchr option to push images to GitHub Container Registry (ghcr.io/newsnowlabs/dockside) alongside Docker Hub.
• New integration test suite (t/integration/): provides a dynamic fixture-driven harness, isolation between test runs, and over 100 tests across admin API, SSH (including the multi-keypair agent and the new exec-proxy path), Github, IDE launch readiness, and network handling — all driven exclusively through the dockside CLI and capable of being run in a Claude Code for Web environment.
• A startup race where a devtainer's IDE could be exec'd before its launcher was actually installed (in mountIDE:false setups, where an inner/'child' Dockside devtainer is launched using its own writable /opt/dockside volume, rather than it's outer/parent Dockside's volume) is fixed.

Documentation

docs/README.md, setup.md and ssh.md have been substantially rewritten, and a new runtimes.md added, to reflect the CLI, the admin UI, and full keypair support, with CLI examples added throughout. Four new Architecture Decision Records document the admin API POST migration, the error-reporting sanitisation, the SSH credential-exposure fix, and the integration harness's cookie-isolation design (docs/adr/).

---

Breaking changes and upgrade notes

• NO UPGRADE FROM DOCKSIDE v3.2.0 OR EARLIER. Dockside instances without a dedicated /opt/dockside mountpoint cannot be upgraded to v4.0.0, but must be removed first, and then Dockside v4.0.0 installed from scratch. Be sure to save any current devtainer contents and remove devtainers before removing your Dockside container, as after reinstalling they cannot be guaranteed to be accessible.
• DEPRECATED. Manually updating Dockside's users.json, roles.json and profiles/*.json is deprecated, since the UI and CLI both fully support creating/editing/removing such records, and their use for this purpose will update these files on the server. That said, it remains safe to add new profiles manually.
• All mutation API routes require POST. Any external script or tool calling Dockside's API directly with GET for a create/update/start/stop/remove operation will now get 405. Use the CLI or update your integration to send POST.
• ssh.authorized_keys[] is migrated to ssh.publicKeys{} automatically on first load of an existing users.json. No manual step is required, but tooling that edits users.json directly should switch to the new field.

Dependency upgrades

• wstunnel v10 is the new default; v6 remains for compatibility. Existing ~/.ssh/config entries keep working against the legacy port, but you should re-run dockside ssh config to adopt the credential-exposure fix (see above).

Upgrading

It is strongly recommended to treat v4.0.0 as a fresh install: i.e.

• save all uncommitted/unpushed devtainer contents; then
• stop and remove all running devtainers; then
• shut down the dockside container (using docker rm or docker compose down, according to your install); then
• pull the new image;
• then install v4.0.0 freshly, using the instructions in the README.

Pull the new image with docker pull newsnowlabs/dockside:latest, or docker pull newsnowlabs/dockside:v4.0.0 in perpetuity (also available via ghcr.io/newsnowlabs/dockside / ghcr.io/newsnowlabs/v4.0.0).

N.B.

• If your existing dockside container has no /opt/dockside volume-mount, this is strictly necessary.
• If your existing dockside container has an existing /opt/dockside volume-mount, you may find you are able to upgrade Dockside in-situ by relaunching only the dockside container from an updated Dockside image. However, since there is a risk devtainers will become inaccessible, it is recommended that you backup data from any devtainers first.

Full Changelog: v3.2.0...v4.0.0