sbx/code-server-kit repository overview

⁠code-server

A mixin that installs code-server⁠ and runs it as a background service on port 8080, with the Claude Code VS Code extension⁠ pre-installed. The kit declares port 8080 in network.publishedPorts, so the sandbox runtime publishes it on an ephemeral host port at start time — no separate sbx ports --publish step is needed. You get a web-based VS Code pointed at the sandbox workspace with a native Claude panel that shares credentials and conversation history with the claude CLI agent.

⁠Usage

Pair it with the built-in claude agent, from its published OCI artifact on Docker Hub:

sbx run claude --kit "docker.io/sbx/code-server-kit:latest" ~/my-project

Or from a git URL targeting this repo:

sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=code-server" ~/my-project

Once the sandbox is up, find the assigned host port:

sbx ports <sandbox-name>

Open http://localhost:<host-port>/ in a browser. code-server opens the sandbox workspace on launch — no File → Open Folder… needed. Click the Spark icon in the editor toolbar (top-right) to open the Claude Code panel; it picks up the same auth the CLI uses.

If you'd rather pin the host port to a fixed value, the classic sbx ports <sandbox-name> --publish 8080:8080/tcp still works alongside the declared ephemeral binding.

If the page doesn't load, check the startup log inside the sandbox:

sbx exec -it <sandbox-name> -- cat /tmp/code-server.log

⁠How the workspace path gets set

The kit uses commands.initFiles to write a tiny wrapper script at /home/agent/.local/bin/start-code-server.sh each time the sandbox starts. ${WORKDIR} expands to the actual workspace path at that point, so the script has the correct folder baked in before code-server runs. commands.startup invokes the script directly, backgrounded with nohup … &, stdout/stderr redirected to /tmp/code-server.log. mode: "0755" on the initFile makes the generated file executable.

This is the cleanest place to see why initFiles exists — the workspace path isn't known until the sandbox starts, so it can't be hardcoded in a static file or a shell-string command.

⁠About authentication

The startup command passes --auth none. code-server is only reachable through the runtime's published-port binding, which lands on localhost on your host by default, so you're already behind the sandbox boundary. If you want a password anyway, override the startup command in a forked kit.

⁠Claude Code extension auth

The extension and the claude CLI share state in ~/.claude/ and both read ANTHROPIC_API_KEY from the environment. The built-in claude agent already routes Anthropic auth through the sandbox credential proxy, so the extension inherits that: no separate sign-in required.

If the extension shows a sign-in prompt when you open the Spark panel, check that the underlying CLI is authenticated first (run claude in the integrated terminal inside VS Code, or sbx attach to the agent).

⁠Shipped VS Code settings

The kit drops a minimal User/settings.json into code-server's user data directory to reduce first-launch noise:

{
  "workbench.startupEditor": "none",
  "chat.commandCenter.enabled": false,
  "workbench.tips.enabled": false,
  "telemetry.telemetryLevel": "off",
  "claudeCode.preferredLocation": "sidebar"
}

• startupEditor: "none" — no welcome page on launch
• chat.commandCenter.enabled: false — hides the built-in chat widget that newer VS Code ships in the top bar
• claudeCode.preferredLocation: "sidebar" — Claude opens in the right-hand sidebar rather than a full editor tab

VS Code doesn't have a clean "auto-open this view on startup" setting, so Claude still needs one click on the Spark icon the first time. After that, state persists across browser reloads (the sandbox's persistence: persistent volume preserves ~/.local/share/code-server/).

Edit files/home/.local/share/code-server/User/settings.json in a fork to customize further.

⁠Can I run a native editor (Cursor, Zed, …) like this?

Not through this kit, but it's plausible as a follow-up recipe. code-server works because VS Code has a first-party web server mode — Cursor, Zed, and most other editors don't. To run one of those in a sandbox and use it from the host browser, the cleanest path is probably xpra⁠ with its HTML5 client: xpra starts the editor under a virtual display and serves its window to a browser over HTTPS, without the latency and clipboard limitations of VNC. A kit would install xpra + the editor, then run xpra start --start-child=<editor> --bind-tcp=0.0.0.0:14500 --html=on as a startup command.