# 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 load instantly without spawning

## API Endpoints Summary

All endpoints accessed relative to your Code Orchestrator URL:
```
https://PROJECT_ID-CONTAINER_ID-code-1.SERVER.containers.hoody.icu
```

**Instance Rendering**:
- [`GET /api/v1/code?folder=/path`](/api/code/instance-management/) - Spawn/reuse VS Code instance
- Parameters: `extension`, `locale`, etc.

**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.icu', 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.icu/api/v1/code?folder=/home/user/my-project"

    # Check health
    curl "https://PROJECT-CONTAINER-code-1.SERVER.containers.hoody.icu/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.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):

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

Each instance creates:

**Data Directory**:
```
/data/instances/
├── extensions/ # Installed extensions
├── User/       # Settings, keybindings
└── workspace/  # Workspace state
```

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

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

**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": "hoody-code/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'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

### 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 orchestrator process running, check network connectivity, ensure port 8080 accessible, review orchestrator logs for errors.

## What's Next