One editor backend: code-server
The VS Code App uses official code-server archives on Linux and macOS, verified against pinned SHA-256 digests. Agent Server owns download, extraction, isolated data directories and process cleanup.
Depends on software-agent-sdk#6792. The smoke workflow pins that PR revision; it is pre-release integration evidence, not released-server compatibility. The foundation supports Windows x64 App backends, but upstream code-server has no Windows release. Canvas folder-query/ingress/session-renewal integration remains outside this diff.
Manifest before → after
Before: OpenVSCode 1.109.5, Linux amd64/arm64 -After: code-server 4.145.2, Linux amd64/arm64 + Darwin amd64/arm64 -Host contract: optional additional_artifacts; no new Canvas browser API.
Official code-server replaces OpenVSCode
Keep Linux artifacts in the canonical map and macOS artifacts in additional_artifacts. Bind loopback with bridge-owned authentication; disable telemetry, update checks and port proxy. No positional folder avoids an initial redirect rejected by the bridge.
Before: apps/vscode/canvas-extension.json:9
After: apps/vscode/canvas-extension.json:17
Inspect diff
diff --git a/apps/vscode/canvas-extension.json b/apps/vscode/canvas-extension.json
-index c1f8c30..f2ddd96 100644
---- a/apps/vscode/canvas-extension.json
-+++ b/apps/vscode/canvas-extension.json
-@@ -3,25 +3,68 @@
- "name": "vscode",
- "display_name": "VS Code",
- "version": "0.1.0",
-- "description": "A managed OpenVSCode editor for the selected Agent Canvas workspace.",
-+ "description": "A managed code-server editor for Agent Canvas.",
- "entrypoint": "extension.js",
-- "contributes": {"pages": [{"id": "editor", "title": "VS Code", "path": "/editor"}]},
-+ "contributes": {
-+ "pages": [
-+ {
-+ "id": "editor",
-+ "title": "VS Code",
-+ "path": "/editor"
-+ }
-+ ]
-+ },
- "backend": {
- "schema_version": 1,
- "artifacts": {
- "linux-amd64": {
-- "url": "https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-v1.109.5/openvscode-server-v1.109.5-linux-x64.tar.gz",
-- "sha256": "b433bf4f0227321a7014d8460d10a8f958adc0f45aa79bd889e84e65e8f88363",
-+ "url": "https://github.com/coder/code-server/releases/download/v4.145.2/code-server-4.145.2-linux-amd64.tar.gz",
-+ "sha256": "2f6db6c3e8b733dd6b3aeee83532e148b2bae2e392353ba85452d03572348962",
- "strip_components": 1
- },
- "linux-arm64": {
-- "url": "https://github.com/gitpod-io/openvscode-server/releases/download/openvscode-server-v1.109.5/openvscode-server-v1.109.5-linux-arm64.tar.gz",
-- "sha256": "36d9c14036489b63de84ebace837fcacf7e60e669a0dc715802c5443684ea4dc",
-+ "url": "https://github.com/coder/code-server/releases/download/v4.145.2/code-server-4.145.2-linux-arm64.tar.gz",
-+ "sha256": "e867a34416e2da4a83496b09580001893e7a4e5bb58a0624c4fcd22819e7d53d",
- "strip_components": 1
- }
- },
-- "argv": ["{artifact_dir}/bin/openvscode-server", "--host", "127.0.0.1", "--port", "{port}", "--without-connection-token", "--accept-server-license-terms", "--telemetry-level", "off", "--user-data-dir", "{data_dir}/user", "--extensions-dir", "{data_dir}/extensions", "--server-base-path", "/app-backends/vscode", "{data_dir}"],
-- "health": {"path": "/", "timeout_seconds": 90, "interval_seconds": 0.5},
-- "inherit_environment": ["PATH", "LANG", "LC_ALL", "TMPDIR"]
-+ "argv": [
-+ "{artifact_dir}/bin/code-server",
-+ "--bind-addr",
-+ "127.0.0.1:{port}",
-+ "--auth",
-+ "none",
-+ "--disable-telemetry",
-+ "--disable-update-check",
-+ "--disable-proxy",
-+ "--ignore-last-opened",
-+ "--user-data-dir",
-+ "{data_dir}/user",
-+ "--extensions-dir",
-+ "{data_dir}/extensions"
-+ ],
-+ "health": {
-+ "path": "/",
-+ "timeout_seconds": 90,
-+ "interval_seconds": 0.5
-+ },
-+ "inherit_environment": [
-+ "PATH",
-+ "LANG",
-+ "LC_ALL",
-+ "TMPDIR"
-+ ],
-+ "additional_artifacts": {
-+ "darwin-amd64": {
-+ "url": "https://github.com/coder/code-server/releases/download/v4.145.2/code-server-4.145.2-macos-amd64.tar.gz",
-+ "sha256": "5fb7ac2bd60538400244d942f649559e0ff4fb3d8792979287f504780f357af6",
-+ "strip_components": 1
-+ },
-+ "darwin-arm64": {
-+ "url": "https://github.com/coder/code-server/releases/download/v4.145.2/code-server-4.145.2-macos-arm64.tar.gz",
-+ "sha256": "d6699692f1e59d918517c81f9d2a4ef335132128cd45725b22236d5fe09636d4",
-+ "strip_components": 1
-+ }
-+ }
- }
- }Packaging validates both artifact maps
The installable package remains small: official binaries download only when the user prepares the backend. Validate remote artifact metadata in both maps.
Before: apps/vscode/scripts/package.mjs:12
After: apps/vscode/scripts/package.mjs:12
Inspect diff
diff --git a/apps/vscode/scripts/package.mjs b/apps/vscode/scripts/package.mjs
-index cbf4279..60b23cf 100644
---- a/apps/vscode/scripts/package.mjs
-+++ b/apps/vscode/scripts/package.mjs
-@@ -9,7 +9,7 @@ const manifest = JSON.parse(
- await readFile(path.join(appRoot, "canvas-extension.json"), "utf8"),
- );
-
--for (const [platform, artifact] of Object.entries(manifest.backend.artifacts)) {
-+for (const [platform, artifact] of Object.entries({ ...manifest.backend.artifacts, ...manifest.backend.additional_artifacts })) {
- const url = new URL(artifact.url);
- if (url.protocol !== "https:" || !url.pathname.endsWith(".tar.gz")) {
- throw new Error(`${platform}: invalid HTTPS artifact URL`);The test starts the downloaded editor
Install the built App package with Agent Server, verify preparation, GET actual workbench HTML, stop, restart and preserve data. Shutdown always runs. This is backend integration coverage, not a browser edit/save test.
Before: New file; no before implementation
After: apps/vscode/scripts/smoke_backend.py:14
Inspect diff
diff --git a/apps/vscode/scripts/smoke_backend.py b/apps/vscode/scripts/smoke_backend.py
-new file mode 100644
-index 0000000..741ccc4
---- /dev/null
-+++ b/apps/vscode/scripts/smoke_backend.py
-@@ -0,0 +1,46 @@
-+"""Install the packaged app and start its checksum-pinned official backend."""
-+
-+import asyncio
-+import sys
-+from pathlib import Path
-+from tempfile import TemporaryDirectory
-+
-+import httpx
-+
-+from openhands.agent_server.canvas_extensions.backend import CanvasExtensionBackendManager
-+from openhands.agent_server.canvas_extensions.installed import install_canvas_extension
-+
-+
-+async def main(source: Path) -> None:
-+ with TemporaryDirectory(prefix="vscode-app-smoke-") as temporary:
-+ root = Path(temporary)
-+ installed = root / "installed"
-+ install_canvas_extension(str(source.resolve()), installed_dir=installed)
-+ manager = CanvasExtensionBackendManager(installed, root / "state")
-+ try:
-+ revision = manager.revision("vscode")
-+ assert revision is not None
-+ prepared = await manager.prepare("vscode", revision)
-+ assert prepared.prepared_revision == revision, prepared
-+ started = await manager.start("vscode", revision)
-+ logs = await manager.logs("vscode", 8192)
-+ assert started.state == "ready", (started, logs.logs)
-+ assert manager.ready_endpoint("vscode") == ("127.0.0.1", started.port)
-+ async with httpx.AsyncClient(trust_env=False) as client:
-+ response = await client.get(f"http://127.0.0.1:{started.port}/")
-+ assert response.status_code == 200, response.text[:500]
-+ assert "workbench" in response.text.lower(), response.text[:500]
-+ marker = manager.data_dir / "vscode" / "persistence-check"
-+ marker.write_text("survives restart")
-+ assert (await manager.stop("vscode")).state == "stopped"
-+ assert manager.ready_endpoint("vscode") is None
-+ restarted = await manager.start("vscode", revision)
-+ assert restarted.state == "ready", restarted
-+ assert marker.read_text() == "survives restart"
-+ print(f"Official {manager.current_platform()} artifact: prepare, HTTP editor, stop, restart passed")
-+ finally:
-+ await manager.shutdown()
-+
-+
-+if __name__ == "__main__":
-+ asyncio.run(main(Path(sys.argv[1])))Linux and Mac run the same smoke path
Use read-only checkout credentials and a frozen SDK dependency lock. Native ubuntu-latest and macos-latest execute the installed backend; replace the SDK commit pin with its containing release before shipment.
Before: New file; no before implementation
After: .github/workflows/vscode-backend-smoke.yml:13
Inspect diff
diff --git a/.github/workflows/vscode-backend-smoke.yml b/.github/workflows/vscode-backend-smoke.yml
-new file mode 100644
-index 0000000..0dee520
---- /dev/null
-+++ b/.github/workflows/vscode-backend-smoke.yml
-@@ -0,0 +1,47 @@
-+name: VS Code backend smoke
-+
-+on:
-+ pull_request:
-+ paths:
-+ - apps/vscode/**
-+ - .github/workflows/vscode-backend-smoke.yml
-+ workflow_dispatch:
-+
-+permissions:
-+ contents: read
-+
-+jobs:
-+ backend:
-+ name: Official code-server (${{ matrix.os }})
-+ runs-on: ${{ matrix.os }}
-+ timeout-minutes: 15
-+ strategy:
-+ fail-fast: false
-+ matrix:
-+ os: [ubuntu-latest, macos-latest]
-+ steps:
-+ - uses: actions/checkout@v7
-+ with:
-+ persist-credentials: false
-+ # Cross-repository dependency: software-agent-sdk#6792. Replace this
-+ # immutable revision with the containing release once it is published.
-+ - uses: actions/checkout@v7
-+ with:
-+ repository: OpenHands/software-agent-sdk
-+ ref: 1772179b1b3a3f92dce2d90822c4d4428125cbde
-+ path: .sdk
-+ persist-credentials: false
-+ - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
-+ with:
-+ python-version: "3.13"
-+ - uses: actions/setup-node@v7
-+ with:
-+ node-version: "24"
-+ - name: Build installable App package
-+ run: node apps/vscode/scripts/package.mjs
-+ - name: Install locked Agent Server dependency
-+ working-directory: .sdk
-+ run: uv sync --frozen --group dev
-+ - name: Download, prepare, serve and restart official editor
-+ working-directory: .sdk
-+ run: uv run --frozen python ../apps/vscode/scripts/smoke_backend.py ../dist/apps/vscodeDocument the cross-repository contract
Document optional additional_artifacts and safe contained-file-link extraction, explicitly identifying the unreleased SDK prerequisite.
Before: skills/canvas-extension-api/references/v1-contract.md:48
After: skills/canvas-extension-api/references/v1-contract.md:48
Inspect diff
diff --git a/skills/canvas-extension-api/references/v1-contract.md b/skills/canvas-extension-api/references/v1-contract.md
-index 5eee133..7aca4de 100644
---- a/skills/canvas-extension-api/references/v1-contract.md
-+++ b/skills/canvas-extension-api/references/v1-contract.md
-@@ -53,6 +53,12 @@ interface CanvasExtensionBackend {
- sha256: string;
- strip_components?: number;
- }>>;
-+ additional_artifacts?: Record<string, {
-+ path?: string;
-+ url?: string;
-+ sha256: string;
-+ strip_components?: number;
-+ }>;
- argv: string[];
- health?: {
- path?: string;
-@@ -81,7 +87,9 @@ All references in this bundle to "the minimum host version documented in `v1-con
-
- For a managed backend:
-
--- Key `artifacts` only by `linux-amd64` or `linux-arm64`; one matching entry is sufficient.
-+- Keep `artifacts` keyed by `linux-amd64` or `linux-arm64` for response compatibility.
-+- [software-agent-sdk PR #6792](https://github.com/OpenHands/software-agent-sdk/pull/6792) adds optional `additional_artifacts` for `darwin-amd64`, `darwin-arm64`, and `windows-amd64`. Schema v1 still requires at least one canonical Linux artifact. Unknown platforms are ignored, and `artifacts` takes precedence on duplicate keys. This is an unreleased dependency; older servers ignore the new field and do not support macOS or Windows backends. Windows requires a native `.exe` entrypoint and its bundled runtime; `.cmd`/`.bat` entrypoints are rejected. The same structured `argv` applies to each platform.
-+- That PR also materializes contained symbolic links to regular files during archive extraction. Absolute, escaping, unresolved and cyclic links remain rejected; no filesystem symlinks are created. Official code-server archives require this behavior. Validate against the dependency's head until a containing release is available; do not claim released-server support before then.
- - Declare exactly one artifact source: either a package-relative, contained `.tar.gz` `path`, or a credential-free HTTPS `.tar.gz` `url`.
- - For remote archives, optionally set `strip_components` to an integer from 0 through 16; it defaults to 0 and is invalid for local paths.
- - Set `sha256` to exactly 64 lowercase hexadecimal characters. Remote downloads are accepted only when this digest matches.Supporting files
| File | Change |
|---|---|
| .github/workflows/vscode-backend-smoke.yml | +47 / −0 |
| .pr/vscode-design.html | +226 / −0 |
| apps/catalog.json | +1 / −1 |
| apps/vscode/README.md | +26 / −2 |
| apps/vscode/canvas-extension.json | +52 / −9 |
| apps/vscode/scripts/package.mjs | +1 / −1 |
| apps/vscode/scripts/smoke_backend.py | +46 / −0 |
| skills/canvas-extension-api/references/v1-contract.md | +9 / −1 |
| tests/test_vscode_app.py | +3 / −3 |
Temporary PR review aid. The repository release workflow removes root .pr artifacts after merge.