VS Code as a URL - Spawn isolated VS Code instances on-demand through HTTP requests, embed specific extensions in your applications, password-protect environments, and manage multiple development workspaces from a single orchestrator.
What You Can Do
Section titled “What You Can Do”- 🚀 Spawn Instances - Create isolated VS Code environments via HTTP
- 🧩 Extension Embedding - Open specific extensions in isolated views
- 🔐 Password Protection - Password authentication for secure access
- 📂 Multi-Workspace - Independent settings and extensions per instance
- 🎯 Instance Isolation - Separate data directories per instance
- 📊 Health Monitoring - Track orchestrator status and running instances
- ⚙️ Custom Configuration - Pass CLI flags via query parameters
- 🔄 Instance Reuse - Existing instances load instantly without spawning
API Endpoints Summary
Section titled “API Endpoints Summary”All endpoints accessed relative to your Code Orchestrator URL:
https://PROJECT_ID-CONTAINER_ID-code-1.SERVER.containers.hoody.icuInstance Rendering:
GET /api/v1/code?folder=/path- Spawn/reuse VS Code instance- Parameters:
extension,locale, etc.
Authentication:
POST /api/v1/code/mint-key- Generate server web keyGET /api/v1/code/login- Get login pagePOST /api/v1/code/login- Submit login credentialsGET /api/v1/code/logout- Logout and clear session
Extensions:
POST /api/v1/code/extensions/install- Install a VS Code extension
Health & Status:
GET /api/v1/code/health- Orchestrator health check
Basic Instance
Section titled “Basic Instance”Spawn VS Code for a folder:
# Spawn a VS Code instancehoody code open --folder "/home/user/my-project"
# List installed extensionshoody code extensions list
# Check healthhoody code healthimport { HoodyClient } from '@hoody-ai/hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN });const containerClient = await client.withContainer({ id: CONTAINER_ID, project_id: PROJECT_ID, server: SERVER });
// Get VS Code instanceconst instance = await containerClient.code.vscode.getVSCode({ folder: '/home/user/my-project',});
// List extensionsconst extensions = await containerClient.code.extensions.list();
// Check healthconst health = await containerClient.code.health.check();# Spawn VS Code instance (opens in browser)curl "https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.icu/api/v1/code?folder=/home/user/my-project"
# Check healthcurl "https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.icu/api/v1/code/health"Returns HTML page with iframe embedding VS Code.
Extension-Only Mode
Section titled “Extension-Only Mode”Embed specific VS Code extensions:
Python extension in isolated view:
Docker extension:
Effect: Hides file explorer, focuses on extension UI only.
Password Protection
Section titled “Password Protection”Password-based authentication is configured when the Code service is launched (via CLI flag). Submit credentials through the login endpoint:
# Submit login credentialscurl -X POST "https://PROJECT_ID-CONTAINER_ID-code-1.SERVER.containers.hoody.icu/api/v1/code/login" \ -d 'password=my-password'The mint-key endpoint is separate — it generates or retrieves the 32-byte server web key used internally for encryption (not a password API):
# Generate/retrieve server web key (binary response)curl -X POST "https://PROJECT_ID-CONTAINER_ID-code-1.SERVER.containers.hoody.icu/api/v1/code/mint-key"Instance Isolation
Section titled “Instance Isolation”Each instance creates:
Data Directory:
/data/instances/├── extensions/ # Installed extensions├── User/ # Settings, keybindings└── workspace/ # Workspace stateInstance Lifecycle
Section titled “Instance Lifecycle”First Request - Fresh spawn:
- Show loading overlay
- Spawn VS Code process
- Configure based on parameters
- Return iframe when ready
Subsequent Requests - Instant reuse:
- No loading overlay
- Reuse existing instance
- Same state preserved
- Instant response
Reuse: Existing instances load instantly without re-spawning.
Custom Configuration
Section titled “Custom Configuration”Pass any VS Code CLI flag:
Parameter Forwarding:
- Boolean flags →
--flag(no value) - Key-value →
--key value - Reserved:
extension(not forwarded to CLI)
Health Monitoring
Section titled “Health Monitoring”Health Check:
Response:
{ "status": "ok", "service": "hoody-code", "started": "2024-01-15T10:30:00.000Z", "built": "2024-01-10T09:00:00.000Z", "pid": 1234, "ip": "10.0.0.12", "memory": { "rss": 44145050, "heap": 29884416 }, "fds": 42, "userAgent": "hoody-code/1.0"}Use Cases
Section titled “Use Cases”Multi-Tenant Development
Section titled “Multi-Tenant Development”Create isolated environment per user - complete setting separation, no cross-contamination, independent extension installations.
Embedded Development Tools
Section titled “Embedded Development Tools”Embed specific extensions in applications - use extension-only mode, hide file explorer, focus on functionality.
Educational Platforms
Section titled “Educational Platforms”Sandboxed coding environments - password-protect student instances, pre-configure extensions, monitor health, clean instances between sessions.
CI/CD Automation
Section titled “CI/CD Automation”Automated code editing - spawn temporary instances, execute through extensions, clean up after completion, integrate with build pipelines.
Extension Showcases
Section titled “Extension Showcases”Demonstrate VS Code extensions - embed in documentation, show extension capabilities, provide interactive demos, no installation required for users.
Best Practices
Section titled “Best Practices”Instance Strategy
Section titled “Instance Strategy”Use separate folders per project for isolation, plan capacity for expected load.
Folder Paths
Section titled “Folder Paths”Always use absolute paths (/home/user/project), never use relative paths or .., validate paths to prevent traversal, ensure folders exist before spawning.
Password Security
Section titled “Password Security”Configure passwords via CLI flag when launching the Code service, rotate passwords regularly, be aware URLs may leak in logs/history.
Resource Management
Section titled “Resource Management”Monitor health via /api/v1/code/health, implement cleanup for old instances, track data directory disk usage.
Extension Configuration
Section titled “Extension Configuration”Validate extension IDs (PUBLISHER.NAME), test compatibility before embedding, document system dependencies, pin versions for consistency.
Useful Questions
Section titled “Useful Questions”Q: How many instances can I run? Practically limited by memory/CPU on the container.
Q: Do instances persist after restart? Data directories persist (extensions, settings), running processes don’t - must re-spawn.
Q: Can I customize VS Code appearance?
Use CLI flags via parameters: locale, load custom CSS/JS, configure through extension settings.
Q: How do I update extensions? Extensions installed per instance directory, update via VS Code UI within instance, or restart with fresh data directory.
Q: What’s the startup time for new instances? Fresh spawn: 5-15 seconds depending on extensions, reuse existing: instant (under 1 second), loading overlay hides spawn delay.
Q: Can I run multiple Code services? Yes - use different instance numbers (code-1, code-2), each has independent orchestrator, separate port ranges and data directories.
Q: How do I embed in my app?
Request the URL with extension parameter, embed returned page in iframe, handle authentication if needed, monitor health endpoint.
Troubleshooting
Section titled “Troubleshooting”Instance Won’t Start
Section titled “Instance Won’t Start”Cause: Folder not found, invalid parameters.
Solution: Verify folder exists and is absolute path, ensure required folder parameter present, check orchestrator logs.
Extension Not Loading
Section titled “Extension Not Loading”Cause: Invalid extension ID or web-incompatible extension.
Solution: Verify ID format PUBLISHER.NAME, check extension supports web version, test without extension-only mode first, visit marketplace to confirm ID.
Password Authentication Fails
Section titled “Password Authentication Fails”Cause: Incorrect password or login endpoint misuse. Solution: Verify password matches the one configured via CLI flag, check URL encoding of form body, confirm the service was started with password authentication enabled.
High Resource Usage
Section titled “High Resource Usage”Cause: Too many instances running.
Solution: Check health with /api/v1/code/health, implement instance cleanup policy, increase server resources.
Instance State Lost
Section titled “Instance State Lost”Cause: Data directory cleared. Solution: Don’t delete data directories of active instances, back up critical instance data.
Health Check Fails
Section titled “Health Check Fails”Cause: Orchestrator down or network issue. Solution: Verify orchestrator process running, check network connectivity, ensure port 8080 accessible, review orchestrator logs for errors.