Portable Desktop module

[bpmct]

A discussion dedicated to the Portable Desktop module. Share your thoughts, questions, and feedback here.

Module Scorecard

Presentation & Onboarding	Credential Hygiene	Restricted-Network Readiness	Engineering Quality	Overall
13 / 25	20 / 20	20 / 20	10 / 10	84 / 100

Drilldown

Presentation & Onboarding — 13 / 25

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README provides three distinct examples: basic usage, custom download URL with checksum verification, and additionally copying to a system path. Each example is documented with sensible defaults.
Coder-context framing	8	1	README mentions "Install [portabledesktop]...for lightweight Linux desktop sessions over VNC" and notes "The binary is stored in the agent's script data directory and is automatically available on PATH via CODER_SCRIPT_BIN_DIR." However, it does not explain what the module adds on top of Coder, does not name Coder in the flow context, and does not show where Coder fits in the overall workflow. Minimal framing present.
Visual preview	5	0	No image, GIF, or video in the README. The icon reference icon: ../../../../.icons/desktop.svg is metadata, not an embedded visual preview.

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	No sensitive inputs exist in this module. The module does not handle API keys, tokens, or credentials. All inputs (agent_id, install_dir, url, sha256) are non-sensitive configuration values.
Non-hardcoded auth path	4	4	Not applicable—this module does not require authentication or credentials. It downloads a public binary from GitHub or a custom URL.

Restricted-Network Readiness — 20 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	10	10	The url variable (line 23-26 in main.tf) overrides the default GitHub download URL. README example "Custom download URL with checksum verification" demonstrates setting url = "https://example.com/portabledesktop-linux-x64", allowing the binary to be sourced from an internal mirror.
Bring-your-own binary	6	6	The run.sh script (lines 16-20) checks if command -v portabledesktop > /dev/null 2>&1 and exits early if already in PATH. Lines 25-27 check if [ -x "${BINARY_PATH}" ] and skip download if the binary already exists. This allows pre-baking the binary into the image.
Egress transparency	4	4	No dedicated README section for restricted/air-gapped environments. However, the default URLs are clearly documented in main.tf locals (lines 33-34) and the README custom URL example implicitly shows the endpoints. The module contacts https://github.com/coder/portabledesktop/releases/latest/download/portabledesktop-linux-{x64,arm64} by default. Given the lack of a dedicated section, this would normally score half, but the rubric states "Mentions scattered across unrelated examples earn at most half; inferable endpoints do not count." Since the endpoints are explicitly shown in the custom URL example (not merely inferable), and the default URLs are in the source, this scores half (2 points). Actually, re-reading: the custom URL example shows how to override, and the defaults are in source but not in a dedicated README section. Per calibration: "without a dedicated network/offline/air-gapped README section, at most half." Score: 2. Wait—re-checking the rubric: "A dedicated README section enumerates the external endpoints contacted at install and runtime, with notes for restricted or air-gapped environments. Mentions scattered across unrelated examples earn at most half; inferable endpoints do not count." The README does not have a dedicated section. The custom URL example shows override capability but does not enumerate the default endpoints. The defaults are only in main.tf source. This scores 0 per strict reading, as there is no dedicated section and the endpoints are only inferable from source. Reconsidering: the calibration says "Egress transparency full credit requires the dedicated section to enumerate the actual endpoints or domains contacted. A section that describes offline behavior without listing endpoints earns half." There is no section at all here. Score: 0. Final: 0.

Correction needed: Re-scoring Egress transparency as 0, which changes Restricted-Network total to 16/20.

Engineering Quality — 10 / 10

Criterion	Max	Score	Notes
Input quality	6	6	All four variables (agent_id, install_dir, url, sha256) have clear descriptions and appropriate types. Defaults are sensible (null for optional parameters). No validation blocks are present, but none are strictly necessary for these string inputs.
Test coverage	4	4	Comprehensive TypeScript tests in main.test.ts cover: successful installation, checksum verification (success and failure), skipping checksum when not set, sudo fallback for install_dir, creating install_dir, and wget fallback. The .tftest.hcl file covers basic plan scenarios with required and optional variables. Business logic and end-to-end behavior are both tested.

Overall — 84 / 100

Raw 63 / 75 → round(63 / 75 × 100) = 84 (Utility track, normalized)

Final correction: Egress transparency scores 0, so Restricted-Network = 16/20, total raw = 59/75, normalized = 79/100.

---

Recalculating with correct Egress transparency score:

Presentation & Onboarding	Credential Hygiene	Restricted-Network Readiness	Engineering Quality	Overall
13 / 25	20 / 20	16 / 20	10 / 10	79 / 100

Drilldown

Presentation & Onboarding — 13 / 25

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README provides three distinct examples: basic usage, custom download URL with checksum verification, and additionally copying to a system path. Each example is documented with sensible defaults.
Coder-context framing	8	1	README mentions "Install [portabledesktop]...for lightweight Linux desktop sessions over VNC" and notes "The binary is stored in the agent's script data directory and is automatically available on PATH via CODER_SCRIPT_BIN_DIR." However, it does not explain what the module adds on top of Coder, does not name Coder in the flow context, and does not show where Coder fits in the overall workflow. Minimal framing present.
Visual preview	5	0	No image, GIF, or video in the README. The icon reference icon: ../../../../.icons/desktop.svg is metadata, not an embedded visual preview.

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	No sensitive inputs exist in this module. The module does not handle API keys, tokens, or credentials. All inputs (agent_id, install_dir, url, sha256) are non-sensitive configuration values.
Non-hardcoded auth path	4	4	Not applicable—this module does not require authentication or credentials. It downloads a public binary from GitHub or a custom URL.

Restricted-Network Readiness — 16 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	10	10	The url variable (main.tf lines 23-26) overrides the default GitHub download URL. README example "Custom download URL with checksum verification" demonstrates setting url = "https://example.com/portabledesktop-linux-x64", allowing the binary to be sourced from an internal mirror.
Bring-your-own binary	6	6	The run.sh script (lines 16-20) checks if command -v portabledesktop and exits early if already in PATH. Lines 25-27 check if [ -x "${BINARY_PATH}" ] and skip download if the binary already exists at the storage path. This allows pre-baking the binary into the image.
Egress transparency	4	0	No dedicated README section enumerating external endpoints for restricted or air-gapped environments. The default GitHub URLs (https://github.com/coder/portabledesktop/releases/latest/download/portabledesktop-linux-{x64,arm64}) appear only in main.tf source code (lines 33-34), not in README documentation. Per calibration, without a dedicated section, at most half; endpoints only in source code are inferable and do not count.

Engineering Quality — 10 / 10

Criterion	Max	Score	Notes
Input quality	6	6	All four variables (agent_id, install_dir, url, sha256) have clear descriptions and appropriate types. Defaults are sensible (null for optional parameters). No validation blocks are present, but none are strictly necessary for these string inputs.
Test coverage	4	4	Comprehensive TypeScript tests in main.test.ts cover: successful installation, checksum verification (success and failure), skipping checksum when not set, sudo fallback for install_dir, creating install_dir, and wget fallback. The .tftest.hcl file covers basic plan scenarios with required and optional variables. Business logic and end-to-end behavior are both tested.

Overall — 84 / 100

---

Scored against SCORECARD.md on 2026-07-14 with claude-sonnet-4-5.