Skip to main content
This example demonstrates running code-server (VS Code in the browser) within OpenSandbox, providing a full development environment accessible through a web browser.

​
Overview

The VS Code sandbox image includes:
  • code-server (VS Code Web) pre-installed
  • Non-root user (vscode) for security
  • Workspace directory at /workspace
  • Full VS Code extension support

​
Building the Image

Build the VS Code sandbox image from the Dockerfile: 
cd examples/vscode
docker build -t opensandbox/vscode:latest .

​
Pull Pre-built Image

Alternatively, pull the pre-built image: 
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/vscode:latest

​
Setup OpenSandbox Server

Start the local OpenSandbox server: 
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server

​
Complete Example

This example creates a sandbox with code-server running and provides browser access: 
import asyncio
import os
from datetime import timedelta

from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.models.execd import RunCommandOpts


async def _print_logs(label: str, execution) -> None:
    """Helper to print execution logs"""
    for msg in execution.logs.stdout:
        print(f"[{label} stdout] {msg.text}")
    for msg in execution.logs.stderr:
        print(f"[{label} stderr] {msg.text}")
    if execution.error:
        print(f"[{label} error] {execution.error.name}: {execution.error.value}")


async def main() -> None:
    domain = os.getenv("SANDBOX_DOMAIN", "localhost:8080")
    api_key = os.getenv("SANDBOX_API_KEY")
    image = os.getenv(
        "SANDBOX_IMAGE",
        "opensandbox/vscode:latest",
    )
    python_version = os.getenv("PYTHON_VERSION", "3.11")
    code_port = int(os.getenv("CODE_PORT", "8443"))

    config = ConnectionConfig(
        domain=domain,
        api_key=api_key,
        request_timeout=timedelta(seconds=60),
    )

    # Create sandbox with environment variables
    env = {"PYTHON_VERSION": python_version}
    sandbox = await Sandbox.create(
        image,
        connection_config=config,
        env=env,
    )

    async with sandbox:
        # Start code-server with authentication disabled
        start_exec = await sandbox.commands.run(
            f"code-server --bind-addr 0.0.0.0:{code_port} --auth none /workspace",
            opts=RunCommandOpts(background=True),
        )
        await _print_logs("code-server", start_exec)

        # Get the proxied endpoint
        endpoint = await sandbox.get_endpoint(code_port)
        print("\nVS Code Web endpoint:")
        print(f"  http://{endpoint.endpoint}/")

        print("\nKeeping sandbox alive for 10 minutes. Press Ctrl+C to exit sooner.")
        try:
            await asyncio.sleep(600)
        except KeyboardInterrupt:
            print("Stopping...")
        finally:
            await sandbox.kill()


if __name__ == "__main__":
    asyncio.run(main())
Run the example: 
uv pip install opensandbox
uv run python examples/vscode/main.py

​
Example Output

The script will start code-server and output the accessible URL: 
[code-server stdout] [2025-03-01T10:30:00.123Z] info  code-server 4.23.1 abc123
[code-server stdout] [2025-03-01T10:30:00.124Z] info  Using user-data-dir /home/vscode/.local/share/code-server
[code-server stdout] [2025-03-01T10:30:00.234Z] info  HTTP server listening on http://0.0.0.0:8443/

VS Code Web endpoint:
  http://127.0.0.1:48379/proxy/8443/

Keeping sandbox alive for 10 minutes. Press Ctrl+C to exit sooner.

​
Screenshots

​
Terminal Access

VS Code terminal

​
Full VS Code Interface

VS Code interface

​
Features

​
Full VS Code Experience

  • Complete VS Code interface in the browser
  • Extension support
  • Integrated terminal
  • File explorer and editor
  • Git integration
  • Debugging support

​
Remote Development

  • Access your development environment from anywhere
  • No local installation required
  • Consistent environment across devices
  • Shareable development environments

​
Customization

  • Install VS Code extensions
  • Configure settings and themes
  • Add language servers and tools
  • Mount custom workspaces

​
Configuration Options

​
code-server Arguments

code-server --bind-addr 0.0.0.0:8443 \
  --auth none \
  --disable-telemetry \
  /workspace
ArgumentDescription
--bind-addrAddress and port to bind to
--authAuthentication method (none, password)
--disable-telemetryDisable telemetry
/workspaceInitial workspace directory

​
Environment Variables

VariableDefaultDescription
SANDBOX_DOMAINlocalhost:8080OpenSandbox server address
SANDBOX_API_KEY-API key for authentication
SANDBOX_IMAGEopensandbox/vscode:latestDocker image to use
PYTHON_VERSION3.11Python version in sandbox
CODE_PORT8443Port for code-server

​
Use Cases

​
Cloud Development

  • Provide browser-based IDEs to users
  • Enable development without local setup
  • Support for teaching and training
  • Temporary development environments

​
AI-Assisted Development

  • Give AI agents access to a full development environment
  • Enable code editing and execution
  • Test code in isolated environments
  • Automate development workflows

​
Code Review and Collaboration

  • Share development environments with team members
  • Review code in a live environment
  • Pair programming over the web
  • Demo features in progress

​
Security Considerations

  • Authentication: Example disables auth for simplicity. Enable --auth password for production.
  • Network Isolation: Sandbox provides network isolation from host.
  • User Permissions: Runs as non-root vscode user.
  • Temporary Environments: Sandboxes can be destroyed after use.

​
Adding Extensions

Install VS Code extensions in the running sandbox: 
# Install an extension using code-server CLI
await sandbox.commands.run(
    "code-server --install-extension ms-python.python"
)

​
Mounting Files

Mount files or directories into the workspace: 
# Upload files to the workspace
await sandbox.files.write(
    "/workspace/app.py",
    b"print('Hello from OpenSandbox!')"
)

# Or download files from the workspace
file_content = await sandbox.files.read_bytes("/workspace/output.txt")

​
References

Build docs developers (and LLMs) love

Get started for freeTalk to us