Skip to content

Commit 72a784e

Browse files
djs55claude
djs55
and
claude
committed
feat(kits): add vscode mixin — native VS Code via --display
Installs VS Code from Microsoft's apt repo and starts it as a Wayland client on the host compositor, opening the sandbox workspace. Requires --display (behind feature.sandbox-display). Includes a README with prerequisites and agentInstructions so the running agent knows the editor is open. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: David Scott <dave@recoil.org>
1 parent fa56d68 commit 72a784e

2 files changed

Lines changed: 223 additions & 0 deletions

File tree

‎vscode/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# vscode
2+
3+
> **Experimental.** This kit depends on `--display`, which is an experimental
4+
> sbx feature gated behind a feature flag. See [Prerequisites](#prerequisites).
5+
6+
A mixin that installs [Visual Studio Code](https://code.visualstudio.com/) and
7+
launches it as a native window on the host desktop. The editor opens the
8+
sandbox workspace on startup, so files you create or edit through the agent are
9+
immediately visible in VS Code, and edits you make in the editor are immediately
10+
visible to the agent.
11+
12+
> **Alternative:** if you want browser-accessible VS Code without the `--display`
13+
> flag, use the [`code-server`](../code-server/) kit instead.
14+
15+
## Prerequisites
16+
17+
**sbx v0.39.0 or later** is required. Earlier versions set `WAYLAND_DISPLAY`
18+
container-wide in a way that caused the clipboard bridge to clobber the
19+
compositor socket, so VS Code never mapped a window.
20+
21+
VS Code renders to the host compositor via `--display`, which requires enabling
22+
a feature flag:
23+
24+
```console
25+
$ sbx settings set platform.allowExperimentalFeatures true
26+
$ sbx settings set feature.sandbox-display true
27+
```
28+
29+
## Usage
30+
31+
```console
32+
$ sbx run claude \
33+
--display \
34+
--kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vscode" \
35+
~/my-project
36+
```
37+
38+
The VS Code window appears on your host desktop. The `claude` terminal session
39+
runs concurrently in the same sandbox — both share the workspace at the path
40+
you passed.
41+
42+
You can use any agent that accepts `--kit`:
43+
44+
```console
45+
$ sbx run shell --display --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=vscode" ~/my-project
46+
```
47+
48+
## First install
49+
50+
On the first `sbx run`/`sbx create` with this kit, VS Code is downloaded and
51+
installed from Microsoft's apt repository inside the sandbox. This takes roughly
52+
30–60 seconds depending on network speed. Subsequent starts reuse the installed
53+
binary from the sandbox's persistent overlay.
54+
55+
## How the display surface works
56+
57+
`--display` provisions a Wayland socket inside the microVM and connects it to
58+
the host compositor. VS Code is started with `--ozone-platform=wayland`, so its
59+
window is a first-class Wayland surface on the host — resize, focus, and
60+
clipboard work as expected.
61+
62+
The startup command runs as root and immediately drops to uid 1000 via `setpriv`
63+
before exec'ing VS Code. This keeps the kit portable across base templates that
64+
use different usernames at uid 1000 (e.g. `agent` in the standard
65+
`docker/sandbox-templates`).
66+
67+
## Troubleshooting
68+
69+
**VS Code window doesn't appear**
70+
71+
Check that you passed `--display` to `sbx run`/`sbx create` and that
72+
`feature.sandbox-display` is enabled:
73+
74+
```console
75+
$ sbx settings get feature.sandbox-display
76+
```
77+
78+
Also check that sbx is v0.39.0 or later (`sbx version`).
79+
80+
**VS Code window was closed — how to reopen it**
81+
82+
The launch wrapper is on PATH inside the sandbox. Run it from any terminal
83+
session in the sandbox:
84+
85+
```console
86+
$ code &
87+
```
88+
89+
**Extension marketplace is unavailable**
90+
91+
The kit allows `marketplace.visualstudio.com` and its CDN hosts. If you're
92+
seeing marketplace errors, check that your sandbox's network policy isn't
93+
overriding the allow-list with a more restrictive rule:
94+
95+
```console
96+
$ sbx policy log <sandbox-name>
97+
```

‎vscode/spec.yaml‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
schemaVersion: "2"
2+
kind: mixin
3+
name: vscode
4+
displayName: Visual Studio Code (native, via --display)
5+
description: Installs VS Code from Microsoft's apt repository and starts it as a Wayland client on the host desktop, opening the sandbox workspace. Requires `--display` at sandbox creation time and the `feature.sandbox-display` feature flag — see the README.
6+
permissions:
7+
network:
8+
allow:
9+
# setup.install runs apt-get update, which refreshes every configured
10+
# apt source. The claude-code-docker base template pre-configures
11+
# Docker's apt repo, so download.docker.com must be allowed even though
12+
# this kit doesn't install anything from it — apt-get exits 100 on the
13+
# first source metadata fetch that returns non-2xx. Ubuntu hosts amd64
14+
# packages on archive/security and arm64 packages on ports.ubuntu.com,
15+
# so all three Ubuntu hosts are listed for cross-arch coverage.
16+
- archive.ubuntu.com
17+
- security.ubuntu.com
18+
- ports.ubuntu.com
19+
- download.docker.com
20+
# Install-time: Microsoft's apt repo (signing key + .deb).
21+
- packages.microsoft.com
22+
# Runtime: VS Code's own update / telemetry / download endpoints.
23+
- update.code.visualstudio.com
24+
- vscode.download.prss.microsoft.com
25+
# Extensions: marketplace + CDN.
26+
- marketplace.visualstudio.com
27+
- "*.vscode-cdn.net"
28+
- "*.gallerycdn.vsassets.io"
29+
agentInstructions:
30+
content: |
31+
## VS Code
32+
33+
VS Code is running inside this sandbox. Its window is visible on the
34+
host desktop — it opened the sandbox workspace on startup, so any
35+
file you create or edit in the terminal is immediately visible in the
36+
editor, and vice versa.
37+
38+
If the user closes the VS Code window and wants to reopen it, run
39+
`code &` from any terminal inside the sandbox.
40+
41+
If the VS Code window is not visible at all, check that `--display`
42+
was passed at sandbox creation time and that the host compositor is
43+
running. The process runs backgrounded; it does not produce a log
44+
file by default.
45+
setup:
46+
install:
47+
- command: |
48+
set -euo pipefail
49+
50+
# apt's InRelease verification uses O_TMPFILE, which is incompatible
51+
# with the virtiofs overlay backing the container. Route the lists
52+
# directory through /dev/shm (a plain tmpfs) instead. The .deb cache
53+
# stays at its default location (/var/cache/apt/archives) because
54+
# /dev/shm's 64 MiB ceiling is too small for the full package set.
55+
mkdir -p /dev/shm/apt-lists
56+
APT_OPTS="-o DPkg::Lock::Timeout=600 -o Dir::State::Lists=/dev/shm/apt-lists"
57+
export TMPDIR=/dev/shm
58+
59+
apt-get $APT_OPTS update
60+
apt-get $APT_OPTS install -yy --no-install-recommends ca-certificates curl gnupg
61+
62+
install -d -m 0755 /usr/share/keyrings
63+
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \
64+
| gpg --dearmor > /usr/share/keyrings/packages.microsoft.gpg
65+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" \
66+
> /etc/apt/sources.list.d/vscode.list
67+
68+
apt-get $APT_OPTS update
69+
apt-get $APT_OPTS install -yy --no-install-recommends code dbus-x11
70+
71+
rm -rf /dev/shm/apt-lists
72+
apt-get clean
73+
user: "0"
74+
description: |
75+
Install Visual Studio Code from Microsoft's official APT repository,
76+
plus dbus-x11 (which provides dbus-run-session, needed by Electron to
77+
wire its IPC bus when no session bus is present in the container).
78+
79+
files:
80+
- path: /home/agent/.local/bin/code
81+
mode: "0755"
82+
description: Launch wrapper written at each startup so WORKSPACE_DIR is resolved at runtime.
83+
content: |
84+
#!/bin/sh
85+
if [ ! -S /run/display/wayland-0 ]; then
86+
echo "code: display socket not found at /run/display/wayland-0" >&2
87+
echo "This sandbox was not created with --display." >&2
88+
echo "" >&2
89+
echo "To fix, enable the experimental display feature and recreate:" >&2
90+
echo " sbx settings set platform.allowExperimentalFeatures true" >&2
91+
echo " sbx settings set feature.sandbox-display true" >&2
92+
echo " sbx run claude --display --kit <this-kit> <workspace>" >&2
93+
exit 1
94+
fi
95+
export WAYLAND_DISPLAY=/run/display/wayland-0
96+
HOME_DIR=$(getent passwd 1000 | cut -d: -f6)
97+
if [ -z "$HOME_DIR" ]; then
98+
echo "code: no user at uid 1000" >&2
99+
exit 1
100+
fi
101+
export HOME="$HOME_DIR"
102+
LAUNCH_DIR="$WORKSPACE_DIR"
103+
if [ -z "$LAUNCH_DIR" ]; then LAUNCH_DIR="$HOME_DIR"; fi
104+
exec dbus-run-session /usr/share/code/code \
105+
--ozone-platform=wayland \
106+
--disable-gpu \
107+
--disable-gpu-compositing \
108+
--no-sandbox \
109+
--disable-dev-shm-usage \
110+
--user-data-dir="$HOME_DIR/.vscode-user" \
111+
"$LAUNCH_DIR"
112+
113+
startup:
114+
- command:
115+
- setpriv
116+
- --reuid=1000
117+
- --regid=1000
118+
- --init-groups
119+
- /home/agent/.local/bin/code
120+
user: "0"
121+
background: true
122+
description: |
123+
Launch VS Code as a Wayland client opening the sandbox's workspace.
124+
Runs as root then drops to uid 1000 via setpriv. The window appears
125+
on the host compositor via the display surface provisioned by
126+
--display. Backgrounded so the agent's terminal keeps focus.

0 commit comments

Comments
 (0)