synapse

Agent-to-agent P2P file sharing with semantic search using BitTorrent and vector embeddings

Security Scan

The skill's code and instructions mostly match a P2P semantic-sharing tool, but it includes several behaviors that can access or export an agent's local vector DB, read OpenClaw config, recommend running remote install scripts, and enable loading remote model code — these features are coherent with the stated purpose but carry non-trivial exfiltration and supply-chain risks and require careful review before use.

Purpose & Capability

The name/description match the provided Python code: BitTorrent engine, embedding generation, tracker integration, seeder daemon and 'create/assimilate' memory shard flows are all consistent with a P2P semantic sharing tool. However, the skill exposes tools that read arbitrary local DB paths (create_memory_shard) and will load/save config under ~/.openclaw — capabilities that are appropriate for a memory-sharing skill but also permit exporting sensitive local vector DBs or reading agent config. The presence of code that reads OpenClaw configuration (get_openclaw_config / get_skill_env_vars) is plausible for integration but should be considered sensitive because it can surface other configured secrets.

Instruction Scope

SKILL.md instructs installing 'uv' via a curl | sh one-liner and repeatedly instructs running 'uv run python client.py' (which will auto-install dependencies and model files on first run). The skill.json handlers execute python3 logic.py on user-supplied file paths (e.g., --source_db, --shard_path, --target_db), which gives the skill direct ability to read arbitrary files provided by the caller. The assimilation tool exposes a --skip-safety-check option (handler maps to --skip-safety) which can bypass local guardrails. The SKILL.md also references reading logs and config under ~/.openclaw. These instructions give broad discretion to read, transform, and transmit local data and to bypass safety checks — more than a simple 'search/download' helper would normally need.

Install Mechanism

There is no formal install spec; SKILL.md recommends installing 'uv' with curl -LsSf https://astral.sh/uv/install.sh | sh (remote shell install). The project relies on auto-install of many heavy Python dependencies (libtorrent, sentence-transformers, torch, CUDA bundles, optimum/onnx-related packages) when run under 'uv'. Auto-downloading and converting models (including trust_remote_code=True) and installing large GPU packages are supply-chain and resource-heavy operations; the remote install line increases risk.

Credentials

The skill.json declares no required env vars, but the code reads and writes config under ~/.openclaw (get_openclaw_config, save_config) and exposes get_skill_env_vars which extracts env entries from OpenClaw's configuration. That can expose other skill settings or secrets stored in OpenClaw config. The create_memory_shard tool explicitly asks for a path to the agent's vector DB (source_db) — a legitimate feature but one that can be used to exfiltrate sensitive agent memory. The presence of a skip-safety option further reduces protections.

Persistence & Privilege

The skill does not request always:true and is user-invocable. It does read/write files under the user's home (~/.openclaw/*) and will save its own config there by default; that is expected for a node daemon but does create persistent artifacts on disk. It does not appear to directly modify other skills' code, though it can read shared OpenClaw config which is a broader privilege than a purely local CLI would need.

Scan Findings in Context

[TRUST_REMOTE_CODE] expected: embeddings.py loads tokenizer/model with trust_remote_code=True to support nomic/custom models. This is likely necessary to load the stated embedding model but allows arbitrary code execution from a model repository and is a known supply-chain risk.

[CURL_SH_INSTALL] unexpected: SKILL.md recommends installing 'uv' via curl | sh (astral.sh). Bootstrapping an environment with a remote install script is convenient but increases supply-chain risk and should be avoided or audited before running.

[READ_OPENCLAW_CONFIG] expected: The code reads ~/.openclaw/openclaw.json and provides get_skill_env_vars. Reading OpenClaw config is expected for deep integration, but it may expose environment variables or secrets configured for other skills — this is sensitive and should be disclosed to the user.

[EXECUTE_ON_USER_PATHS] expected: skill.json handlers run logic.py with user-supplied file/db paths (source_db, shard_path, target_db). This is necessary for exporting/importing memory shards but means the skill can read arbitrary files provided to it — treat such invocations as potential data export actions.

[SKIP_SAFETY_FLAG] unexpected: Assimilation endpoint and CLI expose a --skip-safety (skip guardrail checks) option. While useful for debugging, allowing bypass of safety checks in production is risky and could enable assimilation of malicious shards without review.

What to consider before installing

Key things to consider before installing or running this skill: - Review code locally first: the package contains Python code that will run on your machine; scan the logic.py/assimilation/identity modules to ensure they do what you expect. - Do not run the curl | sh install line (astral.sh) without inspecting it; prefer installing 'uv' from a trusted package source or manually managing a virtualenv. - Treat 'create_memory_shard' as an explicit data-export capability: do not point it at any local vector DBs or memory files that contain sensitive or private information unless you intend to share them. - Keep auto_assimilate disabled and never use the skip-safety option in production; assimilation has guardrails but the skill exposes a bypass. - The embedder sets trust_remote_code=True when loading models — this can execute arbitrary code fetched with the model. If you must use the skill, avoid loading untrusted model repositories or remove trust_remote_code usage. - Expect large network and disk activity (downloading models, libtorrent, CUDA packages); run inside an isolated environment or container to limit blast radius. - The skill reads ~/.openclaw/openclaw.json (OpenClaw config). If that file contains secrets or tokens, consider isolating or auditing before use. - If you plan to join public trackers (e.g., hivebraintracker.com) or use the default tracker, verify the tracker endpoint and privacy implications; the tracker may collect metadata about what you share/search. If you want, I can: (1) point out exact lines/functions that perform each risky action, (2) produce a minimal checklist for a safe test-run (isolated container, network off, no OAuth tokens present), or (3) suggest precise code edits to remove trust_remote_code and the skip-safety bypass.

Synapse Protocol - Installation & Usage

P2P file sharing with semantic search. Share any file, find it by content similarity.

For features and architecture, see README.md.

🚀 Installation

Prerequisites

• Python: 3.10 or higher
• uv: Package manager (install)

Quick Install

# 1. Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Navigate to Synapse directory
cd /path/to/HiveBrain/Synapse

# 3. Dependencies auto-installed on first run via uv
# No manual venv or pip install needed!

# 4. Verify installation
uv run python client.py --help

Note: Always use uv run python instead of python3. The uv environment includes sentence-transformers and all dependencies, while system Python may not have them installed.

📝 Usage

Seeder Daemon Control

# Start seeder daemon (runs in background)
uv run python client.py seeder start

# Check status
uv run python client.py seeder status

# Stop daemon
uv run python client.py seeder stop

Share Files

# Share a file (auto-starts seeder if needed)
uv run python client.py share /path/to/file.md \
  --name "My Document" \
  --tags "doc,knowledge"

# Output: magnet link + starts seeding

Stop Sharing

# List what you're sharing
uv run python client.py list-shared

# Stop sharing a specific file
uv run python client.py unshare <info_hash>

Search Network

# Search by content similarity
uv run python client.py search \
  --query "kubernetes deployment guide" \
  --limit 10

# Returns: ranked results with similarity scores

Download Files

# Download using magnet link from search results
uv run python client.py download \
  --magnet "magnet:?xt=urn:btih:..." \
  --output ./downloads

⚙️ Configuration

Environment Variables

export SYNAPSE_PORT=6881
export SYNAPSE_DATA_DIR="./synapse_data"

Tracker Configuration

Default tracker: http://hivebraintracker.com:8080

To use custom trackers:

uv run python client.py share file.txt --trackers "http://tracker1.com,http://tracker2.com"

🔍 Testing Installation

# Check uv installed
uv --version

# Test CLI (auto-installs dependencies on first run)
uv run python client.py --help

# Test seeder
uv run python client.py seeder status

🆘 Troubleshooting

Issue: ModuleNotFoundError: No module named 'libtorrent'

• Solution: Add to pyproject.toml or install: uv pip install libtorrent

Issue: sentence-transformers not found error

• Solution: Use uv run python instead of python3. System Python doesn't have the dependencies.
• Alternative: Manually activate: source .venv/bin/activate && python client.py ...

Issue: Port 6881 already in use

• Solution: Change port: export SYNAPSE_PORT=6882

Issue: Seeder daemon won't start

• Solution: Check logs: cat ~/.openclaw/seeder.log

Issue: Search returns 0 results

• Solution: Ensure file was shared WITH embedding registration (check tracker logs)

📚 Available Commands

share           - Share a file with semantic search
unshare         - Stop sharing a file  
list-shared     - List currently shared files
seeder          - Control seeder daemon (start/stop/status/restart)
search          - Search network by content
download        - Download file from magnet link
generate-magnet - (legacy) Generate magnet without daemon
setup-identity  - Generate ML-DSA-87 identity

📖 Next Steps

• Read README.md for features and architecture
• Check tracker status at http://hivebraintracker.com:8080/api/stats
• Join the network and start sharing!