Fast Spider

English | 简体中文

Use MCP or an AI coding agent to work safely across your own Windows, Linux
and macOS machines.

Fast Spider is a self-hosted remote development and automation platform. It
turns user-owned machines into explicit, auditable capabilities for reading and
editing code, running builds, operating Git, controlling an isolated browser,
moving artifacts and managing local AI coding sessions.

The machine runs the work. Fast Spider provides the identity, routing, job
lifecycle, audit and control plane through MCP, Web Console, CLI and Local
Bridge.

Project status: Fast Spider is an actively maintained, early-stage public
project. The core platform is functional, but the external contributor and
adopter community is still developing. Feedback, reproducible issues and
focused contributions are welcome.

Codex-native development

Fast Spider is developed with Codex as its primary engineering agent. The
maintainer provides product direction, architecture decisions, acceptance
criteria, security and privacy boundaries, and final release decisions. Codex
supports implementation, testing, documentation, code review, debugging and
iterative maintenance under maintainer supervision.

This collaboration is part of the project's normal engineering workflow:

• turn maintainer requirements into scoped implementation plans;
• implement and test cross-platform changes on Windows, Linux and macOS;
• review code, failure paths, permissions and privacy boundaries;
• maintain documentation, release gates and reproducible verification evidence.

Three-part product structure

Fast Spider has three clear runtime parts:

What you can do with Fast Spider

Fast Spider is useful when a coding agent or automation process needs to:

• inspect or change a repository on another machine you own;
• run a Windows-specific build from Linux or a cloud-based MCP client;
• start a test, follow its logs, cancel it and retrieve the final artifact;
• validate a local web application in an isolated browser;
• coordinate Codex or Claude Code sessions without copying their native history;
• keep machine access, job state and operator actions visible in one place.

How a request runs

MCP / Web / CLI / Local Bridge
              |
              v
        Fast Spider Hub
  identity | routing | jobs | audit
              |
        outbound HTTPS/WSS
              |
              v
       Fast Spider Node
 files | shell | Git | browser | AI
              |
              v
     your operating-system user

1. A client asks the Hub to perform a named capability on a selected Node.
2. The Hub authenticates the caller, records the job and routes it to the Node.
3. The Node validates the capability input and runs it with the permissions of
   the operating-system user that started the Node.
4. Progress, logs, results, errors and artifacts return through the same job
   lifecycle and remain available for audit.

Screenshots

Node overview — connection, local permission and runtime status. The private Hub URL is redacted.	AI and routing — provider-neutral Codex and Claude Code discovery and effective capabilities.
Diagnostics — redacted Node, Hub, agent and local capability readiness.	Components — verified browser, search and file capability status.

What it does not provide

Fast Spider is not a hidden remote desktop, privilege escalation tool or generic tunnel.

It does not provide:

• arbitrary TCP forwarding;
• continuous desktop video streaming;
• automatic privilege escalation;
• unrestricted raw provider credential access;
• a second file-system permission model that overrides the operating system.

Node actions run with the permissions of the current OS user. Operators should treat a connected Node as a powerful local automation agent.

Architecture and trust boundary

+-------------------+        HTTPS/WSS 443        +----------------------+
|                   |  ------------------------->  |                      |
|  Fast Spider Node |                              |   Fast Spider Hub    |
|                   |  <-------------------------  |                      |
+-------------------+                              +----------------------+
        |                                                       |
        | local execution                                      | API / MCP / Web
        v                                                       v
+-------------------+                              +----------------------+
| Files / Shell /   |                              | Users / Machines /   |
| Git / Browser / AI|                              | Jobs / Audit / Relay  |
+-------------------+                              +----------------------+

The Hub never directly mounts a Node file system. All execution happens on the
Node and is routed through explicit capabilities. See the
system architecture,
capability reference and
security model for the detailed contracts.

Quick start

Recommended: deploy with Codex

The recommended deployment path is to open this repository in Codex and ask it
to deploy the Web Console, Hub and Node for the target environment. Codex can
inspect the operating system, follow the documented security boundaries, run
the required checks and report the final service state.

Example deployment request:

Deploy Fast Spider from this repository. First explain the Web Console, Hub and
Node topology you will use. Keep the Hub local unless I explicitly approve a
public tunnel. Generate credentials locally, do not commit them or expose them
in logs, run the documented checks, and report the final access URL and service
status.

Requirements:

• Go 1.26+
• Git
• Optional Node.js / Playwright dependencies for browser automation

Three-minute safe trial

The public first-run path uses Project mode. It binds the Node capability
policy to the selected project directory instead of presenting the original
whole-machine Machine mode as the default.

From the Fast Spider source tree:

git clone https://github.com/isguang2024/fast-spider.git
cd fast-spider
go run ./cmd/spiderctl share --project . --tunnel none

share starts a temporary local Hub, creates the first owner and a short-lived
Node connection token, then prints the Node command and MCP URL. It does not
start Node for you: run the printed command in a second terminal. The MCP URL
uses OAuth; the printed Bearer credential is only for Node registration.

For a CLI installed outside the source tree, install the command and provide a
fast-spider-hub binary or set FAST_SPIDER_SOURCE_ROOT:

go install github.com/isguang2024/fast-spider/cmd/spiderctl@latest
spiderctl share --project .

The first safe request to use after connecting is:

Inspect this repository and summarize its structure. Do not make changes.

Use --tunnel cloudflare or --tunnel ngrok only when a cloud client must
reach the local Hub. See Security Model before
sharing a tunnel URL.

Start a local Hub:

FAST_SPIDER_ADMIN_PASSWORD='<replace-with-a-strong-password>' \
  go run ./cmd/hub --data-dir ./data

Initialize the Hub URL and owner bootstrap:

go run ./cmd/spiderctl setup-url \
  --public-url http://127.0.0.1:8787 \
  --allow-insecure \
  --bootstrap-token-file ./data/bootstrap-token

Start the local Node UI:

go run ./cmd/node ui

Or connect a headless Node after creating a connection token in the Hub:

go run ./cmd/node connect \
  --hub http://127.0.0.1:8787 \
  --allow-insecure \
  --token '<connection-token>' \
  --name dev-node

For no-server usage, run Hub locally and expose it with a free or free-tier tunnel only when cloud clients must reach it. See Free Local Deployment.

For more details, see Getting Started, Security Model, Configuration Reference and Deployment and Operations.

Project mode and Machine mode

Project mode is the recommended open-source onboarding profile. The Node
checks file, search, shell/build working directories, Git repositories and
artifact paths at the capability boundary and rejects paths outside the bound
project root. Native desktop/window screenshots are disabled in this mode.
Shells, Git remotes, browsers and AI providers can still have side effects, so
Project mode is a path-constraint profile, not an operating-system sandbox.

Machine mode remains available for private, advanced use and preserves the
original OS-user trust boundary. Do not expose a Machine-mode Node through a
public tunnel unless you understand and accept the whole-machine risk.

MCP tools

The current public surface contains the following top-level MCP tools:

machine_list
machine_get
capability_list
audit_log
operation_log
file_read
file_edit
code_search
shell_run
job_watch
job_cancel
git_control
build_control
artifact_get
browser_control
screenshot_take
thinking_team
ai_control
working_context

Tool inputs use explicit absolute paths for machine-local operations. Examples:

• file_read, file_edit, code_search: absolute path
• shell_run, build_control: absolute cwd
• git_control: absolute repositoryPath
• ai_control.session.create: absolute workingDirectory

The Windows Node UI asks for a Codex session mode on first launch and stores that choice in its local configuration. Shared mode is the default recommendation: Fast Spider does not claim loaded sessions through Codex Desktop IPC, so Desktop can open them without showing “already open in another application.” FS managed mode enables the owner/control bridge for FS-loaded local sessions. The Node UI setting is authoritative; FAST_SPIDER_CODEX_DESKTOP_BRIDGE remains a compatibility fallback for headless run/automation processes that do not use the Node UI. Public ai_control discovery and local session results include desktopBridge state. The bridge preserves Fast Spider's existing app-server execution path and does not yet promise native Desktop live-history rendering.

Documentation

Start here:

• Documentation Index
• Getting Started
• Getting Started (简体中文)
• Free Local Deployment
• Free Local Deployment (简体中文)
• Security Model
• 安全模型（简体中文）
• Configuration Reference
• Product Vision
• Requirements and Scope
• System Architecture
• Hub Design
• Node Design
• Node Capabilities
• Public API and MCP
• Deployment and Operations
• Security Threat Model
• Test Strategy
• Public Release Guide

Development

Run the standard checks:

go test ./... -count=1
go vet ./...
git diff --check

Run the public release hygiene check:

bash scripts/public-release-check.sh

Run the release gate:

bash scripts/release-gate.sh

Run the extended release gate where the required local runtimes are available:

bash scripts/release-gate.sh --full

Pull requests are also checked by the public GitHub Actions workflow. See the
maintainer workflows for issue triage, review,
release and responsible AI-assisted maintenance practices.

Public source release

Do not publish private development history as the public repository history.

Use the public export flow to create a clean source snapshot with a new root commit:

bash scripts/public-export.sh \
  --output /absolute/path/fast-spider-public \
  --require-license

See Public Release Guide for the full policy.

Security

Read SECURITY.md before reporting a vulnerability or sharing logs.

Never publish:

• connection tokens;
• Direct Access Keys;
• private keys;
• environment files;
• production backup paths or backup archives;
• logs containing machine identifiers, credentials or local private paths.

Contributing

Contributions should follow CONTRIBUTING.md and the Code of Conduct.

Project decisions and maintainer access follow GOVERNANCE.md.
For usage questions and reproducible defects, see SUPPORT.md.
Notable public changes are recorded in CHANGELOG.md.

Community

Fast Spider recognizes and supports the developer community at
LINUX DO. Project discussions and contributions remain
open to everyone through this repository.

License

Fast Spider is released under the Apache License 2.0. See LICENSE.

Third-party dependency notice guidance is available in THIRD_PARTY_NOTICES.md.