Documentation Index
Fetch the complete documentation index at: https://mintlify.com/alibaba/OpenSandbox/llms.txt
Use this file to discover all available pages before exploring further.
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())
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
Full 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
| Argument | Description |
|---|
--bind-addr | Address and port to bind to |
--auth | Authentication method (none, password) |
--disable-telemetry | Disable telemetry |
/workspace | Initial workspace directory |
Environment Variables
| Variable | Default | Description |
|---|
SANDBOX_DOMAIN | localhost:8080 | OpenSandbox server address |
SANDBOX_API_KEY | - | API key for authentication |
SANDBOX_IMAGE | opensandbox/vscode:latest | Docker image to use |
PYTHON_VERSION | 3.11 | Python version in sandbox |
CODE_PORT | 8443 | Port 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