Code

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

• 🚀 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 are reused without re-spawning

API Endpoints Summary

All endpoints accessed relative to your Code Orchestrator URL:

https://PROJECT_ID-CONTAINER_ID-code-1.SERVER.containers.hoody.com

Instance Rendering:

• GET /api/v1/code?folder=/path - Spawn/reuse VS Code instance
• Parameters: folder, workspace, extension, ew, locale

Authentication:

• POST /api/v1/code/mint-key - Generate server web key
• GET /api/v1/code/login - Get login page
• POST /api/v1/code/login - Submit login credentials
• GET /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

Spawn VS Code for a folder:

CLI

# Spawn a VS Code instance
hoody code open --folder "/home/user/my-project"

# List installed extensions
hoody code extensions list

# Check health
hoody code health

SDK

import { HoodyClient } from '@hoody-ai/hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const containerClient = await client.withContainer({ id: CONTAINER_ID, project_id: PROJECT_ID, server: SERVER });

// Get VS Code instance
const instance = await containerClient.code.vscode.getVSCode({
  folder: '/home/user/my-project',
});

// List extensions
const extensions = await containerClient.code.extensions.list();

// Check health
const health = await containerClient.code.health.check();

HTTP

# Spawn VS Code instance (opens in browser)
curl "https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.com/api/v1/code?folder=/home/user/my-project"

# Check health
curl "https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.com/api/v1/code/health"

GET Spawn VS Code instance for a project folder

/api/v1/code?folder=/home/user/my-project

Fetch cURL PowerShell

▶ Run 📋

Response

Click "Run" to execute the request

Returns HTML page with iframe embedding VS Code.

Extension-Only Mode

Embed specific VS Code extensions:

Python extension in isolated view:

GET Spawn VS Code with Python extension only

/api/v1/code?folder=/workspace&extension=ms-python.python

Fetch cURL PowerShell

▶ Run 📋

Response

Click "Run" to execute the request

Docker extension:

GET Spawn VS Code with Docker extension only

/api/v1/code?folder=/workspace&extension=ms-azuretools.vscode-docker

Fetch cURL PowerShell

▶ Run 📋

Response

Click "Run" to execute the request

Effect: Hides file explorer, focuses on extension UI only.

Password Protection

Password-based authentication is configured when the Code service is launched (via CLI flag). Submit credentials through the login endpoint:

# Submit login credentials
curl -X POST "https://PROJECT_ID-CONTAINER_ID-code-1.SERVER.containers.hoody.com/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.com/api/v1/code/mint-key"

Instance Isolation

Each instance creates:

Per-instance state:

• Installed extensions live in the extensions directory (e.g. /home/user/.local/share/hoody-code/extensions)
• User settings and keybindings are stored separately
• The last opened folder/workspace is persisted in settings for the next session

Instance Lifecycle

First Request - Fresh spawn:

• Show loading overlay
• Spawn VS Code process
• Configure based on parameters
• Return iframe when ready

Subsequent Requests - Reuse:

• No loading overlay
• Reuse existing instance
• Same state preserved

Reuse: Existing instances are reused without re-spawning.

Custom Configuration

Use the supported query parameters to configure an instance:

GET Spawn VS Code with custom locale

/api/v1/code?folder=/workspace&locale=fr

Fetch cURL PowerShell

▶ Run 📋

Response

Click "Run" to execute the request

Supported parameters:

• folder / workspace — what to open (stored in settings for the next session)
• extension — open in extension-only mode (PUBLISHER.NAME)
• ew — “empty window” flag; clears the last opened folder/workspace
• locale — display language (IETF language tag, e.g. fr)

Health Monitoring

Health Check:

GET Check orchestrator health status

/api/v1/code/health

Fetch cURL PowerShell

▶ Run 📋

Response

Click "Run" to execute the request

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": "HoodyMonitor/1.0"
}

Use Cases

Multi-Tenant Development

Create isolated environment per user - complete setting separation, no cross-contamination, independent extension installations.

Embedded Development Tools

Embed specific extensions in applications - use extension-only mode, hide file explorer, focus on functionality.

Educational Platforms

Sandboxed coding environments - password-protect student instances, pre-configure extensions, monitor health, clean instances between sessions.

CI/CD Automation

Automated code editing - spawn temporary instances, execute through extensions, clean up after completion, integrate with build pipelines.

Extension Showcases

Demonstrate VS Code extensions - embed in documentation, show extension capabilities, provide interactive demos, no installation required for users.

Best Practices

Instance Strategy

Use separate folders per project for isolation, plan capacity for expected load.

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

Configure passwords via CLI flag when launching the Code service, rotate passwords regularly, be aware URLs may leak in logs/history.

Resource Management

Monitor health via /api/v1/code/health, implement cleanup for old instances, track data directory disk usage.

Extension Configuration

Validate extension IDs (PUBLISHER.NAME), test compatibility before embedding, document system dependencies, pin versions for consistency.

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 happens on first request vs. a reused instance? A fresh spawn starts a new VS Code process and (when --page-loader is enabled) shows a branded loading overlay during initialization; a reused instance loads its existing process without re-spawning.

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

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

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

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

Cause: Too many instances running. Solution: Check health with /api/v1/code/health, implement instance cleanup policy, increase server resources.

Instance State Lost

Cause: Data directory cleared. Solution: Don’t delete data directories of active instances, back up critical instance data.

Health Check Fails

Cause: Orchestrator down or network issue. Solution: Verify the orchestrator process is running, check network connectivity to the Code Orchestrator URL, and review orchestrator logs for errors.

What’s Next

Instance Management Spawn and configure VS Code instances

Health Monitoring Track orchestrator and instance status