Filaxis
You can use Filaxis as an MCP server for remote execution, session observation, layered SSH/container access, and verified file operations.
Execute one-off shell commands with stdout/stderr separation, timeout, and truthful exit codes.
Run dependency-ordered batches of exec/edit/read/put/get steps, with parallel execution where possible, stop-on-fail behavior, and per-step evidence; no automatic rollback.
Start long-running tasks immediately and later stop/verify them with
exited/stopped/unknownterminal states.Open continuous observation streams, read recent or continued frames, paginate, and close streams.
Read remote UTF-8 files and return content plus size/mtime metadata.
Perform controlled file edits with unique replacement checks, CAS-style protection, and atomic or inode-preserving writes.
Upload and download binary files between the MCP host and target layers, using exec or SFTP transport with verification.
Create and manage named SSH layers, including jump hosts, idempotent reuse, default-layer targeting, and safe removal.
Enter inner/container shells from an SSH layer and inherit layered execution context.
Supports SSH-to-Linux-host then docker exec into Alpine containers for non-interactive command execution and controlled file editing inside the container.
Adds BSD file-transfer dialect adaptation for remote file operations, helping avoid command/dialect failures on BSD-based targets such as FreeBSD and OPNsense.
Verified SSH integration for Debian hosts covering non-interactive exec, interactive PTY, continuous observation windows, reattaching sessions/watchers after reconnect, verified stop, and file operations.
Integrates with Docker via docker exec/launchCmd and push_into, enabling command execution, file editing, and transfers inside containers while preserving layer context.
Supports FreeBSD-based targets, notably OPNsense devices, over SSH for non-interactive command execution, directory reads, and permission-preserving file writes.
Adds GNU file-transfer dialect adaptation for remote file operations on GNU-based environments.
Targets Linux hosts for remote execution, long-running sessions, observation streams, file transfer, and persistent sessions across local and SSH transports.
Verified SSH integration with OPNsense/FreeBSD devices for non-interactive exec, directory reads, and file writes or overwrites with permissions preserved.
Uses tmux as a persistent session backend, enabling terminalIds to be re-attached across processes with working-directory restoration.
Verified support on Ubuntu for local WSL execution, local tmux persistent sessions, observation windows, tmux reattach/stop, and CI SSH-loopback integration tests.
牵丝 Filaxis
简体中文 · English
千里一线,执行有迹。—— Connect · Execute · Observe · Reattach
面向自动化与 Agent 的远程执行运行时 SDK(Syrkos · 漩核旗下)。TypeScript 编写,Bun 与 Node LTS 双运行时,Windows 与 Linux 同构。CLI / SDK / MCP Server 三入口(filaxis / createAgentToolkit / filaxis-mcp)共享同一工具词汇表;CI 覆盖(均在 Ubuntu runner):Bun 侧跑全量测试与 SSH 自环集成,Node 侧跑类型检查、边界检查、构建与编译版 CLI 冒烟(Node 不重复运行完整测试套)。
import { RuntimeStack } from "@syrkos/filaxis";
const stack = new RuntimeStack();
const host = await stack.connect({ driver: "ssh", target: "my-server" });
// exec:退出码是数据,失败是异常;stdout/stderr 物理分离
const r = await host.exec("uname -a", { timeoutMs: 10_000 });
console.log(r.stdout, r.stderr, r.exitCode, r.effectiveUser);
// 长跑会话:execSession 即返(句柄含 sessionId/logBase/pid)→ 观察 → 停止核实
const cap = await host.execSession("tcpdump -i eth0 -c 100 -w /tmp/x.pcap");
console.log(cap.sessionId, cap.logBase); // 句柄字段
console.log((await host.tailSession(cap.sessionId, 10))); // 热窗口快照(最近 10 行)
const stop = await host.stopSession(cap.sessionId); // 三态:exited/stopped/unknown
if (stop.status === "unknown") {
const v = await host.verifySession(cap.sessionId); // 核实原语(unknown 闭环)
console.log("实测:", v.status, v.exitCode); // running / exited(码) / unknown
}
// 事件(零消息队列依赖——消费方自行接队列/看板)
stack.events.on("exit", (e) => console.log("session", e.sessionId, "exit", e.exitCode));能力矩阵
「成熟度」列:内置=开箱即用且 CI 真机覆盖;可接入=经配置/适配层支持(示例或文档指引);实验=有实现但真机覆盖薄,欢迎试用与反馈。
能力 | 成熟度 | 说明 |
多 Transport 统一语义 | 内置(local/ssh)/ 可接入(docker/k8s/teleport) |
|
exec 双通道 | 内置 | 缺省非 PTY 通道(stdout/stderr 物理分离 + 层上下文拼装:cwd/env/enter 进入管线在独立通道按需重放—— |
长跑会话生命周期 | 内置 |
|
ready() 就绪握手 | 内置 | 回溯匹配热窗口(快输出进程竞态根治);滚出判定有据(evictedCount) |
观察流 | 内置 | 独立 SSH channel 真流式直推(无轮询);ControlMaster 复用;注意力衰减回收 |
持久会话 | 内置 | tmux 后端 terminalId 跨进程 re-attach + cwd 恢复 |
文件传输 | 内置 |
|
受控编辑 | 内置 |
|
环境规格 | 内置 | 两段式自发现(语言/GPU/关键包)蒸馏落盘; |
连接治理 | 内置 | 连接拓扑指纹复用(同拓扑零重建);3 次退避自动重连;层状态机与退化哨兵 |
安全边界 | 内置 | host key 策略显式(tofu 缺省/strict+known_hosts);凭据只传路径永不外泄;渲染永不含密钥内容 |
Related MCP server: Menager MCP Server
安装与运行时
bun add @syrkos/filaxis # 或 npm install @syrkos/filaxis运行时:Bun ≥1.x / Node LTS(内核统一
node:标准库,零 runtime 专有 API——CI lint 断言)npm 依赖:零(
dependencies为空是 AC 门禁项,见bun run check:boundaries)系统依赖按能力分列(
stack.features()探测本机视角——Agent 在容器里跑 filaxis 时探测的是容器内的ssh/tmux/sftp,目标主机的能力经launchCmd层的 shell 自行确认):ssh≥7.3 全功能(-J)、tmux仅持久会话(缺席自动降级非持久)、sftp仅传输快路径
MCP 配置与 Agent Skill
npm i -g @syrkos/filaxis
filaxis mcp-config # JSON,使用 mcpServers
filaxis mcp-config --format toml # TOML,使用 mcp_servers(Codex)命令把 MCP 配置片段写到标准输出,包含当前运行时和 filaxis-mcp 入口的绝对路径。Agent 根据自身平台和所需作用域选择配置位置,再将片段合并到现有配置。
也可直接在 MCP 客户端配置中通过 npx 启动:
{
"mcpServers": {
"filaxis": {
"command": "npx",
"args": ["-y", "-p", "@syrkos/filaxis", "filaxis-mcp"]
}
}
}暴露的 15 个 MCP 工具速览:
命令与批处理:
run_command、run_batch长跑会话与观察窗:
spawn_and_observe、stop_and_verify、observe_stream、read_stream、close_stream文件读写与传输:
read_file、edit_file、put_file、get_file多层连接管理:
push_ssh、push_into、list_layers、remove_layer
npm 包包含 Skill 入口与四份子剧本,以及配套的 AGENTS.md。需要登记 Skill 时,由 Agent 按自身平台的规则处理这些文件。
CLI 文件传输
filaxis put --layer app -- ./config.yaml /app/config.yaml
filaxis get --host user@host --transport sftp -- /var/tmp/result.bin ./result.binput/get 传输单个文件,支持 --layer 和 --host。默认用层的 exec 通道,可进入容器。SSH 目标的文件系统可直接访问时,可显式选择 --transport sftp,包括经 -J 跳板的连接。两条路径都先校验暂存文件再落位,JSON 结果标明校验等级和写入形态。详见 文件同步剧本。
MCP 对应工具是 put_file 和 get_file。local_path 位于 MCP 服务所在机器,remote_path 位于目标层。可用 layer 选择命名层。
已验证的平台与连接方式
操作系统 | 连接方式 | 验证范围 |
Windows | 本地执行(Git Bash) | 本地命令、长跑会话、观察窗、Windows Job 子进程回收 |
Ubuntu Linux | 本地执行(WSL)、本地 tmux、CI SSH 回环 | 本地会话与观察窗、tmux 持久会话重挂与停止、SSH 集成测试。tmux 的 watcher 接管尚未实现 |
Debian GNU/Linux | SSH 直连 | 非交互 exec、交互 PTY、持续观察窗、重连后接管会话与 watcher、核实停止、文件操作 |
Debian GNU/Linux | SSH 单跳( | 非交互 exec、stdout 与 stderr 分离 |
Alpine Linux | SSH 到 Linux 宿主后经 | 容器内非交互执行与受控文件编辑 |
OPNsense(FreeBSD) | SSH 直连(非交互 exec) | 命令执行、目录读取、文件写入与覆盖时保留权限。默认交互登录进入设备菜单,PTY 握手在该配置下不可用 |
SSH 文件中转模式
运行环境限制匿名管道时,可在启动 CLI 或 MCP 服务前设置 FILAXIS_SSH_STDIO_MODE=inherit。使用 SDK 时,在建立 SSH 层前设置。该模式通过临时文件为 SSH 提供标准输入和双流输出。命名层使用非交互探测核实目标和工作目录,后续执行仍以完成哨兵确认退出码。
Windows 上,Filaxis 启动 OpenSSH 子进程时会补齐缺失的系统和账户环境变量,包括 SystemRoot、windir、ProgramData 和 USERNAME。已有值优先,补全只作用于子进程。成功补齐 SystemRoot 时,CLI 和 MCP 会在 stderr 告警一次,SDK 通过注入的 logger 记录。主机剥离这些变量和主机限制匿名管道是两类独立问题。
支持免交互认证的直连、单跳 connParams.jump(CLI -J)及可非交互重放的进入步骤。逐跳 PTY 登录链、交互式进入、持久端口转发和持续观察窗需要可用的匿名管道。会话日志可用 readSessionLog 读取落盘内容。
SSH 秒退 255 且双流为空只能作为排障线索。执行终态未知时,先核实远端状态再决定是否重发。
语义契约要点(使用前必读)
详见包内 AGENTS.md——终止即请求、死亡须核实(unknown 不是失败也不是成功);退出码非零是数据不是异常;PTY 通道 stderr 混流是终端语义;跨流聚合序为到达序。
示例与技能剧本
examples/:跨主机诊断 / 长跑观察 / Agent 工具面最小封装(三可运行示例)
docs/skills/:场景操作剧本(给人也给 Agent)
Benchmark(真实运维对照评测)
四期受控实战评测(涵盖 v0.1.0 ~ v0.2.5,内网与跨地域多跳、明盒与纯黑盒场景;每期内采用同模型对照,跨期因版本、考题与模型档位不同不可直接横向等同)的完整数据、方法论与局限说明见 benchmark.md。
最新一期(第四份:v0.2.5 跨地域无 ProxyJump 真实堡垒机、0 提示纯黑盒 9 处联动故障 + 跨海 PUT/GET 二进制文件传输,Gemini 4 Hydrogen 轻量档位子代理,四组均 100% 达标)总账:
组别 | 方式 | 轮数 | 耗时 | 报错/摩擦 | 全量活跃 Token ( | 纯实战活跃 Token (去文档预读) | 总吞吐 Token (含 cache) |
牵丝 MCP |
| 14 | 225s (3m45s) | 0 | 81,297 | 50,362 | 561,736 |
牵丝 SDK |
| 18 | 273s (4m33s) | 0 | 104,563 | 67,823 | 890,017 |
牵丝 CLI |
| 22 | 368s (6m08s) | 3 | 106,587 | 79,535 | 1,051,857 |
裸 SSH | 原生 | 24 | 483s (8m03s) | 4 | 107,151 | 86,917 | 999,825 |
在跨地域无 -J 纯黑盒排障场景下,牵丝 MCP 组达成 0 报错、墙钟耗时缩短 53.4%、全量活跃 Token 省 24.1%(剥离文档预读的纯实战活跃 Token 省 42.1%、总吞吐省 43.8%)。需要说明的是:上述结果为单次实战采样(非多随机种子统计),且在路径明确的简单局域网任务中裸 SSH 与牵丝差距较小(见报告第一份测试二);牵丝的效率与稳定性优势主要集中在无路径提示、多跳穿透与多故障联动排障场景。
许可
Apache-2.0 + NOTICE(牵丝 Filaxis / Syrkos · 漩核 品牌归属声明)。
Available Tools
15 toolsclose_streamA
关闭由 observe_stream 打开的本地观察窗,确认终止并回收对应的远端观察流进程与通道资源,返回 { window_id, closed: true }。观察完成后应及时调用以防残留流进程;若 window_id 不存在或已关闭则报错(不影响其他观察窗)。
Inputs: window_id (required).
edit_fileA
受控编辑远端文件:精确替换(唯一命中校验,all=true 全替换)+ TOCTOU 乐观锁(他人先写则拒绝)+ base64 保真写回(零 Shell 转义——绝不 sed -i)。未命中/多处命中/冲突均报错不盲写。返回 write_mode:atomic-replace=原子替换;inplace-write=保留 inode(bind mount 挂载点 mv 不可用降级)——非原子写入,中断可暴露半截。
Inputs: new (required), old (required), path (required), all, +2 more.
get_fileA
从目标层下载单个文件到 MCP 服务所在机器(支持二进制)。先传输至本地暂存文件并校验大小与 SHA-256 后再落位,校验失败不破坏已有本地文件;成功时会覆盖已存在的 local_path,返回传输通道、字节大小、校验等级 (verification) 与写入形态 (write_mode)。仅读取远端小文本请用 read_file,批量传输多个文件请使用 run_batch。
Inputs: local_path (required), remote_path (required), layer, transport, +1 more.
list_layersA
列出全部命名层(链路/状态/有效用户/默认层标记)。死层/退化层有警示标注(removeLayer 后按原参数重建)。
Inputs: no named parameters.
observe_streamA
直接启动一条持续输出命令并打开本地滚动观察窗,立即返回 window_id(不等待命令结束)。适用于实时盯日志或持续监控输出(如 tail -f、事件流),配合 read_stream 按游标非破坏回看/翻页/续读,完成后用 close_stream 关闭并回收远端流进程。若需后台起停服务、等待就绪标记并核实进程退出码,请改用 spawn_and_observe + stop_and_verify。
Inputs: command (required), name, layer, stream.
push_intoA
从默认层(或 from 指定层)进入内层 shell(docker exec -i sh / kubectl exec 等)——enter 管线全量继承追加(父层 docker→再 su 不丢)。新层成为默认层。需 ssh 层为源。
Inputs: enter_cmd (required), from, name, label.
push_sshA
建立命名 ssh 层(成为默认层——后续工具缺省落它)。同落点幂等复用(reused=true 返回既有层,不重复建连)+ 落点校验(宁重连不错主机)。跳板传 jump(-J 不占层)。
Inputs: host (required), key, jump, name, +2 more.
put_fileA
从 MCP 服务所在机器上传一个文件到目标层。支持二进制,校验后落位,可能覆盖目标文件。返回校验等级和写入形态。
Inputs: local_path (required), remote_path (required), layer, transport, +2 more.
read_fileA
只读获取目标层中的 UTF-8 文本文件(不修改远端状态),返回 { path, content, size, mtime_ms }。文件不存在、无权限或层不支持元数据时报错;下载二进制文件请改用 get_file,同时读多个文件优先使用 run_batch,后续受控修改请配合 edit_file。
Inputs: path (required), layer.
read_streamA
读取本地观察窗。可读最近帧、按 before_seq 向前翻页、按 window_ms 回看或按 since_seq 续读。每次续读用 last_delivered_seq,gap 表示游标区间有丢失。
Inputs: window_id (required), limit, wait_ms, since_seq, +2 more.
remove_layerA
移出命名层(缺省连接保留在指纹缓存——再建同层零成本;destroy=true 才真销毁连接)。
Inputs: name (required), destroy.
run_batchA
批次组合:一次调用描述多个文件或命令操作(exec/edit/read/put/get),按依赖边(after)拓扑执行——步骤 layer 可覆盖批次 layer;after 可跨层引用步骤 id。无依赖步骤并行,顺序链靠 after 显式保序;默认任一步失败即停(未启动步骤标 skipped)。返回逐步骤状态与证据(退出码/输出/编辑明细)。不做自动回滚(配置恢复≠运行状态回滚——重载可能已产生外部副作用),失败现场交回调用方决策。
Inputs: steps (required), layer, output, max_parallel, +1 more.
run_commandA
执行会自行结束的一次性命令(多条命令/多文件操作请改用 run_batch 一次并行打包;持续盯实时输出且不关心退出码的命令如 tail -f 请改用 observe_stream 直接启动并流式读取;需后台起停服务、等就绪标记并核实进程退出码的任务请改用 spawn_and_observe)。退出码如实返回(非零不是异常——是数据,供条件分支);只有无法执行(超时/中断/连接死)才报错。stdout 与 stderr 分离返回。
Inputs: command (required), layer, timeout_ms.
spawn_and_observeA
启动后台任务或常驻服务(输出落盘到 log_base 对应的 .out/.err 文件,立即返回 session_id 与 log_base 句柄不阻塞)。适用于需要等待就绪标记(ready_marker——回溯热窗口,快输出竞态安全)、自动捕获错误模式(error_pattern——命中即收摊)并在结束后用 stop_and_verify 核实进程终态与退出码的场景。若只需持续流式查看实时输出(如 tail -f / 监控日志)并按游标翻页续读,请改用 observe_stream + read_stream。
Inputs: command (required), name, layer, ready_marker, +1 more.
stop_and_verifyA
停止任务并核实终态。status 三态:exited=拿到退出码;stopped=终止已核实;unknown=核实不可达(非成功非失败——重试核实或显式上报,严禁当已清理)。
Inputs: session_id (required), layer.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
The execution-oriented tools (run_command, run_batch, spawn_and_observe, observe_stream) overlap conceptually, but their descriptions explicitly cross-reference each other and define crisp boundaries (one-shot vs batch vs background-with-readiness vs live tail). The stream family (observe_stream/read_stream/close_stream) and file family (read/edit/put/get) are cleanly separated. The only residual confusion is choosing between spawn_and_observe and observe_stream, which requires reading the fine print.
Every tool follows a snake_case verb_noun pattern (run_command, read_file, edit_file, put_file, get_file, push_ssh, list_layers, remove_layer). Compound verbs like spawn_and_observe and stop_and_verify are a minor stylistic variation but still fit the same convention. The get/put vs read/write vocabulary is used coherently per family.
15 tools map onto four coherent sub-domains: execution (4), files (4), streaming (3), and layers (4). Each tool serves a distinct role in one of these workflows, and the count sits within the well-scoped range for a remote shell/execution platform.
Core CRUD and lifecycle are covered: exec (run_command/run_batch), background lifecycle (spawn_and_observe/stop_and_verify), streaming (observe/read/close), files (read/edit/put/get), and layers (push_ssh/push_into/list/remove). Gaps remain: no directory-listing tool, no file delete, and no way to pop/switch back to a prior layer as default. These are largely workaroundable via run_command (ls/rm) or remove_layer, so coverage is strong but not complete.
Maintenance
Related MCP Connectors
Hosted runtime for persistent agent teams, durable workflows, memory, schedules, and goals.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Related MCP Servers
- AlicenseAqualityBmaintenanceStateful, structured, safe shell sessions for AI agents, on real infrastructure.713Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents or human operators to spawn, monitor, drive, and hook into child terminal sessions—such as CLI tools, interactive shells, and polyglot runtimes—via POSIX pseudo-terminals, providing multiplexed control, event interception, and memory-bounded observability for orchestration.GPL 3.0
- AlicenseAqualityBmaintenanceEnables AI assistants to spawn and control persistent local shells, SSH sessions, REPLs, debuggers, and serial/UART devices with zero-loss output capture, timestamped history, and atomic expect matching for command execution and prompt synchronization.12MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to remotely execute shell commands and transfer files on SSH hosts, including jump-host tunneling, background tasks, resumable transfers, and optional approval of destructive commands, while SSH credentials remain in the local process. It runs over stdio or a streamable HTTP daemon and supports auditing, allow/deny lists, and multiple authentication methods.ISC