VS Code, Cursor and Windsurf

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.

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.

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.

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.

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

.kola/config.yaml

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.

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. 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 for SSH and key errors.

Getting started

Administration

Development

VS Code, Cursor and Windsurf

Connect to a workstation

In the workstation

Discussions

Previews

Services and tasks

Dotfiles

Outside access and failures

Remove the extension

Troubleshooting

​Connect to a workstation

​In the workstation

​Discussions

​Previews

​Services and tasks

​Dotfiles

​Outside access and failures

​Remove the extension

​Troubleshooting

Connect to a workstation

In the workstation

Discussions

Previews

Services and tasks

Dotfiles

Outside access and failures

Remove the extension

Troubleshooting