VS Code Integration

Sink includes an integrated VS Code (via code-server), allowing you to edit and manage files in your Workspace directly from a browser. This guide explains how to enable and use VS Code features.

What is VS Code Integration?

Sink integrates code-server, which is VS Code running in a browser. It allows you to:

• Browse and edit all files in your Workspace directory
• View task-related files and directory structure
• Use the full VS Code feature set in your browser
• Avoid installing any additional local software

Accessing VS Code

In the Sink Web UI:

1. Click Code Server in the main menu
2. Or visit directly: http://localhost:5000/api/vscode/default (replace default with your workspace ID, and adjust the address and port according to your Gateway configuration)

VS Code Management Page

The VS Code management page provides the following features:

Starting VS Code

If VS Code is not yet running, you’ll see a Start button. Click it to launch the code-server process.

The first startup may take 10-30 seconds, so please wait patiently.

Viewing Status

The page header shows the current status of VS Code:

• Idle — code-server process is not yet running
• Starting — code-server is in the process of starting
• Ready — code-server is running and ready to use
• Stopping — code-server is shutting down
• Error — code-server encountered an error

Opening VS Code

Once VS Code is ready, you can open it in two ways:

Open in New Tab

Click the Open in New Tab button to open VS Code in a new browser tab, providing maximum workspace.

Open in Canvas

Click the Open in Canvas button to embed VS Code as a window in the Canvas, allowing you to view tasks and edit code simultaneously.

Stopping VS Code

If you need to free up system resources, click the Stop button to shut down VS Code. Stopping is safe and you can restart it at any time.

Working in VS Code

File Browsing

When VS Code is open, the left sidebar displays your Workspace’s file tree. You can:

• Browse files and folders — Click to expand or collapse directories
• Create new files — Right-click in a directory and select “New File”
• Edit files — Click a file to open it in the editor

Viewing Task Files

Task files in your Workspace are stored in the .sink/tasks/ directory:

<workspace-path>/
  .sink/
    tasks/
      <task-id>/           # Each task's working directory
        .sink/          # Task-local configuration
        CLAUDE.md          # Agent instruction file (reference)
        ...                # Task-related files

You can browse these files through VS Code, but typically don’t need to edit them directly.

Configuring Workspace

The .sink/ directory contains Workspace-level configuration files:

• settings.json — Environment variables and logging settings
• mcp.json — MCP Server configuration
• runtimes.json — Agent Runtime configuration
• profiles/ — Agent Profile definitions
• skills/ — Agent Skill definitions

These configuration files can be edited directly in VS Code, and changes take effect when the next task starts.

Code Editing

VS Code provides complete code editing capabilities:

• Syntax highlighting — Automatically recognizes file types
• Auto-indentation — Intelligent code formatting
• Find and replace — Ctrl+H to open the replace dialog
• Multi-select editing — Ctrl+D to select the next match
• Built-in terminal — `Ctrl+`` to open a terminal and run commands in the Workspace

Configuring VS Code

Extensions and Themes

code-server supports many VS Code extensions. You can install extensions through VS Code’s extension marketplace.

Note: Some computationally intensive extensions may have reduced performance in a browser environment.

Keyboard Shortcuts

All standard VS Code keyboard shortcuts work fully in code-server:

Common Scenarios

Scenario 1: Viewing Task Configuration

1. Start VS Code
2. Open the .sink/ directory
3. Edit Profile files in profiles/
4. After saving, new tasks will use the updated configuration

Scenario 2: Configuring MCP Servers

1. Start VS Code
2. Open .sink/mcp.json
3. Add or edit MCP Server configurations
4. Save the file; changes take effect when the next task starts

Scenario 3: Viewing Code in Canvas

1. Go to the Canvas page
2. Click the Open in Canvas button
3. VS Code window appears in the Canvas
4. View tasks and edit code simultaneously

Scenario 4: Running Commands

1. Start VS Code
2. Press `Ctrl+`` to open the terminal
3. Run any shell command in the Workspace directory

Important Notes

Browser Requirements

• Requires a modern browser (Chrome, Firefox, Safari, Edge, etc.)
• Some advanced features may require specific browser capabilities
• Best performance browsers: Chrome and Firefox

File Size Limits

Editing very large files (>10MB) may cause browser performance degradation.

Storage Space

The code-server process consumes some system memory and storage space. If you don’t use it for extended periods, you can stop it to free up resources.

Troubleshooting

VS Code Fails to Start

Symptom: After clicking the start button, it still shows “Not Started”

Things to check:

1. Verify the system has sufficient memory and storage space
2. Check the Gateway logs for detailed error information
3. Try running code-server manually in the Workspace:

   code-server --version
   

If the command is not found, you may need to configure the code-server path in settings.json — see the example below.

Configuring the code-server command

{
  "ide": {
    "codeServer": {
      "command": "/usr/local/bin/code-server"
    }
  }
}

VS Code is Unresponsive or Slow

Symptom: VS Code loads slowly after starting or has input lag

Solutions:

1. Refresh the browser
2. Close other browser tabs to free up memory
3. Stop and restart VS Code:
   • Click the Stop button
   • Wait for the shutdown to complete
   • Click the Start button to restart
4. Check your network connection quality

Cannot Save Files

Symptom: Files cannot be saved after editing

Things to check:

1. Check file permissions—run in the terminal:

   ls -l /path/to/file
   

2. Verify sufficient disk space
3. Ensure no other process is locking the file

VS Code Window Not Showing in Canvas

Symptom: After clicking “Open in Canvas”, VS Code doesn’t appear in the Canvas

Solutions:

1. Refresh the Canvas page
2. Ensure VS Code is started and ready (check the VS Code management page)
3. Manually open VS Code in a new browser tab to verify it works normally

Next Steps

1. Quick Start Tutorial — Create your first task
2. Canvas Workspace — Learn how to organize multiple windows in Canvas