# Code

**Page:** kit/code

[Download Raw Markdown](./kit/code.md)

---

# 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`](/api/code/instance-management/) - Spawn/reuse VS Code instance
- Parameters: `folder`, `workspace`, `extension`, `ew`, `locale`

**Authentication**:
- [`POST /api/v1/code/mint-key`](/api/code/) - Generate server web key
- [`GET /api/v1/code/login`](/api/code/) - Get login page
- [`POST /api/v1/code/login`](/api/code/) - Submit login credentials
- [`GET /api/v1/code/logout`](/api/code/) - Logout and clear session

**Extensions**:
- [`POST /api/v1/code/extensions/install`](/api/code/instance-management/) - Install a VS Code extension

**Health & Status**:
- [`GET /api/v1/code/health`](/api/code/health-monitoring/) - Orchestrator health check

## Basic Instance

Spawn VS Code for a folder:


  
    ```bash
    # 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
    ```
  
  
    ```typescript
    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();
    ```
  
  
    ```bash
    # 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"
    ```
  




Returns HTML page with iframe embedding VS Code.

## 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

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

```bash
# 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):

```bash
# 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:



**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:**



Response:
```json
{
  "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