Ghost Desk

Give your AI agent eyes, hands, and a full Linux desktop.

An MCP server that lets LLM agents see the screen, move the mouse, type on the keyboard, launch apps, and run shell commands — all inside a sandboxed virtual desktop.

If a human can do it on a desktop, your agent can too.

Your browser does not support the video tag.

GhostDesk demo — from a single prompt ("open the browser, go to Google News, and tell me the latest headlines in the Technology section"), the agent launches Firefox, navigates to Google News, switches to the Technology section, and reports the latest stories back.

______________________________________________________________________

目录

• 为什么是GhostDesk？
• 运作原理
• 快速启动
• 安全本地运行（TLS+身份验证）
• 工具
• 型号要求
• 从一名代理人到一名员工
• 配置
• 安全
• 故障排除
• 自定义图像
• 许可证

______________________________________________________________________

为什么是GhostDesk？

浏览器自动化工具（Playwright、Puppeteer、Selenium……）是为使用选择器驱动浏览器的人类测试工程师构建的。他们做了一件事，而且做得很好——在浏览器内部。

GhostDesk是从另一端构建的：用于 AI代理，驾驶 桌面运行的所有内容浏览器、原生应用、集成开发环境、终端、办公套件、传统软件、内部工具。如果它在屏幕上渲染像素，您的代理就可以看到并使用它——在一次对话中，在许多应用程序中，无需一行粘合代码。

你不写选择器。你写一个提示：

*“打开CRM，将上个月的潜在客户导出为CSV，打开LibreOffice Calc，构建数据透视表，截图图表，并通过电子邮件发送给团队。”*

代理打开浏览器，登录，下载文件，切换到LibreOffice，处理数据，捕获结果，撰写电子邮件，发送。一个提示，多个应用程序，完全自主——没有胶水代码，没有每个网站的抓取器，没有脆脆的选择链。

就是这样 *使用桌面的代理* 看起来像。

在您实际可以托管的模型上运行

桌面控件需要 快 --一个需要12秒来决定点击位置的代理是不可用的。GhostDesk经过调整，使运行在单个工作站GPU上的Qwen家族的视觉语言模型成为一流的目标，而不是事后的想法。没有API账单，没有离开网络的桌面截图。

前沿模型（Claude、GPT-4o、Gemini）也适用，并且仍然是最平滑的路径，但它们不是标准。看 型号要求 对于支持的堆栈和重要的一个坐标空间设置。

______________________________________________________________________

运作原理

GhostDesk在Docker中运行一个虚拟Linux桌面，并将其作为MCP服务器公开。你的代理会得到一个沙盒桌面，上面有任务栏、时钟和预装的应用程序——相当于人类在屏幕上看到的内容。

客服通过呼叫来感知屏幕 screen_shot()，它以本机分辨率捕获整个桌面，并将其作为WebP（或PNG）返回。可选 region= 当代理明确希望缩小其焦点时，参数可以裁剪为子矩形。

这适用于 任何应用程序 --web应用程序、原生应用程序、遗留软件、Canvas、WebGL。

______________________________________________________________________

快速启动

1.运行容器

一个命令，纯HTTP，无密码。踢你信任的笔记本电脑的轮胎很好-- 不适合做除此之外的任何事情准备好硬化了吗？跳转到 安全本地运行.

docker run -d --name ghostdesk-demo \
  --shm-size 2g \
  -p 3000:3000 \
  -p 6080:6080 \
  ghcr.io/yv17labs/ghostdesk:latest

这 latest 图像随附 火狐，the 脚 终端， 鼠标垫 （文本编辑器）， 胶凝器，且无密码 sudo 为了 agent 用户——足以演示开箱即用的浏览+笔记工作流程。需要不同的应用程序集吗？在上面建立自己的 base --看 自定义图像.

容器以开发状态启动：两个端口上都是纯HTTP，每个身份验证门都是故意解除的。您将在日志中看到警告，提醒您这一点——一旦您遵循下面的安全路径，这些警告就会消失。

2.连接你的AI

GhostDesk说话 主控程序 通过Streamable HTTP传输——任何兼容MCP的客户端都可以驱动它 http://localhost:3000/mcp:

克劳德桌面/克劳德代码

{
  "mcpServers": {
    "ghostdesk": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

任何其他MCP兼容客户端 --相同的URL，没有标头，没有身份验证。这就是整个演示姿势。

3.看着你的经纪人工作

打开 http://localhost:6080/ 在浏览器中实时查看虚拟桌面。没有密码提示——开发人员会跳过它。

首先提示您的代理确认接线正确：

*“截取桌面截图，列出已安装的应用程序，然后打开Firefox并转到wikipedia.org。”*

您应该在noVNC选项卡中看到Firefox启动、URL栏填写和页面加载——所有这些都在您的代理的控制之下。

4.当你完成时

docker stop ghostdesk-demo && docker rm ghostdesk-demo

演示运行不会创建命名卷，因此不会留下任何东西。

______________________________________________________________________

安全本地运行（TLS+身份验证）

上面的快速启动会放下每个门，这样你就可以在三十秒内踢出轮胎。当你想将其暴露给你自己的笔记本电脑之外的任何东西时——局域网上的另一台机器、不受信任的网络上的devcontainer端口转发、队友的浏览器——切换到安全状态：MCP+上的真实TLS+承载令牌认证+noVNC上的密码提示。

# Issue a locally-trusted cert (first time only — installs a local CA in your trust store)
mkcert -install
mkdir -p tls
mkcert -cert-file tls/server.crt -key-file tls/server.key localhost 127.0.0.1 ::1

# Generate the MCP and VNC secrets
export GHOSTDESK_AUTH_TOKEN=$(openssl rand -hex 32)
export GHOSTDESK_VNC_PASSWORD=$(openssl rand -hex 16)

选择与代理角色匹配的容器名称-- sales-agent, research-agent, accounting-agent…下面我们使用 my-agent 作为占位符；替换命令中的所有位置。

# Run the container — cert mounted, TLS + auth enabled everywhere
docker run -d --name ghostdesk-my-agent \
  --restart unless-stopped \
  --cap-add SYS_ADMIN \
  --shm-size 2g \
  -p 3000:3000 \
  -p 6080:6080 \
  -v ghostdesk-my-agent-home:/home/agent \
  -v "$PWD/tls/server.crt:/etc/ghostdesk/tls/server.crt:ro" \
  -v "$PWD/tls/server.key:/etc/ghostdesk/tls/server.key:ro" \
  -e GHOSTDESK_AUTH_TOKEN \
  -e GHOSTDESK_VNC_PASSWORD \
  -e TZ=America/New_York \
  -e LANG=en_US.UTF-8 \
  ghcr.io/yv17labs/ghostdesk:latest

echo "MCP token:    $GHOSTDESK_AUTH_TOKEN"
echo "VNC password: $GHOSTDESK_VNC_PASSWORD"

容器启动后，更新MCP客户端配置——与演示形状相同，现在结束 https:// 使用不记名代币：

克劳德桌面/克劳德代码

{
  "mcpServers": {
    "ghostdesk": {
      "type": "http",
      "url": "https://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer 
"
      }
    }
  }
}

任何其他MCP兼容客户端 --相同的URL，加上 Authorization: Bearer 无论客户接受何种形式的标题。

然后打开 https://localhost:6080/ 在您的浏览器中—— mkcert CA安装者 mkcert -install 已在您的信任存储中，因此浏览器接受证书而不发出警告。noVNC将提示 $GHOSTDESK_VNC_PASSWORD.

去生产？ 交换 mkcert 叶子用于真实证书，从您的秘密管理器获取两个秘密，并使用身份感知代理访问前端端口6080-- 安全.md 有完整的合同。

--cap-add SYS_ADMIN --Electron应用程序（VS Code、Slack等）和其他需要Linux用户命名空间来运行沙箱的应用程序都需要。如果你不需要它们，可以安全地移除。

命名卷在重新启动时保留代理的主目录——浏览器密码、书签、Cookie、下载和桌面首选项都会被保留。在第一次运行时，Docker会自动从映像中为卷添加默认配置的种子。

______________________________________________________________________

工具

13种工具触手可及，按关注点分组(verb_noun 命名）：

屏幕

老鼠

键盘

剪贴板

应用程序

______________________________________________________________________

型号要求

您的推理堆栈必须涵盖四种功能——这四种功能都是必需的：

1. 文字+视觉 --代理通过屏幕截图感知桌面，并需要一个可以解释它们的模型。
2. 工具使用 --GhostDesk将14个工具作为函数调用公开；模型必须能够调用它们。
3. MCP客户端 --主机需要说Streamable HTTP MCP才能到达GhostDesk服务器。
4. WebP图像支持 --GhostDesk默认情况下以WebP格式返回屏幕截图，以保持有效载荷小和推理快。只能解码PNG或JPEG的堆栈将无法开箱即用。

坐标空间-- GhostDesk-Model-Space 头球

默认情况下，不需要标头：Claude和其他主要前沿LLM可以开箱即用。 Qwen3.x 需要客户端发送 GhostDesk-Model-Space: 1000 在每个MCP请求上。

MCP客户端配置示例：

{
  "mcpServers": {
    "ghostdesk": {
      "url": "https://localhost:3000/mcp",
      "headers": {
        "GhostDesk-Model-Space": "1000"
      }
    }
  }
}

在本地运行

对于自托管推理，我们使用并推荐我们的llama.cpp分支，它在上游之上添加了WebP解码和turbo量化： YV17Labs/火焰.cpp，分支 integration/webp-turbo.当WebP到达上游时，我们将存档分叉并直接指向那里。

macOS用户：使用llama.cpp，而不是mlx-vlm（截至2026-04-01）。 mlx-vlm堆栈目前为在llama.cpp下正常工作的相同模型产生不准确的坐标输出。这是由苹果依赖关系中的上游错误引起的，而不是模型本身。在修复成功之前，llama.cpp是每个平台上的推荐后端，包括苹果Silicon Mac。

运行你喜欢的任何本地模型。我使用过的Qwen视觉家族的四款产品，它们在桌面控制方面表现良好：

• Qwen3.6-27B --致密27B；截至今天，这四种方法中最强大的一种可以处理复杂的多步骤任务，但代价是推理速度较慢。
• Qwen3.6-35B-A3B --每个令牌只有3B个活动参数。

______________________________________________________________________

从一名代理人到一名员工

每个GhostDesk实例都是一个容器。启动一个、十个或一百个——每个代理都有自己的独立桌面、自己的应用程序和自己的角色。把它想象成雇佣一个数字员工团队，每个人都有自己的工作站。

水平扩展

# docker-compose.yml — 3 specialized agents, one command
#
# Prerequisites: the TLS cert + key at ./tls and the two secrets
# (GHOSTDESK_AUTH_TOKEN, GHOSTDESK_VNC_PASSWORD) in your environment or a
# .env file. Generate both exactly as shown in the Secure local run
# section above. See SECURITY.md for the production secret-handling
# contract.

x-ghostdesk-defaults: &ghostdesk-defaults
  image: ghcr.io/yv17labs/ghostdesk:latest
  restart: unless-stopped
  cap_add: [SYS_ADMIN]
  shm_size: 2g
  environment:
    - GHOSTDESK_AUTH_TOKEN
    - GHOSTDESK_VNC_PASSWORD
    - TZ=America/New_York
    - LANG=en_US.UTF-8

services:
  sales-agent:
    <<: *ghostdesk-defaults
    container_name: ghostdesk-sales-agent
    ports: ["3001:3000", "6081:6080"]
    volumes:
      - ghostdesk-sales-agent-home:/home/agent
      - ./tls/server.crt:/etc/ghostdesk/tls/server.crt:ro
      - ./tls/server.key:/etc/ghostdesk/tls/server.key:ro

  research-agent:
    <<: *ghostdesk-defaults
    container_name: ghostdesk-research-agent
    ports: ["3002:3000", "6082:6080"]
    volumes:
      - ghostdesk-research-agent-home:/home/agent
      - ./tls/server.crt:/etc/ghostdesk/tls/server.crt:ro
      - ./tls/server.key:/etc/ghostdesk/tls/server.key:ro

  accounting-agent:
    <<: *ghostdesk-defaults
    container_name: ghostdesk-accounting-agent
    ports: ["3003:3000", "6083:6080"]
    volumes:
      - ghostdesk-accounting-agent-home:/home/agent
      - ./tls/server.crt:/etc/ghostdesk/tls/server.crt:ro
      - ./tls/server.key:/etc/ghostdesk/tls/server.key:ro

volumes:
  ghostdesk-sales-agent-home:
  ghostdesk-research-agent-home:
  ghostdesk-accounting-agent-home:

docker compose up -d   # Your workforce is ready

每个代理在自己的桌面上并行、独立运行。将每个应用程序连接到不同的LLM，为每个应用程序提供不同的系统提示，安装不同的应用程序——完全专业化。

设计安全

每个代理都在自己的容器中沙盒。无法访问主机。无法访问其他代理。网络、文件系统和进程隔离不受Docker的限制。

这使得GhostDesk非常适合企业：

让每个代理商都专业化

给每个代理人一个角色，就像给新员工一样：

• 销售代理 --监控CRM，丰富潜在客户，更新渠道
• 研究代理 --浏览网页、编制竞争情报、撰写报告
• 会计代理人 --在传统ERP软件中处理发票，核对电子表格
• QA代理 --点击您的应用程序，将错误报告与屏幕截图一起归档
• 支持代理 --处理工单，在多个内部工具中查找客户信息

每个代理都有自己的系统提示，定义其任务、安装的应用程序和网络权限。像员工一样管理人工智能代理——每个代理都有自己的桌面、自己的工具和自己的权限级别。

实时监督

每个代理都公开一个VNC/noVNC端点。打开浏览器选项卡并观察您的代理工作，或者打开十个选项卡并监控您的整个团队。随时干预：接管鼠标、纠正课程或与编排LLM聊天。

______________________________________________________________________

配置

GhostDesk读取的每个变量都在下面的命名空间中 GHOSTDESK_*标准POSIX变量(TZ, LANG)保持原样，以便现有的Unix生态系统继续工作。

机密（必填——没有机密，容器无法启动）

两者都是简单的环境变量。从你的秘密商店给他们打电话(secretKeyRef 在Kubernetes上，Docker secrets/Vault/AWS SM在compose上）——请参阅 安全.md 对于完整的合同。

运行时间旋钮

固定值（不可配置）

______________________________________________________________________

安全

GhostDesk拥有两样东西： 传输加密 和 认证其他一切（速率限制、SSO、WAF、会话记录、暴力保护、noVNC上的每个用户身份）都是反向代理问题——容器被设计为在一个代理后面运行，而不是直接在互联网上运行。

完整的威胁模型 *Auth≡TLS* 姿势开关，wayvnc RFB-type-2-side-wss:// 基本原理、秘密处理合同和详尽的范围内/范围外表都存在 安全.md --唯一的真理来源。在部署到任何你不完全信任的东西之前，先从那里开始。

______________________________________________________________________

故障排除

我经纪人的点击量大大偏离了目标

几乎总是坐标空间不匹配。前沿模型（Claude、GPT-4o、Gemini）不需要标头（默认传递）；Qwen视觉家族需要客户发送 GhostDesk-Model-Space: 1000 在每个MCP请求上。充分理由 型号要求 → *坐标空间*.

容器以secrets错误拒绝启动

触针姿势（已安装证书） 需要 两者 GHOSTDESK_AUTH_TOKEN 和 GHOSTDESK_VNC_PASSWORD 要设置--GhostDesk故意拒绝在没有它们的情况下启动，以防止未经身份验证的prod容器。如所示生成它们 安全本地运行 并将其传递给 -e演示姿势（无证书）没有这样的要求。

noVNC显示黑屏或桌面渲染出现图形故障

您可能缺少共享内存。容器内的浏览器和其他GPU加速应用程序需要合理的 /dev/shm — --shm-size 2g 是每个示例中的基线，不应修剪。如果你已经有了 --shm-size 2g，检查容器日志中是否存在wayvnc或合成器错误。

Firefox/Electron应用程序无法启动或立即崩溃

基于Electron的应用程序（VS Code、Slack、Discord……）的沙盒需要Linux用户命名空间。添加 --cap-add SYS_ADMIN 给你的 docker run （已存在于安全本地运行示例中）。Firefox本身可以在没有它的情况下工作。

______________________________________________________________________

自定义图像

这 base 标签提供的GhostDesk没有任何预安装的GUI应用程序，只有虚拟桌面、VNC和MCP服务器。使用它仅使用您需要的工具构建自己的图像：

FROM ghcr.io/yv17labs/ghostdesk:base

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        chromium-browser \
        libreoffice-calc \
    && rm -rf /var/lib/apt/lists/*

docker build -t my-agent .

查看项目的 举一个完整的例子。

______________________________________________________________________

许可证

功能源许可证，版本1.1，ALv2未来许可证 （FSL-1.1-ALv2） --看 许可证 对于权威术语。

这在实践中意味着什么 *（非正式摘要——以许可证文件为准；这不是法律建议）*:

• 允许目的 涵盖对绝大多数用户重要的用例：公司内部的内部使用和访问、非商业教育和研究，以及您根据许可证向使用GhostDesk的被许可人提供的专业服务。自托管GhostDesk来运行自己的代理，甚至是商业、创收的工作流程 *你的* 产品——是允许内部使用的。
• 禁止竞争使用。 您不得在替代GhostDesk的商业产品或服务中向他人提供GhostDesk，也不得使用GhostDesk替代项目提供的任何产品或服务，或提供相同或基本相似的功能。简而言之：您不能将GhostDesk重新命名，将其作为付费服务托管，或从中为代理产品构建竞争对手的桌面自动化。
• 两年后的Apache 2.0。 GhostDesk的每个发布版本都会在发布两周年之际根据Apache License 2.0自动且不可撤销地提供。竞争使用限制仅适用于前两年。

商业许可。 如果您的预期用途属于竞争用途——您想转售GhostDesk，将其作为托管服务提供，或构建竞争产品——请在部署前联系维护人员讨论商业许可证。打开GitHub问题或直接联系；我们很乐意交谈。