Repository navigation
ServerFS v0.24.0
ServerFS v0.24.0 — Optional Cloudflare Tunnel for Linux Docker
Release-candidate notes. Stable publication is controlled by the dispatch-first, exact-SHA release workflow; this document is not evidence that the release tag, wheels, Plugin, GHCR images or GitHub Release already exist.
Highlights
ServerFS v0.24.0 introduces an optional Cloudflare Tunnel ingress for Linux Docker Compose. Existing Streamable HTTP remains the origin protocol; a non-root cloudflared sidecar publishes a remotely managed public hostname through outbound-only Cloudflare connections without a host-published MCP port.
compose.cloudflare.ymladdscloudflaredas an independent service and disables the legacy OpenAI Tunnel by default for this Compose mode.- The connector joins
serverfs_internalandtunnel_egress, with a read-only root, dropped capabilities,no-new-privilegesand one read-only external Tunnel Token mount. The MCP container retains its two private Docker networks,serverfs_internalandserverfs_file_ingress(both internal), and does not jointunnel_egress. - The Tunnel Token is strictly a Connector credential. Remote MCP callers still require effective ServerFS API Key or OAuth, or a separately verified equivalent admission boundary, plus HTTPS and exact Host/Origin policy. Query-string API Key compatibility has URL logging exposure risks.
.env.exampledocuments an overridable, testedcloudflare/cloudflared:2026.10.7tag and an externalCLOUDFLARE_TUNNEL_TOKEN_FILEpath.CLOUDFLARED_UID/GIDare independent ofSERVERFS_UID/GIDso an ordinary host user can own a private0600Token file.- Linux operator guidance, all seven portable Agent Skills (including the new
serverfs-tunnel/references/cloudflare-linux.mdbranch), and English/Simplified-Chinese site content are updated together. The Plugin remains a single skills-only ZIP; no eighth Skill or separate Cloudflare binary installer is introduced.
Public staging acceptance (2026-11-06)
The actual vps-serverfs-mcp.ntlx.top route was tested with the isolated serverfs_cf_staging Compose project and its one staging_fixture read-only workdir, not the existing unauthenticated production ServerFS.
- Cloudflare Tunnel
healthy; proxied CNAME and validated public TLS; unauthenticated/wrong Bearer401, authorizedinitialize200. - Direct ChatGPT
vps-serverfsPlugin tool discovery, directory listing, file metadata/read and file/content search succeeded; hidden.envand path traversal were denied. - Public SSE GET negotiated
text/event-stream, stayed live for more than 60 seconds, produced an event/heartbeat, and accepted threetools/listrequests in the same session. - After a controlled restart of only the staging
cloudflaredcontainer, the same pre-existing MCP Session ID again completedtools/listwithout reinitialization. The production and staging MCP container IDs were unchanged. - Runtime container boundary inspection verified non-root connector privileges, read-only Token mounting, no host port binding, internal MCP networks, no MCP attachment to the connector egress network, and separate Docker project ownership.
The acceptance does not prove production workdir/Agent/Repo Ops connectivity through this ingress, native Windows/macOS Cloudflare lifecycle support, or lossless replay of SSE messages in flight during a restart. The isolated staging deployment has those optional capabilities disabled.
Compatibility and security notes
Cloudflare Tunnel is an alternative to the existing OpenAI Secure MCP Tunnel and generic loopback HTTP; both remain available. The core MCP tools, workdir security defaults, existing Linux Agent Bridge/Repo Ops interfaces and supported native Windows/macOS deployments are unchanged.
Public MCP initialize can return application/json or text/event-stream; parse according to the response media type. An established session should send notifications/initialized before a persistent GET SSE connection. Initial SSE GET response headers can take approximately 15 seconds in the observed staging route. A separate Python-urllib/3 probe received HTTP 403, while a normally identified MCP test client succeeded; the exact Cloudflare/ingress enforcement source was not proven. Do not broadly disable WAF/bot protections to work around this observation.
Use a uniquely named Compose project with its complete overlay set and separate operator-owned --env-file for a new Cloudflare-only deployment. Do not run bare docker compose up against an existing production project or put secrets inside configured workdirs. For detailed operation, see Cloudflare Tunnel runbook.
Release and distribution boundary
- Supported Cloudflare path in this release: Linux Docker Compose, with live
linux/amd64staging evidence;linux/arm64has configuration/image-manifest evidence but no separate live Cloudflare staging acceptance. - Published stable release before this candidate: v0.23.3.
- v0.24.0 release artifacts (upon successful dispatch-first release): project wheel, Agent Bridge wheel, Windows native abi3 wheel, seven-Skill
serverfs-plugin-v0.24.0.zip, immutable release tag and stable GHCR tags. - The unchanged native Windows/macOS functionality still requires the release workflow's native platform CI gates; passing the Linux Cloudflare E2E is not a replacement for those gates.
Windows installation assets (Python >= 3.12; no Rust/MSVC/Docker required)
The three release wheels install into two isolated environments, matching the
frozen ServerFS/Agent-Bridge process boundary (the supervisor selects the Bridge
interpreter through SERVERFS_BRIDGE_PYTHON; the packages never share one dependency
graph):
| file | installs into | sha256 |
|---|---|---|
| serverfs_mcp-0.24.0-py3-none-any.whl | ServerFS env | 9878eb3925653c99b24b7d3a293898d65f5333e1373f4b769d9d128b032e91ee |
| serverfs_windows_native-0.24.0-cp312-abi3-win_amd64.whl | ServerFS env | 4ee5b0250438384637ea2badae46d8ebfbc35b5590f400569b823c3532556741 |
| serverfs_agent_bridge-0.24.0-py3-none-any.whl | Agent Bridge env | aef013f8cba2e940320aa52cf693ac84e3e5cadebbcf3159dea9304f5c995763 |
ServerFS environment (product + native kernel):
uv venv --python 3.12 .venv-serverfs
uv pip install --python .venv-serverfs/Scripts/python.exe https://github.com/NTLx/ServerFS_MCP/releases/download/v0.24.0/serverfs_mcp-0.24.0-py3-none-any.whl https://github.com/NTLx/ServerFS_MCP/releases/download/v0.24.0/serverfs_windows_native-0.24.0-cp312-abi3-win_amd64.whl
Agent Bridge environment (Bridge + provider SDKs; it must NOT contain the product):
uv venv --python 3.12 .venv-bridge
uv pip install --python .venv-bridge/Scripts/python.exe https://github.com/NTLx/ServerFS_MCP/releases/download/v0.24.0/serverfs_agent_bridge-0.24.0-py3-none-any.whl
Point the ServerFS supervisor at the Bridge interpreter (set this in the environment
that starts serverfs supervisor; it is not a provider setting and does not belong in
[agent] config):
$env:SERVERFS_BRIDGE_PYTHON = "<path>\.venv-bridge\Scripts\python.exe"
Verified native-wheel storage alternative:
serverfs bootstrap native-wheel --url "https://github.com/NTLx/ServerFS_MCP/releases/download/v0.24.0/serverfs_windows_native-0.24.0-cp312-abi3-win_amd64.whl" --sha256 4ee5b0250438384637ea2badae46d8ebfbc35b5590f400569b823c3532556741