Desktop client

apps/desktop is an optional Tauri desktop client. It bundles the same React App and browser adapters as apps/tui/web. The console communicates directly with a remote controller's HTTPS/WebSocket gateway; no local controller, Docker or TUI process is required. An optional native onboarding helper uses the system SSH client to discover, check and prepare servers. SSH is only needed during setup; sessions and gateway traffic run independently on the remote server.

This implementation uses Tauri 2. As of 15 October 2026, the official Tauri releases publish the stable 2.x series; a stable Tauri 3 API is not available. Native code and bootstrap live in this workspace so a future framework migration does not require another UI implementation.

Build and launch

Install the repository's Node/pnpm dependencies and build its shared packages as usual (pnpm install, then pnpm build). The standard workspace build, typecheck and test scripts prepare/check JavaScript and installer resources; they do not need Rust, WebKit or a desktop session. Python 3.9+ is required to package the installer resources and run the SSH-helper tests. Server Docker builds exclude this optional desktop package.

pnpm --filter @devctl/desktop build
pnpm --filter @devctl/desktop test
pnpm --filter @devctl/desktop typecheck

For the native application, first install the platform's Tauri prerequisites, including a current stable Rust toolchain. Linux requires its WebKitGTK/system development packages; macOS requires Xcode command line tools; Windows requires the MSVC tools and WebView2. Then run:

pnpm --filter @devctl/desktop dev
pnpm --filter @devctl/desktop build:app

The development command also serves the bundled assets through Tauri's local asset protocol; it does not start a development API server. Build outputs are in apps/desktop/src-tauri/target/release/bundle/. Build separately on each target OS. Package signing/notarization and automatic updates are not configured. For a native compile check after preparing the UI:

pnpm --filter @devctl/desktop check:native
cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked

Repeatable Windows builds over SSH

Use an existing Windows VM or machine with OpenSSH Server. The build pipeline does not create VMs or download operating-system images. On Apple Silicon, check the guest architecture: Windows ARM64 can also build an x64 target, but an ARM64 test is not proof of execution on an x64 Windows machine.

For a dedicated builder, run apps/desktop/windows-builder-ssh.ps1 -PublicKey 'ssh-ed25519 … builder' once in an administrator PowerShell. It installs the Windows OpenSSH capability, adds only the supplied public key, and restricts the builder login to key authentication without forwarding or a PTY. Existing key material and unrelated SSH configuration are preserved. Its firewall rule allows the VMPal NAT host only. Forward a Mac loopback port to guest port 22; verify that it listens only on 127.0.0.1/::1, then configure a dedicated devctrl-windows-builder SSH alias and verify its SSH host-key fingerprint. Keep the private builder key on the client. For other networks, configure an equivalent private SSH route and firewall rule explicitly.

The bootstrap reuses an existing SSH service before consulting Windows Optional Features. For a separately verified Microsoft OpenSSH installation, pass -OpenSshDirectory <absolute-directory>; it preserves the Windows SSH agent. Host private keys receive an Administrators/SYSTEM-only ACL and owner, and the firewall setup uses native netsh rather than waiting on the CIM provider.

After this one-time setup, builds use the console only:

python3 apps/desktop/build-windows.py \
  --ssh devctrl-windows-builder --commit HEAD --architecture arm64

# Optionally start an EXISTING VMPal VM and publish verified preview assets.
python3 apps/desktop/build-windows.py \
  --env .env.windows-builder --ssh devctrl-windows-builder \
  --commit <committed-revision> --architecture arm64 --publish

The optional private env file contains DEVCTRL_WINDOWS_VM_ID and, when needed for unlock, DEVCTRL_WINDOWS_PASSWORD. Keep it ignored by Git with mode 0600. Values stay in the wrapper's memory; they are not exported or uploaded. You can instead pass an existing VM ID with --vm and use its saved VMPal login.

The wrapper sends a git archive of the requested commit, never the working tree, untracked files or local credentials. Windows installs missing build prerequisites, uses the pinned pnpm lockfile and Cargo lockfile, caches Rust builds, and records timed steps and exit codes. It runs desktop/native tests, checks the actual PE architecture, installs the NSIS package into an isolated test folder, and opens the bundled app through a temporary interactive-user task. A local WebView2 check verifies rendering and native SSH discovery with a fresh test profile. The temporary app/task are cleaned up by their exact PID and executable path; existing clients are not stopped. Native UI checks require the builder user to be signed in. Close an existing devctrl desktop client before the installation/UI check: the builder preserves it instead of silently closing it or attaching the test to its window. Closing a VMPal VM window suspends its work; the VM must stay running while a build executes.

Artifacts and logs go to dist/windows/<commit>/<architecture>/ on the client. --publish uploads only the verified installer, SHA-256 checksums and build manifest to a GitHub prerelease. It rejects failed checks, changed bytes, architecture/revision mismatches and release tags pointing at another commit. Publishing also requires the full isolated smoke test: bundled project/session navigation, terminal input and resizing, plus native SSH key/password login and rejection of an incorrect password. Use --full-smoke to run these checks without publishing. The fixture uses an existing installer-lab Docker image, loopback-only ports and temporary test credentials; it never pulls an image or connects to a production server. Build logs, source archives, private keys and test credentials are excluded. Installers are unsigned developer previews; Windows may show SmartScreen.

Windows SSH onboarding uses the Python launcher (py -3, with interpreter fallbacks) and OpenSSH. Passwords pass through stdin and a one-use local named pipe restricted to the current user; they are not stored in temporary files or put in command arguments or environment variables. The packaged executable is also the native OpenSSH askpass client. Private console links work without the Python/OpenSSH prerequisites.

Windows first-use host-key discovery requires a working OpenSSH key scanner. Microsoft's stock OpenSSH 9.5 can advertise an unsupported key-exchange method; update Microsoft OpenSSH to 9.8.2 or later if the client requests it. This is an upstream Windows issue, and does not indicate an incorrect password. Already trusted SSH aliases can continue using the system trust configuration. devctrl never disables host-key verification to bypass this failure.

Connect through SSH

On first launch, Connect your server lists saved launcher connections from ~/.config/devctrl/consoles.json (or $XDG_CONFIG_HOME/devctrl/consoles.json), previous desktop SSH connections, and literal Host aliases from ~/.ssh/config and its Include files. Discovery reads configuration only; it does not contact all listed servers. Existing console sessions saved in the desktop profile continue to use the shared console switcher.

Select a server and choose Check and connect. Or select Enter a server address and supply its hostname/IP, SSH username, port, and optional password. Without a password, SSH uses the system agent and configured identities. Custom host-trust files and SSH configuration remain in effect. A new host requires explicit fingerprint verification; changed host keys are never silently replaced. For a first connection through ProxyJump or another indirect route, establish host trust with the system SSH client if direct key discovery is unavailable.

The check distinguishes an existing controller, a stopped controller, a fresh machine, unavailable Docker and incomplete installation. Connecting to an existing installation does not rebuild images, recreate containers or restart running sessions. A stopped controller/gateway can be started. Desktop Origins are enabled through a loopback-only operator endpoint, authenticated by a credential read on the server over SSH, with no gateway restart. An older gateway lacking this endpoint requires a control-plane update or a desktop-enabled private link.

A fresh server offers Install devctrl and connect. Automatic installation uses the existing standalone installer on Ubuntu with root or passwordless sudo, installs missing prerequisites including Docker, and prepares the remote controller, execution host and public gateway. It does not copy local coding-agent or Git credentials. Add repositories and authorize accounts in the shared interface. Existing or incomplete state is retained; the installer will not replace it. Prepared rootless Docker can be selected for an existing deployment; automatic rootless preparation is not part of desktop onboarding.

The setup UI shows the current stage and elapsed time with indeterminate progress. Keep the window open during installation. A connection timeout can leave partial server state, which is reported rather than overwritten on retry. Closing the client after connecting does not stop projects or sessions.

SSH passwords are held only for the current operation and a temporary private askpass file, removed after each command. They are never placed in process arguments, environment values, saved connection metadata or native logs. Saved SSH targets contain only address/alias, username, port and rootless preference. The desktop requires system Python 3.9+ and OpenSSH for SSH onboarding; private-link connection does not depend on those tools.

Connect via SSH remains available in the console header and sign-in form. Use a private console link retains the original shared authorization workflow.

Connect a console

On the machine hosting the console, enable the desktop client's exact asset Origins when starting its gateway:

./devctl web --client-url desktop
# Or a local-only gateway on the same computer:
./devctl web --local --client-url desktop
# Or configure an existing remote checkout over SSH:
./devctl web --host MY_SERVER --remote-dir /srv/devctrl --client-url desktop

The gateway opts into tauri://localhost (macOS/Linux) and http://tauri.localhost (Windows). No wildcard CORS or opaque null Origin is enabled by this option. A running gateway keeps its configured client mode; changing it uses the normal web gateway configuration workflow. SSH onboarding can add the two exact desktop Origins through the authenticated local operator endpoint without restarting the gateway or any Project/session.

Paste the complete HTTPS private console link into Connect devctrl. Plain HTTP is accepted only for localhost, 127.0.0.1 and [::1], for an API on the same computer. Other hosts require HTTPS with a trusted certificate. Use Console → Manage consoles to name, add, update, switch or forget connections. Each console keeps a separate revocable sign-in session, with the same user ownership rules as the web app. Use Sign out to revoke it on the server.

The private key is exchanged by the shared client and removed from the page fragment. It is not written to configuration or native logs. The remember-device option stores the returned revocable session in the application's WebView profile for up to 30 days; without it, the session is kept in session storage. This first version does not use an OS keychain. Local connection names and origins are also stored in that application profile, independently from ordinary browsers.

Copy page link produces a credential-free link such as:

devctrl://connect?api=https%3A%2F%2Fconsole.example#/projects?project=my-project&view=mosaic

After installation, the OS opens that console/page in devctrl. A console which has not been signed in on this device still requires its private link in the sign-in form. Desktop links reject access keys, user/password URL credentials, unsupported routes and non-loopback HTTP endpoints; never put keys in OS protocol links or command-line arguments. Protocol registration comes from the installed bundle; tauri dev alone does not install the handler on macOS, and Linux AppImage handlers require desktop integration. See Tauri deep linking.

The window uses standard OS decorations and the shared accessible DOM controls, keyboard navigation, console switching and session routes. External HTTP(S) links and authenticated file downloads open in the system browser. The desktop window stays on bundled application assets; remote websites cannot invoke its native APIs. Drag/drop uploads use the shared browser file-transfer flow.

The client uses normal browser fetch/WebSocket APIs, the gateway's Origin-bound bearer sessions and one-use transfer tickets. It has no native HTTP bypass, arbitrary shell, filesystem or process capability. A bundled-window-only native command accepts fixed SSH setup operations with validated structured targets; it accepts no executable, shell command or filesystem path from the frontend. Other native permissions read incoming deep links and listen to their events. The CSP permits remote HTTPS/WSS API connections and loopback HTTP/WS; scripts remain bundled.

Web Push/PWA installation is disabled in this native wrapper. Background OS notifications, an OS credential vault, auto-update and per-platform installer signing remain future work. The normal API client requires a connection; offline launch does not provide cached project data or offline terminal access.

Verification

The desktop tests use disposable loopback gateway/controller fixtures. They exercise the production shared browser transport with both Tauri Origins, preflight, sign-in, API forwarding, single-use WebSocket/download tickets, preserved download filenames without browser Origin/session headers, logout and rejection of opaque Origins, plus desktop link validation/selection. They use no real operator keys, containers or coding-provider sessions. Rust tests cover the window's allowed navigation Origins. Native helper tests cover offline discovery, SSH target validation, host trust and cleanup of temporary credentials. Fresh, existing and partial installations, stage interruption and preservation of active sessions are also covered. Native rendering, OS protocol integration, file dialogs/download behavior and distribution signing must also be checked on each target OS before publishing installers.

For an opt-in DOM smoke test using a separate headless Chrome profile:

pnpm --filter @devctl/desktop test:browser
# On another platform, select its installed Chrome/Chromium executable:
CHROME_PATH=/usr/bin/chromium pnpm --filter @devctl/desktop test:browser

This test uses mock SSH/authentication and fixture connection records only. It checks discovery, late fingerprint confirmation, fresh-install progress, password cleanup, safe host labels and mobile layout. It does not control the user's existing browser or contact real servers. Screenshots are written to the system temporary directory. It is excluded from normal CI.

The shared browser screen checks also apply to the desktop's bundled App: prepare the TUI/web build and install Playwright separately first. Set DEVCTL_PLAYWRIGHT_MODULE for an external installation and DEVCTL_BROWSER_EXECUTABLE to select an existing Chrome/Chromium binary.

node apps/tui/web/browser-parity.integration.mjs
node apps/tui/web/shared-form-controls.integration.mjs

They exercise compact Project/session controls, secondary action menus, native checkboxes, first terminal attachment and window resizing, plus real form and approval callbacks against isolated fixtures. Desktop and narrow viewports are checked for overflow. Provider prompts and production settings are never used. The connection list keeps fixed-size rows when many servers are saved; the remember checkbox uses the same 18-pixel size as other browser controls.

Desktop connection setup uses the same fourteen interface languages as the shared console. The native SSH helper supplies explicit notice IDs for local validation, discovery sources and warnings, fingerprint checks, setup stages, and connection failures. The desktop bridge translates these IDs; it does not guess a translation from English error text. Addresses, fingerprints, SSH aliases, paths, input values and remote server errors remain unchanged. Language changes also update an already visible local notice without rerunning setup or sending credentials again.

The native protocol retains its existing code, message, stage, source and warnings fields. New noticeKey, sourceNoticeKey and warningNotices metadata is additive. Older helpers without this metadata display their original messages. Native command rejections retain a readable message alongside the notice ID; the frontend translates only the native boundary and locally created typed notices, never an HTTP error that happens to contain a similar field.

Source checks cover the Python helper and isolated desktop onboarding DOM in Russian and Japanese at desktop and mobile widths. They verify local progress, errors, language changes and preservation of raw remote diagnostics. These checks do not rebuild, install or launch a native Windows or Android client; installed clients need a subsequent separately verified release to receive the updated native connection source.