Platter

platter

您的电脑，一应俱全。

MCP 服务通过 Stdio 和 StreamableHTTP 传输方式提供 Read、Write、Edit、Bash、Glob、Grep 和 JS 工具。使用 Bun 构建，可编译为独立可执行文件。

专为基于浏览器的（或任何兼容 MCP 的）Agent 设计，例如 Hadrian，用于控制电脑。

工具

工具	描述
read	分页读取文件内容（offset/limit）。检测图像文件（JPEG、PNG、GIF、WebP）并返回元数据。文本最多截断至 2000 行或 50KB。
write	创建或覆盖文件。自动创建父目录。
edit	使用精确或模糊匹配查找并替换（规范化智能引号、破折号和 Unicode 空白字符）。要求匹配结果唯一；也可使用 replace_all 替换所有匹配项（仅限精确匹配）。返回统一差异。
bash	执行 Shell 命令，可选设置超时。输出最多截断至末尾 2000 行或 50KB。
glob	快速匹配文件模式。返回最多 500 个符合 glob 模式（例如 **/*.ts）的路径。
grep	使用 ripgrep 搜索文件内容。支持正则表达式、文件筛选、上下文行和多种输出模式。需要安装 rg。
js	在持久化的 Node.js vm 上下文中执行 JavaScript/TypeScript。会话内的多次调用之间状态会保留。支持 await、console.log，以及通过 await load("package") 从 unpkg.com 加载包。自动返回最后一个表达式的结果。不是安全沙箱——请参阅下文的安全。

快速开始

使用发行版二进制文件

从 Releases 下载适用于您平台的最新二进制文件，或使用 curl 获取：

# Download (replace the filename for your platform)
# Available: platter-linux-x64, platter-linux-arm64, platter-darwin-x64, platter-darwin-arm64
curl -fsSL https://github.com/hadriangateway/platter/releases/latest/download/platter-linux-x64 -o platter
chmod +x platter

./platter          # stdio mode
./platter -t http  # HTTP mode on :3100

Docker

docker run --rm -i ghcr.io/hadriangateway/platter                                   # stdio mode
docker run --rm -p 3100:3100 ghcr.io/hadriangateway/platter -t http --host 0.0.0.0  # HTTP mode

有关挂载路径、网络、安装额外软件和构建自定义映像的信息，请参阅下文的 Docker。

从源代码构建

bun install
bun run dev      # run directly from TypeScript
bun run compile  # build standalone binary for current platform

用法

platter v1.x.x

Your computer, served on a platter.

Usage: platter [options]

Options:
  -t, --transport <stdio|http>   Transport mode (default: stdio)
      --tray                     Run the HTTP server with a Linux system tray
                                 (implies --transport=http, persists state
                                 across restarts in ~/.config/platter)
  -p, --port <number>            HTTP port (default: 3100)
      --host <address>           HTTP bind address (default: 127.0.0.1)
      --cwd <path>               Working directory for tools (default: current directory)
      --cors-origin <origin>     Allowed CORS origin (default: *)
      --auth <mode>              Auth mode: oauth, bearer, jwks, none (default: oauth)
      --auth-token <token>       Bearer token for HTTP auth (auto-generated if omitted)
      --tls-cert <path>          TLS certificate file (PEM) — enables HTTPS
      --tls-key <path>           TLS private key file (PEM)

External JWKS / OIDC (--auth jwks — verify tokens from an external IdP):
      --oauth-issuer <url>       Issuer URL; OIDC-discovers the JWKS endpoint
      --jwks-url <url>           Explicit JWKS endpoint (overrides discovery)
      --oauth-audience <aud>     Expected token audience (strongly recommended)
      --jwks-scope-grants        Map tools:<name> token scopes to tool access
                                 (fail closed: a token with no tools:<name>
                                 scopes is granted no tools)

Process management:
      --max-processes <number>   Max concurrent bash processes per session (default: 20)
      --max-sessions <number>    Max concurrent HTTP sessions (default: unlimited)

Restrictions:
      --tools <list>             Comma-separated tools to enable (default: all)
                                 Valid: read, write, edit, bash, glob, grep, js
      --allow-path <path>        Restrict read/write/edit/glob/grep to this path (repeatable)
                                 Does not restrict bash or js
      --allow-command <regex>    Allow bash commands matching this pattern (repeatable)
                                 Pattern must match the entire command string
                                 Applies to bash only; does not restrict js

Sandbox (applies to bash only; the js tool is never sandboxed):
      --sandbox                  Use just-bash sandbox instead of native bash
      --sandbox-fs <mode>        Filesystem backend: memory, overlay, readwrite (default: readwrite)
      --sandbox-allow-url <url>  Allow network access to URL prefix (repeatable)

  -h, --help                     Show this help message
  -v, --version                  Show version number

限制

您可以限制注册哪些工具、文件工具可访问哪些文件系统路径，以及 bash 工具可执行哪些命令。

工具选择

仅注册指定工具。未注册的工具对 MCP 客户端完全不可见：

platter --tools read,glob,grep    # read-only server
platter --tools read,write,edit   # no bash/search/js

路径限制

将文件访问工具（read、write、edit、glob、grep）的访问范围限制在一个或多个目录树内。路径会解析为绝对路径，并通过 realpath 解析符号链接，以防止越界访问：

platter --allow-path /home/user/project
platter --allow-path /home/user/project --allow-path /tmp

命令限制

仅允许整个命令字符串至少匹配一个正则表达式模式的 bash 命令：

platter --allow-command "git( .*)?"                             # git only
platter --allow-command "git( .*)?" --allow-command "npm( .*)?" # git or npm
platter --allow-command "ls( .*)?" --allow-command "cat .*"     # ls or cat

模式会添加锚点：--allow-command "git( .*)?" 会编译为 ^(?:git( .*)?)$，因此 git status 会匹配，但 rm -rf / && git status 不会匹配。

组合示例

# Locked-down: read-only tools, scoped to one directory
platter --tools read,glob,grep --allow-path /home/user/project

# Full tools, but bash restricted to git/npm, files restricted to project
platter --allow-path ./my-project --allow-command "git( .*)?" --allow-command "npm( .*)?"

启动时，活动限制会记录到 stderr。

身份验证

由 --auth <mode> 控制：

模式	描述
oauth（默认）	OAuth 2.1 授权码 + PKCE，并以静态 Bearer 令牌作为备用方式
bearer	仅使用静态 Bearer 令牌
jwks	资源服务器模式：通过 JWKS 验证由外部 OAuth/OIDC 颁发方（Auth0、Keycloak、Okta、Entra）签发的 JWT 访问令牌
none	无身份验证

OAuth 2.1（--auth oauth）

支持 RFC 9728（受保护资源元数据）的 MCP 客户端可以自动发现 platter 的 OAuth 端点并进行身份验证，无需手动复制令牌。

流程：

1. 客户端发现 /.well-known/oauth-authorization-server 和 /.well-known/oauth-protected-resource/mcp
2. 客户端通过 POST /register 注册（RFC 7591 动态客户端注册）
3. 客户端通过 /authorize 发起 Authorization Code + PKCE 流程
4. 系统会通过带外方式显示一个确认码（打印到 stderr，或在托盘模式下显示为桌面通知）
5. 用户查看授权页面，输入确认码，选择要授予权限的工具，然后批准或拒绝请求
6. 客户端在 /token 处使用授权码换取令牌
7. 后续请求使用 Authorization: Bearer <access_token>

确认码可证明批准请求的人能够访问 platter 进程——能够访问授权页面的远程攻击者无法在没有确认码的情况下批准请求。确认码只能使用一次，5 分钟后过期，最多可尝试 5 次。

访问令牌在 1 小时后过期，并且可以刷新。客户端注册信息会保存到 ~/.config/platter/clients.json。不支持 OAuth 的客户端也可以使用静态 Bearer 令牌作为备用方案。

Bearer 令牌（--auth bearer）

启动时会生成一个随机 Bearer 令牌并打印到 stderr（或在托盘模式下保存到系统密钥环）。每个请求都必须包含 Authorization: Bearer <token>。你也可以提供自己的令牌：

platter -t http --auth bearer --auth-token my-secret-token

无身份验证（--auth none）

完全禁用身份验证（例如，在由反向代理处理身份验证的情况下）：

platter -t http --auth none

外部 JWKS / OIDC（--auth jwks）

在 jwks 模式下，platter 充当纯粹的资源服务器：它不会签发自己的令牌，而是验证由外部 OAuth/OIDC 授权服务器（Auth0、Keycloak、Okta、Microsoft Entra）签发的 JWT 访问令牌——根据签发方的 JWKS 验证签名，并校验 iss、aud 和 exp 声明。这样，你就可以让 platter 运行在现有 IdP 后面，而无需使用反向代理。

# Auth0 (root issuer)
platter -t http --auth jwks \
  --oauth-issuer https://YOUR_TENANT.auth0.com/ \
  --oauth-audience https://platter.example.com/mcp

# Keycloak (realm issuer)
platter -t http --auth jwks \
  --oauth-issuer https://kc.example.com/realms/myrealm \
  --oauth-audience platter-api

# Skip discovery / point at a JWKS endpoint directly
platter -t http --auth jwks \
  --jwks-url https://idp.example.com/.well-known/jwks.json \
  --oauth-audience platter-api

受众验证（强烈建议）。 将 --oauth-audience 设置为 IdP 中配置的 API 标识符。如果省略此选项，platter 会接受签发方签发的任何有效令牌，包括签发给其他资源服务器的令牌（存在混淆代理风险）。禁用受众验证时，platter 会在启动时打印警告。

发现。 使用 --oauth-issuer 时，platter 会在启动时获取签发方的 /.well-known/openid-configuration（若失败，则尝试 /.well-known/oauth-authorization-server），以查找 jwks_uri，并向支持 RFC 9728 的 MCP 客户端重新公布授权服务器信息（位于 /.well-known/oauth-protected-resource/mcp）。传入 --jwks-url 可跳过发现，或用于 IdP 在启动时无法访问的情况。如果发现失败，但已设置 --jwks-url，令牌验证仍可正常工作——只是会跳过 RFC 9728 自动公布。

授权（令牌可以执行哪些操作）。 默认情况下，已验证的令牌会获得管理员级别访问权限，仅受操作员的 CLI 限制（--tools、--allow-path、--allow-command、--sandbox）约束——IdP 控制谁可以访问，CLI 标志控制他们可以执行什么操作。传入 --jwks-scope-grants 可进一步启用对令牌中 tools:<name> 作用域的支持（例如 tools:read tools:bash），从而进一步缩小获准使用的工具范围（只能缩小，不能超出操作员设定的上限）。同时支持 scope 声明和 Entra 风格的 scp 声明。在此模式下，访问采用默认拒绝策略：不包含 tools:* 作用域的令牌不会获准使用任何工具，因此令牌必须明确请求所需的工具。

不支持静态回退。 与 oauth 模式不同，jwks 模式只接受外部签发的 JWT——不接受 --auth-token。

注意： MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL 与此模式无关。它仅涉及 platter 在 --auth oauth 模式下通过 http 提供自己的签发方服务。外部 https 签发方无需此标志。如果将 --auth jwks 指向纯 http 签发方（例如本机的 Keycloak），platter 会发出警告并跳过 RFC 9728 元数据公布，但令牌验证仍可正常工作。

TLS（HTTPS）

若要通过 HTTPS 提供服务，请提供 PEM 编码的证书和私钥：

platter -t http --tls-cert cert.pem --tls-key key.pem

--tls-cert 和 --tls-key 必须同时提供。提供这两个参数后，服务器将通过 HTTPS 而非纯 HTTP 监听。

若要为开发或可信的内部使用生成自签名证书：

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=myserver'
platter -t http --tls-cert cert.pem --tls-key key.pem

Stdio 模式

用于 Claude Desktop、Cursor 及其他会启动子进程的 MCP 客户端：

{
  "mcpServers": {
    "platter": {
      "command": "/path/to/platter"
    }
  }
}

HTTP 模式（StreamableHTTP）

用于基于浏览器的 Agent 和远程连接：

platter -t http -p 3100

服务器在 /mcp 公开一个端点，用于处理：

• POST /mcp - JSON-RPC 消息（初始化、工具调用）
• GET /mcp - SSE 通知流
• DELETE /mcp - 终止会话

默认情况下，对所有来源启用 CORS（反映请求中的 Origin）。若要限制为特定来源：

platter -t http --cors-origin https://myapp.example.com

根据 StreamableHTTP 规范，服务器通过 Mcp-Session-Id 标头管理会话。

服务器会验证 Host 标头，以防止 DNS 重绑定攻击。设置 --cors-origin 时，服务器端也会验证 Origin 标头（而不只是通过 CORS 响应标头进行验证）。

托盘模式（Linux）

将 platter 作为持久运行的后台服务启动，并显示系统托盘图标：

platter --tray

这会启用 --transport=http，并添加以下功能：

• 系统托盘图标：通过 DBus（StatusNotifierItem 协议）提供，兼容 KDE、GNOME（需安装 AppIndicator 扩展）及其他桌面环境。
• 持久化配置：~/.config/platter/config.json 中的认证令牌、已启用的工具、端口、主机和工作目录会在重启后保留。
• 动态切换工具：可在运行时通过托盘菜单启用或禁用单个工具。更改会持久保存并立即生效。
• 认证令牌管理：可将服务 URL 或认证令牌复制到剪贴板，也可重新生成令牌。系统密钥环可用时，令牌会存储在其中；否则存储在配置文件中。
• 服务控制：可通过托盘菜单启动、停止和重启 HTTP 服务。

Linux 安装程序

linux/install.sh 脚本会以用户级别安装（无需 sudo）：

./linux/install.sh                  # install
./linux/install.sh --uninstall      # remove

此操作会安装：

• ~/.local/bin/platter — 二进制文件
• ~/.local/share/applications/platter.desktop — 桌面启动器条目
• ~/.local/share/icons/hicolor/scalable/apps/platter.svg — 应用图标
• ~/.config/systemd/user/platter.service — 用于自动启动的 systemd 用户单元

安全性

网络（HTTP 模式）

• TLS（HTTPS） — 通过 --tls-cert 和 --tls-key 启用可选的传输加密。使用 Node.js https 模块，以及 PEM 编码的证书和密钥文件。
• OAuth 2.1 + PKCE（--auth oauth，默认）— MCP 客户端通过带 PKCE 的授权码流程进行身份验证（RFC 7636）。支持动态客户端注册（RFC 7591）和令牌撤销（RFC 7009）。
• 外部 JWKS / OIDC（--auth jwks）— 资源服务模式：platter 根据发行方的 JWKS 验证来自外部发行方（Auth0、Keycloak、Okta、Entra）的 JWT 访问令牌，并校验签名、iss、aud 和 exp。仅支持非对称算法（拒绝 alg: none 和 HMAC）。配置说明请参阅身份验证下的外部 JWKS / OIDC部分。
• 带外同意确认 — OAuth 同意页面要求输入确认码，该确认码仅向 platter 操作者显示（通过 stderr 或桌面通知）。这可防止 CSRF 和跨源攻击自动批准授权请求。同意页面还受到 X-Frame-Options: DENY、Sec-Fetch-Site 校验和 Origin 请求头检查的保护。
• Bearer 令牌身份验证 — 静态 Bearer 令牌（RFC 6750）可作为 oauth 模式的备用方式，也可作为 bearer 模式的唯一方式。除非提供 --auth-token 或设置 --auth none，否则启动时会生成一个随机的 256 位令牌。
• Host 请求头校验 — 防止 DNS 重绑定攻击。绑定到 localhost 时仅接受 127.0.0.1、localhost 和 ::1；远程绑定时仅接受指定的 --host。
• Origin 校验 — 设置特定来源的 --cors-origin 后，带有不匹配 Origin 请求头的请求会被主动拒绝并返回 403（不仅仅是通过 CORS 响应头进行过滤）。

限制（尽力而为）

--tools、--allow-path 和 --allow-command 是纵深防御控制措施。它们会显著提高攻击门槛，但并非沙箱。在威胁模型中依赖这些措施之前，应先了解以下限制。

优势

• 工具选择在注册时强制执行。已禁用的工具不会通过 MCP 协议公开。客户端无法调用或发现它们。
• 路径验证会在比较前，使用 realpath() 解析目标路径和每个允许路径中的符号链接，从而防止通过 ../ 或符号链接目录进行路径遍历。对于尚不存在的写入目标，则解析最近的现有上级目录。
• 命令验证会将正则表达式锚定到完整命令字符串，防止通过追加 && malicious-command 之类的方式轻易绕过。

已知限制和绕过方式

• **Bash 本身不受限制。**启用 bash 工具时，足够巧妙的命令可以完全绕过 --allow-path（例如 cat /etc/passwd）。如果设置了 --allow-path，却没有同时设置 --allow-command，也没有从 --tools 中移除 bash，启动时会打印警告。如需严格控制文件访问，请禁用 bash（--tools read,write,edit,glob,grep），或将 --allow-path 与严格的 --allow-command 允许列表搭配使用。
• **js 工具不是安全沙箱。**它在 Node.js vm 上下文中运行代码，而 Node 自身的文档明确指出，这不是一种安全机制——不可信代码可以通过已知技术逃逸该上下文。即使没有逃逸，运行时也会提供 fetch（可进行任意网络访问，包括访问私有地址和环回地址）、Buffer，以及一个 load() 辅助函数，可从 unpkg.com 或任何其他 URL 下载并执行任意代码。--allow-path、--allow-command、--sandbox 和 --sandbox-allow-url 均不适用于 js 工具——这些标志只影响文件和 bash 工具。启用 js 工具时，应将该服务视为与不受限制的 bash 具有大致相同的破坏范围。如需禁用它：--tools read,write,edit,bash,glob,grep。如需严格隔离，请在容器或虚拟机中运行 platter。
• **命令正则表达式针对原始字符串运行。**它不会解析 shell 语法。像 --allow-command "git( .*)?" 这样的模式会阻止 rm && git status（因为整个字符串不匹配），但有心的攻击者可能构造出符合正则表达式、却执行了非预期代码的命令，例如允许的模式过于宽泛时。请尽可能严格地编写模式。
• **符号链接 TOCTOU。**路径验证会在检查时解析符号链接。如果符号链接目标在检查与实际文件操作之间发生变化，就可能绕过验证。这是用户空间路径检查的根本局限。
• Glob/grep 搜索范围。--allow-path 会验证 glob 和 grep 的搜索目录，但该目录树中的结果可能包含指向目录外部的符号链接。这些符号链接目标的内容可能会出现在 grep 输出中，或由 glob 列出。
• **没有进程级沙箱。**所有限制均通过 platter 进程中的应用代码强制执行，不使用操作系统级机制（seccomp、namespaces、pledge 等）。platter、Bun 或某个依赖项中的漏洞都可能绕过所有限制。

如需更强的隔离，请使用 just-bash 沙箱、Docker 容器，或两者兼用。

沙箱模式（just-bash）

选择使用 just-bash，这是一个使用 TypeScript 重新实现的 bash，带有虚拟文件系统，可用于沙箱化命令执行。不会生成原生进程；shell 完全在 Bun 运行时中运行。

platter --sandbox                                               # readwrite fs, no network
platter --sandbox --sandbox-fs memory                           # pure in-memory fs
platter --sandbox --sandbox-fs overlay                          # reads from disk, writes ephemeral
platter --sandbox --sandbox-allow-url "https://api.example.com" # allow network to prefix

文件系统模式

模式	读取	写入	用例
memory	仅虚拟文件系统	仅虚拟文件系统	最大程度隔离，完全不访问磁盘
readwrite（默认）	真实磁盘	真实磁盘	在可访问真实文件的同时进行沙箱化执行
overlay	真实磁盘	内存（临时）	探索文件而无需担心文件被修改

网络访问

默认情况下，禁用网络访问。使用 --sandbox-allow-url（可重复指定）允许访问特定的 URL 前缀。始终禁止访问私有/回环 IP。

platter --sandbox --sandbox-allow-url "https://api.github.com" --sandbox-allow-url "https://registry.npmjs.org"

与其他限制的交互

• --allow-path：在 readwrite 和 overlay 模式下，每个允许的路径都会挂载到沙箱中。在 memory 模式下，忽略 --allow-path。
• --allow-command：命令正则验证仍会在沙箱执行命令前应用。
• --sandbox 会抑制 bash 与 --allow-path 的警告，因为沙箱会强制执行文件系统边界。

限制

• 并非完整的 bash。 just-bash 是 TypeScript 的重新实现；某些边缘情况的行为可能与 GNU bash 不同。
• 不支持原生二进制文件。 git、node、docker、rg、python 等命令不可用。只有 bash 内建命令和 just-bash 的内置命令集可以使用。
• Beta 软件。 just-bash 正在积极开发中。请先测试工作流，再在生产环境中依赖它。

容器隔离（Docker）

在 Docker 容器中运行 platter，可通过 Linux 命名空间和 cgroups 提供操作系统级隔离。容器边界会限制 bash 工具可访问的内容。即使是不受限制的命令，也只能访问容器暴露的文件系统和网络。

# Minimal: no host filesystem, no network
docker run --rm -i --network none ghcr.io/hadriangateway/platter

# Read-only project access, no bash
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work:ro \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --tools read,glob,grep

# Full tools, scoped to a mounted directory
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --allow-path /work

容器的强制限制

• 文件系统边界。 只有明确挂载的路径（-v）可见。即使启用了 bash，命令也无法读取或写入未挂载的主机路径。
• 网络边界。 --network none 会完全禁用网络。未设置此选项时，容器可以访问外部网络，但无法访问仅主机服务，除非使用 --network host。
• 进程隔离。 容器内的进程无法查看或向主机进程发送信号。
• 资源限制。 Docker 的 --memory、--cpus 和 --pids-limit 标志可限制资源使用，以防止拒绝服务。

容器与虚拟机

容器与主机共享内核；隔离由内核功能（命名空间、cgroups、seccomp）强制执行。内核漏洞或配置错误的容器（例如 --privileged）可能会突破边界。虚拟机在虚拟化硬件上运行独立内核，因此来宾系统遭到入侵不会直接暴露主机。如果你的威胁模型包含可能尝试内核漏洞利用的不可信代码，请在虚拟机中运行 platter（或使用基于虚拟机的容器运行时，例如 Kata Containers 或 Firecracker）。对于大多数用例，例如限制 AI Agent 造成的影响范围，正确配置的容器（非 root 用户、移除能力、--network none）就足够了。

结合使用沙箱和容器

just-bash 沙箱和 Docker 容器针对不同的防护层。结合使用可实现纵深防御：

层	防护对象
just-bash 沙箱	任意原生进程执行：没有 git、curl、rm 等命令。命令在 TypeScript 解释器中运行，而非操作系统 shell。
Docker 容器	主机文件系统/网络访问：即使沙箱存在漏洞或被绕过，容器也会将影响范围限制在已挂载路径和允许的网络内。

# Maximum isolation: sandbox inside a container, overlay fs, no network
docker run --rm -i --network none \
  -v /home/user/project:/work:ro \
  ghcr.io/hadriangateway/platter --sandbox --sandbox-fs overlay

# Sandbox with controlled network access inside a container
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 \
    --sandbox --sandbox-allow-url "https://api.github.com"

为获得最高安全性，还应以非 root 用户运行容器（--user）、移除所有能力（--cap-drop ALL），并将文件系统设为只读（--read-only），同时提供一个 tmpdir 用于必要的写入操作：

docker run --rm -p 3100:3100 \
  --user 1000:1000 \
  --cap-drop ALL \
  --read-only --tmpfs /tmp \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --sandbox

有关挂载路径、网络设置和构建自定义镜像的完整使用说明，请参阅 Docker。

Docker

Docker 镜像基于 Debian Bookworm（slim），并包含 ripgrep。每次发布带标签的版本时，都会将多架构镜像（linux/amd64、linux/arm64）发布到 GitHub Container Registry。

docker pull ghcr.io/hadriangateway/platter        # latest release
docker pull ghcr.io/hadriangateway/platter:1.0.0  # specific version

以 stdio 模式运行

通过 stdin/stdout 传递 JSON-RPC 消息：

docker run --rm -i ghcr.io/hadriangateway/platter

以 HTTP 模式运行

在容器内绑定到 0.0.0.0，以便主机能够访问该端口：

docker run --rm -p 3100:3100 ghcr.io/hadriangateway/platter -t http --host 0.0.0.0

挂载路径

将主机目录挂载到容器中，并使用 --cwd 或 --allow-path 授予 platter 访问权限：

# Mount a project directory as the working directory
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0

# Mount read-only
docker run --rm -p 3100:3100 \
  -v /home/user/project:/work:ro \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 --tools read,glob,grep

# Mount multiple directories with path restrictions
docker run --rm -p 3100:3100 \
  -v /home/user/project:/project \
  -v /tmp/scratch:/scratch \
  ghcr.io/hadriangateway/platter -t http --host 0.0.0.0 \
    --cwd /project \
    --allow-path /project --allow-path /scratch

网络

默认情况下，容器可以完全访问出站网络。你可以使用 Docker 的网络选项对此进行限制：

# No network access (file-only tools)
docker run --rm --network none -i ghcr.io/hadriangateway/platter

# Access host services (e.g. a local database)
docker run --rm -p 3100:3100 --network host ghcr.io/hadriangateway/platter -t http --host 0.0.0.0

在运行时安装其他软件

该镜像基于 Debian，因此你可以在运行时使用 apt-get 安装软件包。这适用于快速实验，但会增加启动延迟。生产环境中，建议改为构建自定义镜像（见下文）。

docker run --rm -p 3100:3100 ghcr.io/hadriangateway/platter \
  bash -c "apt-get update && apt-get install -y git nodejs && exec platter -t http --host 0.0.0.0"

或者进行交互式操作：

docker run --rm -it --entrypoint bash ghcr.io/hadriangateway/platter
# inside the container:
apt-get update && apt-get install -y git python3
platter -t http --host 0.0.0.0

构建自定义镜像

在 platter 镜像之上添加其他工具，构建一个开箱即用的环境：

FROM ghcr.io/hadriangateway/platter:latest

RUN apt-get update \
 && apt-get install -y --no-install-recommends \
      git \
      curl \
      python3 \
      nodejs \
      npm \
 && rm -rf /var/lib/apt/lists/*

构建并运行：

docker build -t my-platter .
docker run --rm -p 3100:3100 -v ~/project:/work my-platter -t http --host 0.0.0.0

在本地构建镜像

docker build -t platter .
docker run --rm -i platter

构建

bun install
bun run build        # bundle to dist/
bun run compile      # standalone binary for current platform -> ./platter
bun run compile:all  # cross-compile for linux-x64, linux-arm64, darwin-x64, darwin-arm64
bun run format       # format with Biome
bun run format:check # check formatting
bun run lint         # lint with Biome
bun run lint:fix     # lint and auto-fix with Biome
bun run typecheck    # typecheck with TypeScript
bun run test         # run tests

许可证

MIT