# capsulate [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/capsulatedev/capsulate  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1355  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/capsulate

## Description
Real Linux and Windows desktop VMs for AI agents: exec, files, computer-use and snapshots via MCP.

## Tools
Capabilities this server exposes over MCP:

- **capsulate_launch** — Launch a new isolated cloud sandbox (capsule) and (by default) wait until it is ready. Returns the capsule id and connection info. Use the returned sessionId for exec/files/etc. With skill, the capsule is the skill's environment (its saved template with the software set up) and the skill's setup procedure has run, so you can use its procedures right away.
- **capsulate_list** — List the team's active capsules.
- **capsulate_get** — Fetch a capsule's full details by id.
- **capsulate_destroy** — Terminate a capsule and release its resources.
- **capsulate_exec** — Execute a command inside a capsule and return stdout, stderr, and the exit code. Provide the command as an argv array, e.g. ['ls','-la','/workspace']. Commands first: files, installs, settings, scripts and data are one call here, a fraction of a second, where the screen takes many steps. On a Linux desktop capsule it runs as the desktop user 'capsulate' (home folder, DISPLAY :1, so apps open on the shared screen); prefix 'sudo' for root. On Windows pass ['powershell.exe', '-Command', '<script>']: it runs in the desktop session's PowerShell, about 0.3 s. It works while a person holds the screen.
- **capsulate_run_code** — Run a snippet of code inside a capsule: python, node or bash on Linux, powershell on Windows (about 0.3 s). Returns stdout/stderr/exit. Faster than doing the same on the screen.
- **capsulate_write_file** — Write a UTF-8 text file inside a capsule (the folder is created). One call, far faster than typing it into an editor on the screen; open it afterwards with capsulate_open if the person should see it.
- **capsulate_read_file** — Read a UTF-8 text file from inside a capsule. One call, no screen needed.
- **capsulate_set_env** — Set environment variables inside a running capsule.
- **capsulate_screenshot** — Capture a screenshot of a desktop capsule. Returns the image so you can see the screen. For a smaller, faster image ask for format 'jpeg', a scale such as 0.5, or only a region (x, y, w, h) of the screen; the text after the image says how its points map back to screen pixels, which click and the other tools take.
- **capsulate_click** — Click at pixel (x, y) in a desktop capsule. Pass screenshot:true to see the screen after the click.
- **capsulate_type** — Type text into the focused field of a desktop capsule.
- **capsulate_key** — Press keys in a desktop capsule, in order. Each entry is one key or a '+'-joined chord (xdotool names): ['ctrl+c'] copies, ['ctrl+l', 'Return'] focuses then submits, ['alt+F4'] closes a window. A bare modifier followed by a key is joined into a chord, so ['ctrl','v'] also pastes.
- **capsulate_snapshot** — Capture a snapshot of a capsule's current state (restorable later).
- **capsulate_catalog** — List the operating systems / base templates and marketplace bundles you can launch.
- **capsulate_move** — Move the mouse pointer of a desktop capsule to (x, y) in screen pixels.
- **capsulate_scroll** — Scroll at (x, y) in a desktop capsule. dy > 0 scrolls down, dy < 0 up; dx scrolls sideways. Units are wheel clicks.
- **capsulate_drag** — Press at (x1, y1), drag to (x2, y2) and release, in a desktop capsule. Or draw along a path: path is a list of [x, y] points (at most 1000), pressed at the first and released at the last, for curves, circles, signatures and any shape a hand draws. smooth draws a curve through the points instead of straight lines; closed returns to the first point (eight points on a circle with smooth and closed make a round circle); stepMs is the pause between points (8 ms by default; apps such as Paint need about that to see every point). The button is honoured (right paints with Paint's second color).
- **capsulate_ui_tree** — Return the accessibility tree of a desktop capsule (AT-SPI on Linux, UI Automation on Windows): roles, names, values, states and screen rectangles with centers (cx, cy) you can click. Far cheaper and more exact than reading a screenshot.
- **capsulate_find_element** — Find accessible elements by role / name / text in a desktop capsule. Each match has a center (cx, cy) to click.
- **capsulate_wait_element** — Wait until an accessible element matching the selector appears (for example after a page load).
- **capsulate_click_element** — Find an accessible element (waiting for it if needed) and click its center. The reliable way to press a named button or link.
- **capsulate_clipboard** — Without `text`, return the desktop capsule's clipboard. With `text`, put that text on the clipboard (then paste with ctrl+v). Pasting long text is faster and safer than typing it.
- **capsulate_windows** — Without a target, list the open windows of a desktop capsule. With `id` or `title`, bring that window to the front. To minimize, maximize, move, resize or close one, use capsulate_window.
- **capsulate_ocr** — OCR the desktop capsule's screen (or a region) and return the words with their boxes. Use when the UI tree has no labels (canvas apps, images).
- **capsulate_element** — Act on the accessible element a selector finds, without coordinates: set_value (replace a field's text, or a slider's value, with value), clear, toggle (a check box), expand or collapse (a menu, combo box or tree item), invoke (press a button, follow a link), select (a list item, tab or radio button; with value, the option of that name inside a combo box or list), focus, scroll_into_view. Prefer it to clicking and typing at guessed coordinates: it acts on exactly the element you name. Roles match across systems ('button', 'push button' and 'Button' are the same); a multi-line editor is 'document' on Windows (Notepad) and 'text' on Linux. Returns the element afterwards (its value and states such as checked, expanded, selected).
- **capsulate_window** — Minimize, maximize, restore, close, move, resize or focus a window of a desktop capsule, by id (from capsulate_windows) or a part of its title. move takes x, y (the new top-left corner); resize takes w, h (each at least 50). close asks the app to close, as the title bar's close button does, so it may first ask to save. Returns the window afterwards (none after close).
- **capsulate_open** — Open a URL (in the default browser), a file (in its default app) or an app by name on a desktop capsule, instead of hunting through menus. Without kind it is guessed: a path (/, ~, C:\) is a file, a scheme (https:, mailto:) or www. is a URL, anything else is an app name (a Linux menu entry such as 'Text Editor', a Windows Start menu entry such as 'Notepad', or a program on the path). Pass waitMs to wait for the new window and get it back. For web pages you will read or fill in, capsulate_browser_open is faster and more exact.
- **capsulate_wait_for** — Wait in the capsule until a condition holds, instead of sleeping or taking screenshot after screenshot: present (an element matching the selector is there), absent (none is any more: a dialog closed, a spinner went away), enabled (a matching element can be used), text (an element's name or value contains text; the selector is optional), window (a window whose title contains window is open), screen_stable (nothing on screen changed for stableMs: an app or page finished drawing). Returns met (true or false), waitedMs and what matched. The wait never holds up the capsule's other calls.
- **capsulate_screen_info** — The screen's size in pixels, the pointer's position and the active window of a desktop capsule. Use it instead of a screenshot when that is all you need.
- **capsulate_console_link** — Mint a signed, expiring URL that opens the desktop capsule's LIVE screen in any browser with no login. The person watching sees your pointer, clicks and keys as you act, plus your narration. mode 'control' (default) also lets them take the screen and hand it back; 'view' only watches. Open it in your browser pane or give it to the person.
- **capsulate_control** — Read or change who drives a desktop capsule's shared screen. state 'free' (nobody), 'agent' (you; every input renews a 45 s hold) or 'human' (a person; your input is refused until they hand it back). action 'status' (default) reads it, 'take' claims it for you, 'release' lets go when you finish so the person can use the screen, 'pace' sets how your input plays while a person watches: 'natural' (the pointer glides, typing is readable) or 'presentation' (slow enough to follow every step); 'fast' is the default. action 'visible' turns visible mode on or off (when the person asks to see every step). The status says visible: true while it is on: then do every step on the screen instead of through commands. action 'care' sets how carefully you check your work: 'quick', 'balanced' (the default) or 'careful'; the status says care when it is not balanced.
- **capsulate_handoff** — Hand the desktop capsule's screen to the person watching, with a note saying exactly what you need (sign in, solve a CAPTCHA, approve a payment, check something). The console shows 'The AI needs you' with your note. Then waits until they press Done, hand back, and returns their note. Use this instead of typing passwords or secrets yourself.
- **capsulate_wait_for_handback** — Wait until the person holding the desktop capsule's screen hands it back. Returns at once when nobody holds it. Returns their note.
- **capsulate_say** — Show one short line on the live console of a desktop capsule, e.g. 'Opening the settings to change the theme'. Narrate each step so the person watching knows what you are doing and why.
- **capsulate_browser_open** — Open the agent's own Chrome on a desktop capsule (the person watching sees it) and optionally load a url. For web pages prefer the capsulate_browser_* tools: they read the page as text with refs and act at page speed, faster and more exact than screenshots and clicks.
- **capsulate_browser_navigate** — Load a url in the browser's current tab and wait for it.
- **capsulate_browser_snapshot** — Read the current page as an outline of elements with refs, e.g. [e12] link "Pricing". Act on them by ref with the other browser tools. Refs stay valid until the element goes away; take a new snapshot after the page changes.
- **capsulate_browser_click** — Click an element of the page by ref (from capsulate_browser_snapshot), CSS selector or visible text.
- **capsulate_browser_fill** — Type a value into a field (replacing what is there); submit presses Enter after. Never use it for passwords or card numbers: hand the screen to the person instead (capsulate_handoff).
- **capsulate_browser_select** — Choose an option of a dropdown (<select>) by its value or label.
- **capsulate_browser_press** — Press keys in the page, in order: 'Enter', 'Tab', 'Escape', 'ArrowDown', 'PageDown' or a single character.
- **capsulate_browser_scroll** — Scroll the page by dy pixels (negative scrolls up), or bring an element into view by ref, selector or text.
- **capsulate_browser_wait** — Wait until an element or text appears (or, with state 'hidden', goes away). Without a target, waits for the page to finish loading.
- **capsulate_browser_text** — The page's visible text, or one element's (by ref, selector or text).
- **capsulate_browser_screenshot** — A screenshot of the browser page only (fast, small JPEG). For the whole desktop use capsulate_screenshot.
- **capsulate_browser_tabs** — List the browser's tabs, or open (new, with url), switch to (select) or close one (by tab id).
- **capsulate_browser_eval** — Evaluate a JavaScript expression in the page and return its JSON value (awaits promises). For reading data the outline does not show.
- **capsulate_menus** — List every menu of the focused window (or the window whose title contains window) with its items, read by opening each menu and closing it again. The quick way to learn what an application can do before you explore it; it takes a few seconds and the person watching sees the menus open.
- **capsulate_run_actions** — Run a list of steps on a desktop capsule in ONE call, back to back; the run stops at the first step that fails. Prefer it over one call per step whenever you know what comes next. Each step is {do: verb, ...that verb's fields}: screen: click {x, y, button?, count?}, type {text}, key {keys: ['ctrl+s']}, move {x, y}, scroll {x, y, dx, dy}, drag {x1, y1, x2, y2, button?} or {path: [[x, y], ...], smooth?, closed?, stepMs?, button?} (a stroke through the points), screenshot {format?, scale?, x?, y?, w?, h?}, ui_tree, find_element {selector}, wait_element {selector, timeoutMs}, clipboard, clipboard_set {text}, windows, window_focus {title}, ocr; without coordinates: element {action, selector, value?, window?} (action set_value, clear, toggle, expand, collapse, invoke, select, focus or scroll_into_view), window {action, title | id, x?, y?, w?, h?} (minimize, maximize, restore, close, move, resize), open {target, kind?, waitMs?}, wait_for {condition, selector?, window?, text?, timeoutMs?, stableMs?} (present, absent, enabled, text, window, screen_stable; a wait that ends unmet fails the step), screen (its size, the pointer, the active window); browser: browser_open {url}, browser_navigate {url}, browser_snapshot, browser_click {ref | text | selector}, browser_fill {ref, value, submit?}, browser_select {ref, option}, browser_press {keys}, browser_scroll {dy}, browser_wait {text | ref, state?}, browser_text, browser_eval {expression}, browser_screenshot; commands and files: exec {cmd: [...], cwd?, timeoutSec?}, write_file {path, content}, read_file {path, maxBytes?} (a text file comes back as text); they also run while a person holds the screen; helpers: click_element {selector: {role?, name?, text?}, waitMs?} (find, waiting up to 5 s, then click its centre), say {text} (narrate for the person watching), pause {ms}; skills: use {procedure, skill?, version?, args?} (run a procedure of a skill from capsulate_skills with its args; the call's skill is the default), check {element: selector, present?} | {window: title} | {exec: [...], exitCode?, contains?} | {file, contains?} | {pixel: {x, y, color, tolerance?}} (with timeoutMs? it waits; a check that does not hold fails), pixel {x, y} (a pixel's colour), menus {window?} (every menu's items). A step can say frame: '<name>' to give its coordinates in a frame of the call's frames (screen = origin + scale * (x, y), a stroke clamped inside clamp), and save: {variable: resultField} to keep a result for later steps as {{variable}}. Any step can carry expect (a wait that must succeed after it: {selector, timeoutMs} after a screen step, {text | ref | selector, timeoutMs} after a browser step) and optional: true (may fail without stopping the run). observe returns a look at the end, also when the run stopped early: 'screenshot', 'ui_tree' or 'browser_snapshot'. At most 200 steps and 90 s per call. Never put passwords or other secrets in steps; hand those to the person (capsulate_handoff).
- **capsulate_skills** — The team's skills. action 'list' (query?) lists them; 'get' (skill, version?, part?: 'all' | 'instructions' | 'spec') reads one, its instructions, procedures, traps and environment, so you do not have to discover the application again. 'save' keeps what you learned: skillMd (a whole SKILL.md) or name + description (what it does and when to use it) + instructions (Markdown), and spec (capsulate/skill.json: environment, frames, inputs, procedures as run_actions steps with {{param}} placeholders, checks, traps) and files. It creates the skill, or adds a proposed version when the team has one by that name; what a new version leaves out is kept. 'versions' (skill) lists versions; 'approve' (skill, version, force?) makes one current (a passing rehearsal, or force); 'reject' and 'rollback' (skill, version); 'archive' and 'unarchive' (skill). 'environment' (skill, sessionId, setup?) saves the capsule as the skill's environment once the software is installed and set up: a saved template, and a version that launches from it (capsulate_launch with skill), its setup procedure run after each launch. 'rehearse' (skill, version, sessionId?, keep?) proves a version before it is approved: a fresh capsule from its environment (or the capsule given), its fingerprint and checks; follow it with capsulate_skill_run get. 'weekly' (skill, on) rehearses the current version every week to notice when the software changes.
- **capsulate_skill_run** — Run a skill's procedure (or steps that call its procedures) in the background, with no time limit: the stored steps replay and you are asked only where the skill leaves a decision open. action 'start' (sessionId, skill, procedure? default main, inputs?, steps?, frames?, version?; or launch: true to start the skill's environment for the run, keep? to keep it) starts it and waits up to waitMs (default 20000) for it to end or to need you. 'get' (runId, waitMs?) reads it; 'continue' (runId with values answering its question, or action 'retry' or 'skip', or steps to run instead of a stuck step) goes on; 'cancel' (runId); 'list' (skill?, status?). A run that needs you says so: needs_input with a question, or needs_help with the step that failed. Steps you give for a stuck step are kept as a proposed fix to the skill.
- **capsulate_inbox** — The team's inbox: runs that ask a question or are stuck on a step, versions waiting for approval, versions whose rehearsal failed, and skills whose software changed. Each item says what to do next.
- **capsulate_lesson** — A lesson records how a job is done on a capsule so it can become a skill. While it records, every action taken on the capsule through these tools is logged in full, a person's clicks, keys and typing on the shared screen are recorded with the elements they hit (typing in a password field is masked), and keyframes are taken. action 'start' (sessionId, title, goal?, mode: 'ai' to teach yourself toward the goal, 'human' when a person teaches on the shared screen; skill? it improves); 'note' (lessonId, text, screenshot?) for what you learned or a trap; 'pause', 'resume', 'finish', 'discard' (lessonId); 'get' (lessonId) reads the digest after it finished: the steps in plain words, each with the step that does it again, the notes and what changed on the capsule, then save the skill with capsulate_skills action 'save' and lessonId; 'draft' (lessonId, skill?, description?) makes a draft version mechanically; 'on' (sessionId) is the lesson recording on a capsule; 'list'. Never type a password or a key during a lesson: hand that step to the person (capsulate_handoff).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "capsulate": {
    "command": "npx",
    "args": ["-y","@capsulate/mcp"],
    "env": {
      "CAPSULATE_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `CAPSULATE_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What capsulate does

The capsulate MCP server connects AI agents to real KVM virtual machines, called capsules. Available machine types include Linux headless systems, Linux desktops, and Windows Server desktops. Capsules are obtained from a warm pool and can become available in about two seconds, according to the project documentation.

An agent can work with the operating system through several interfaces. It can execute commands, work with files, capture screenshots, and inspect or operate controls through the operating system accessibility tree. Linux uses AT-SPI for this tree, while Windows uses UIAutomation. The server also exposes checkpointing and rollback for the complete machine, along with session replay.

The underlying control plane and node agent run on Capsulate infrastructure in Helsinki; they are not included in this repository. The repository contains the SDK, CLI, MCP package, AI tool packs, and a GitHub Action for running a step inside a capsule.

## How it works

An MCP-compatible client starts the `@capsulate/mcp` package, which communicates with Capsulate using credentials supplied by the developer. The client can then request capsule operations through MCP tools. The same service can also be accessed through the TypeScript SDK or the `cap` command-line tool, but those are separate interfaces to the platform.

Capsules represent complete virtual machines rather than individual processes. A workflow can launch a machine from a template, wait for it to become active, perform commands or desktop interactions, create a checkpoint, and later destroy the capsule. Checkpoints cover the whole machine and support rollback when a workflow needs to return to an earlier state.

## Setup and configuration

The capsulate MCP server is installed and run with:

```bash
npx -y @capsulate/mcp
```

Use an API key obtained from the Capsulate dashboard under Settings, API and Keys. Capsulate is currently in private beta, so access must be requested through the Capsulate website. The repository identifies `CAPSULATE_API_KEY` as the SDK configuration pattern; the MCP client configuration should provide the corresponding key to the server according to the client’s environment settings.

The repository also provides a global CLI installation with `npm i -g @capsulate/cli`. Its documented workflow logs in with an API key, launches a template and size, executes a command, captures a screenshot, and destroys the capsule.

## Tools and capabilities

The capsulate MCP server is suited to workflows requiring an actual operating system environment. Supported capabilities include:

- Launching Linux or Windows capsule types
- Running commands inside a capsule
- Reading and manipulating files
- Taking screenshots
- Inspecting and interacting with accessibility-tree controls
- Creating checkpoints of the complete machine
- Rolling a machine back to a checkpoint
- Replaying a session

The README specifically shows a desktop interaction that finds a control by name and clicks it, then creates a checkpoint before submission.

## Limitations and notes

The service is metered by the second, although the beta is free; published rates are maintained on the pricing page. The documented deployment currently has one compute node in Helsinki and supports approximately ten to fifteen active capsules at once. Windows access is limited to invited testers.

The engine is hosted remotely and is not part of the repository, so local installation does not provide a self-hosted VM control plane. Keep API keys out of source repositories and issue reports; the project asks users to report security vulnerabilities separately. The capsulate MCP server therefore fits hosted, access-controlled automation better than an offline or self-contained deployment.

_Full upstream README: https://allmcps.com/mcp/capsulate/readme_