> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usekolaos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VS Code, Cursor and Windsurf

> Connect your editor to your workstation, and work with discussions, previews, services and dotfiles from it.

KolaOS has two editor extensions. The **KolaOS** extension runs on your computer, signs you in, lists your workstations and connects your editor to one. The **KolaOS Workstation** extension runs inside the workstation and shows your discussions, previews and services. You install the first one, and it installs the second one in each workstation you connect to.

The extensions work in VS Code, Cursor and Windsurf. The browser IDE in each workstation comes with KolaOS Workstation installed. They are not yet published to the Visual Studio Marketplace or Open VSX. Until they are, use the [desktop app or the CLI](https://docs.usekolaos.com/development/desktop-and-ssh.md).

## Connect to a workstation

The KolaOS extension includes the KolaOS CLI, so you do not install anything else. Your editor also needs its Remote - SSH extension. VS Code uses Microsoft's Remote - SSH, and Cursor and Windsurf each ship their own.

**1. Sign in**

Open the KolaOS view in the activity bar and select **Sign in**. Complete the sign-in in your browser. If you already signed in with `kola login`, the extension uses that sign-in.

**2. Choose a workstation**

The view lists your workstation in each workspace with its state. Select **Start** or **Stop** next to a workstation to change its state.

**3. Connect**

Select **Connect**. The extension updates your SSH setup, starts the workstation, waits until it is running, and then opens a Remote-SSH window on it. Because the editor connects only to a running workstation, the first connection does not time out while the workstation starts.

You can also open a workstation from the dashboard. On your workstation's page, choose **Open in editor**, then VS Code, Cursor or Windsurf. The link opens your editor and connects to the workstation in the same way.

While you are connected, the status bar shows the workspace, the workstation's state and the AI budget for this month. When the budget is spent, the status bar shows that AI is blocked for the rest of the month.

## In the workstation

The **KolaOS Workstation** view has three sections.

| Section | What it shows |
| - | - |
| **Discussions** | Your discussions with Claude Code, Codex and OpenCode. These are the same discussions as in the desktop app. |
| **Services** | Your dotfiles and the services and tasks of each repository's `.kola/config.yaml`. |
| **Previews** | The ports your dev servers listen on, with their preview links. |

### Discussions

Select **New discussion**, choose the agent and the project folder, and enter a title. Open a discussion to read its transcript and send messages.

* Press Enter to send. During a turn, Enter adds your message to the running turn.
* Press Tab during a turn to queue a message for after the turn.
* Press Escape or select **Stop** to stop the turn.

When an agent asks for approval or asks a question, a notification appears. Answer it there, or open the discussion to answer in the transcript. An approval offers **Allow once**, **Allow for this discussion** and **Deny**.

To give an agent context, right-click and choose one of these:

* **Send selection to discussion** in the editor sends the selected text.
* **Send file to discussion** in the Explorer sends the file's path.
* **Send last output to discussion** in a terminal sends the output of the last command. It needs the terminal's shell integration, which is on by default.

### Previews

Each port that a dev server listens on appears with its process name. Select **Open preview** to open its link in your browser, where KolaOS checks your sign-in. Select **Share preview** to open your workstation's page in the dashboard, where you share a port with other people. See [Previews](https://docs.usekolaos.com/development/previews.md) for who can open a shared preview.

## Services and tasks

A repository can describe how to run itself in `.kola/config.yaml` at its root. KolaOS runs these commands in your workstation, so the dev server and its database are ready when you open the editor.

```yaml .kola/config.yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
services:
  - name: web
    start: pnpm dev
    ready: curl -fsS http://localhost:3000
    triggeredBy: [workstationStart]
tasks:
  - name: install
    command: pnpm install
    triggeredBy: [workstationStart]
  - name: seed
    command: pnpm db:seed
    triggeredBy: [manual]
```

A **service** keeps running, such as a dev server or a database. A **task** runs once and finishes, such as installing dependencies or seeding data.

| Field | Applies to | Value |
| - | - | - |
| `name` | Services and tasks | 1 to 64 letters, digits, dots, underscores or dashes. |
| `start` | Services | The command that runs the service. It must keep running. |
| `ready` | Services | Optional. A command that succeeds once the service is ready. KolaOS runs it every second for up to 2 minutes. |
| `command` | Tasks | The command that runs the task. |
| `triggeredBy` | Services and tasks | `workstationStart`, `manual`, or both. |

Commands run in a login shell as your user, in the repository's folder, so they find the tools your workspace installs.

`workstationStart` entries run each time the workstation starts. KolaOS runs the tasks first, in the order of the file, and starts the services after the last task succeeds. A task that fails stops the ones after it. `manual` entries run only when you select **Start** next to them.

Each service shows **Stopped**, **Starting**, **Ready** or **Failed**, and each task shows **Pending**, **Running**, **Done** or **Failed**. Select **Logs** to see a service's or a task's output. A service whose ready command does not succeed within 2 minutes is stopped and shows **Failed**.

When you change `.kola/config.yaml`, the running services keep the configuration they started with, and the repository shows **Changed**. Select **Apply** to use the new file. A file with an error shows **Invalid .kola/config.yaml** and names the line and the field, and the last valid configuration keeps running.

> [!WARNING]
>
> Services and tasks run inside your workstation, where you have full control. They make setup faster, and they do not restrict what anyone can do in the workstation.

## Dotfiles

Your dotfiles repository holds your own shell and editor settings. Set it in the dashboard under **Account**, then **Profile**, in **Dotfiles repository**. The value is an `https://` Git URL without a user name, password or query.

On a new workstation's first start, KolaOS clones the repository into `~/dotfiles` and runs the first of these files that exists: `install.sh`, `install`, `bootstrap.sh`, `bootstrap`, `setup.sh` or `setup`. It waits until your workspace's tools and Git access are set up, and it installs your dotfiles before `workstationStart` tasks run. The install can take up to 10 minutes.

The clone uses your workstation's own Git access. A public repository works, and so does a private repository that your workspace has added. KolaOS does not store a personal Git token for your dotfiles.

The **Dotfiles** entry in the Services section shows **Installed** or **Failed** with the reason, and your workstation's activity in the dashboard records the result. Select **Reinstall dotfiles** to run the install again. A change to your dotfiles repository applies to new workstations, or to this one when you reinstall.

## Outside access and failures

When a service, a task or the dotfiles install fails, and your workspace blocks internet access or allows only some domains, the failure names that policy. Ask an admin to allow the hosts your commands need. See [Workspace settings](https://docs.usekolaos.com/administration/workspace-settings.md).

KolaOS records only that a service, a task or the dotfiles install failed, with its name. The command output stays in your workstation, in the **Logs** of that service or task.

## Remove the extension

Before you uninstall the KolaOS extension, run **KolaOS: Remove ssh setup** from the Command Palette. It removes the `Include ~/.ssh/kola/config` line from `~/.ssh/config` and deletes `~/.ssh/kola`. Uninstalling an extension cannot remove files, so the SSH setup stays until you run this command or `kola ssh remove`.

**KolaOS: Sign out** signs out the extension and the CLI. **KolaOS: Export logs** saves the extension's log to a file you can send to support.

## Troubleshooting

| Problem | What to do |
| - | - |
| Connect says to install a Remote - SSH extension | Install your editor's Remote - SSH extension, then select **Connect** again. |
| The KolaOS view asks you to sign in | Select **Sign in**. Your sign-in ended or was revoked. |
| A link names a workspace where you have no workstation | Ask an admin to add you to the workspace, or open the link from your own workstation's page. |
| You have workstations in two organizations with the same workspace name | A link asks which workstation to open. The view lists both. |
| Sending a message says the session host isn't running | Restart the workstation from the dashboard. |
| A service stays **Starting** | Check its `ready` command in a terminal. It must exit with status 0 once the service is ready. |

See [Troubleshooting](https://docs.usekolaos.com/development/troubleshooting.md) for SSH and key errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.