convez.ai
MCP ServerIntegração & APIsAvançado
cgfixit

CyClaw

cgfixit/CyClaw

RAG local com auditoria, sem dados saindo de casa

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que responde perguntas sobre seus documentos rodando 100% localmente no seu hardware. Usa um grafo LangGraph de 12 nós para recuperação com auditoria completa, embeddings e BM25 na CPU, com fallback opcional para Grok ou Claude mediante consentimento por pergunta.

Instalação

$npx convez-ai cgfixit/CyClaw

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 1 dia
Versão
—
Issues abertas
10
Contribuidores
12

Casos de uso

  • Consultar documentos privados sem enviar dados para a nuvem
  • Configurar um assistente documentário com controle total sobre fallbacks pagos
  • Auditar e rastrear todas as consultas e gastos com modelos externos

Veredito

CyClaw é uma solução robusta de RAG local com forte foco em privacidade, auditoria e controle operacional. Adequado para organizações que exigem retenção total de dados sensíveis e transparência de custos com fallbacks externos.

README

A tradução para o português deste README ainda está na fila.

CyClaw

Python 3.12 FastAPI LangGraph CyClaw CI/CD testing

CyClaw console answering from the local library

Watch the 60-second demo (MP4) — silent, with real local retrieval and inference using synthetic documents.

CyClaw answers questions from your documents on your hardware. Its 12-node LangGraph retrieves first and audits every path, and requires per-question consent for paid Grok or Claude fallback. The server binds to 127.0.0.1:8787.

  • Embeddings, BM25, and the cross-encoder run locally on CPU; cache both retrieval models before going offline.
  • Soul, ops, memory, and audit routes require operator access, which fails closed without CYCLAW_API_KEY (an enabled admin's login also works when per-user auth is on).
  • Audit records hash questions by default; the spend ledger records billed tokens; cyclaw-metrics reads both offline.
  • Guardrails (NeMo in every base install), the Numbat stream, and the spend ledger ship on. Auth, memory, connectors, and the Telegram/X channels ship off.

CyClaw serves one trusted operator, or a mutually trusted group with auth enabled; it provides neither tenant isolation nor a microVM (threat model).

Install and API recipes: Setup Guide. Contributor contracts: CLAUDE.md, AGENTS.md, Codex guidance, Actions guide. Install the Git hooks with bash scripts/ensure-githooks.sh; verify git config --show-origin --get core.hooksPath selects .githooks unless an existing hook manager was preserved. Hook file guide. Residual security decisions record accepted limits and research; native Windows verification remains disabled.

Confirmed fallback sends questions externally. Context stays local unless policy.fallback.send_local_context_to_grok or send_local_context_to_claude is enabled; soul content is never added. Model downloads and optional sync/channels have separate connections. For no-egress use, pre-cache models, disable optional connections, and enforce an external network boundary.

Quick Start

macOS (Apple Silicon) — install, keys, Ollama, index, and startup:

git clone https://github.com/cgfixit/CyClaw && cd CyClaw
bash macos/setup-cyclaw.sh

Linux — Ollama already running on 127.0.0.1:11434. The shipped MLX model tag targets Apple Silicon. Before starting the gateway, set both models.local_llm.model and guardrails.model in config.yaml to the Linux-compatible tag you pull below (or another installed model that fits your hardware):

git clone https://github.com/cgfixit/CyClaw && cd CyClaw
python3.12 -m venv .venv && source .venv/bin/activate
pip install --require-hashes --no-deps -r locks/requirements-torch-lock-linux.txt --index-url https://download.pytorch.org/whl/cpu
pip install --require-hashes -r locks/requirements-lock-linux.txt
pip install --require-hashes -r locks/requirements-test-lock-linux.txt
ollama pull qwen3.8:27b
export CYCLAW_API_KEY="$(openssl rand -hex 20)"  # operator routes; /query uses sessions/tokens when auth is on
python -m retrieval.indexer                      # once; without this, /query is 503
python gate.py                                   # http://127.0.0.1:8787

CI checks every lock group against recorded inputs and hashes, and checks wheel dependency metadata. Refresh on arm64 macOS with the maintained lock scripts; generation failures leave tracked locks unchanged.

Windows uses the same pins with the -windows lock files (py -3.12 -m venv .venv, .\.venv\Scripts\Activate.ps1): Windows, Linux. Choose a non-MLX local model and update both model keys there as well.

Confirm: curl http://127.0.0.1:8787/health, then open http://127.0.0.1:8787/. A manual macOS install uses plain torch==2.14.1 (no +cpu wheel) then the hashed macOS lock (macOS (Apple Silicon)); updating an existing environment ends with the NeMo verification.

Audit the whole checkout in one command, without touching your working tree (it runs the checkers, ruff, every CLI and subsystem selftest, the in-process graph swarm, and a scratch gate.py probed against the route contract): .venv/bin/python .claude/skills/CyClaw-Sandbox/local_audit.py --mock-ollama. Add --browser (needs Playwright) to render the console in Chromium too. pytest and the coverage gate stay with GitHub Actions; the ladder, opt-in steps and what a green run does not prove are in the CyClaw-Sandbox skill.


For newcomers

Python and install paths. Use Python 3.12 (>=3.12,<3.13): macOS, Windows, Linux above, Docker (linux/amd64, loopback), or conda (environment.yml). The constrained editable install adds cyclaw-* commands; source checkouts use python gate.py and python -m retrieval.indexer. Lock maintenance.

Secrets. gate.py reads environment variables, never dotenv files (Invoke-CyClaw.ps1 reads only non-secret settings from an owner-only %USERPROFILE%\.CyClaw\.env or checkout dotenv).

Secret persistence.

PlatformSetupOperationDefault secret storePlaintext opt-in
macOSmacos/setup-cyclaw-keys.shSet up or preserve gateway keyKeychain--write-env-file
Windowspowershell/Install-CyClaw.ps1Migrate existing plaintext secretsCredential Manager-WriteEnvFile

On Linux, macos/invoke-cyclaw.sh stores the gateway key in libsecret or an owner-only file (macos/cyclaw-linux-key.sh). Services read secrets at execution through macos/cyclaw-keychain-env.sh or powershell/CyClaw-CredMan-Env.ps1, never from dotenv, plist, task XML, config.yaml, shell rc files, or argv; a configured keystore lookup fails closed when its item is missing. A missing provider key leaves that provider unavailable, not the server down (provider keys).

Offline and hybrid. Shipped app.mode: hybrid needs an enabled, available, selected provider and per-request confirmation for paid fallback. Offline mode or declining stays local. Downloads have separate controls: models.embeddings.offline_after_index: true requires cached embeddings; pre-cache the ~91 MB reranker before its first query.

Ports. Gateway 127.0.0.1:8787 (api.port, launcher CYCLAW_GATE_PORT; unquoted integer 1..65535, invalid values refuse startup), Ollama 127.0.0.1:11434. The retired :8790 console became CG-agent-harness.

First-run checks and limits.

  • 503 INDEX_NOT_FOUND: run python -m retrieval.indexer or Build my library (POST /index/build, GET /index/status). Build requires loopback, same-origin, no forwarding headers; configured keys require unlock.
  • Console mode and Library/Engine chips expose readiness. /health: degraded usually means Ollama is down; startup TELEMETRY KILL is expected.
  • External health probes ship off (api.health_probe_external_providers). Key presence/model readiness does not establish successful generation.
  • Per-IP rate limit: 60/min, reset on restart unless api.rate_limit.persist_path or Postgres persists it. /health and /index/status are public/unlimited. Bodies above security.max_request_body_bytes (1 MiB) return 413.
  • CORS allows http://127.0.0.1:8787 and http://localhost:8787; /query rejects cross-site requests. Restart after sanitizer-config edits. CYCLAW_EMBED_CACHE_SIZE (2048) is an environment variable.
  • Run python .claude/skills/invariant-guard/check_invariants.py and python .claude/skills/doc-sync/doc_sync.py; exercise changed behavior. Hosted CI owns broad suites.
  • At api.max_concurrent_queries (4), /query returns 503 GRAPH_BUSY; exceeding api.graph_timeout_sec (780 s) returns 504 GRAPH_TIMEOUT.

Local records. Paths are relative to the repository.

PathGit statusContents and behavior
logs/audit.jsonlignoredAuthoritative audit, written synchronously on the request thread. Questions use persistent HMAC-SHA256 fingerprints by default, including when logging.audit_fields is absent or empty. Explicit include_query_hash: false stores redacted query text
logs/spend.jsonlignoredTokens for billed Grok/Claude calls, without query text or prices
logs/numbat-events.ndjsonlignoredDerived redacted audit and out-of-band events; observation only
logs/cyclaw.logignoredApplication log; a bounded writer drops records rather than holding a request on stalled I/O
logs/evals/ignoredOpt-in dogfood and judge output, separate from production billing
index/ignoredChroma and bm25.json; rebuild after corpus changes
data/personality/soul.mdtrackedChanges appear in git status and broad staging
data/personality/cyclaw_soul.dbignoredVersion DB; not yet generated in a clean checkout
data/personality/soul.md.bakignoredVetted backup; not yet generated in a clean checkout

Day-two:

python -m metrics                           # spend, audit aggregates, sequences
python -m retrieval.clear_cache             # dry-run; --apply deletes .emb_cache
python -m retrieval.indexer                 # rebuild after editing data/corpus/
curl -s http://127.0.0.1:8787/index/status   # build progress

What It Does

CyClaw retrieves Markdown and .txt documents before generation. Output rails enforce a token-overlap floor on retrieved local answers; that heuristic does not verify individual claims, which the evals measure.

  1. Retrieval first. retrieve starts the 12-node graph; a miss can still reach offline_best_effort with partial context.

  2. Hybrid search. ChromaDB and BM25 fuse through RRF (retrieval.rrf_k). A vault hit needs the best cosine to clear retrieval.min_semantic_score (without cosines, the fused score must clear the RRF-scale retrieval.min_score); the cross-encoder runs in shadow mode (retrieval.min_rerank_score: null). Retrieval reference.

  3. Local generation. Ollama uses models.local_llm.model (shipped qwen3.8:27b-mlx). Tune context/sampling for your hardware in config.yaml. An optional derived tag stores num_ctx; macos/Modelfile.cg builds the unpublished qwen3.8:27b-mlx-cg. Keep a suffix to avoid overwriting the registry tag. Local bearer tokens come from models.local_llm.api_key_env or models.local_llm.fallback.api_key_env (defaults CYCLAW_LOCAL_LLM_API_KEY and CYCLAW_LOCAL_LLM_FALLBACK_API_KEY). Unset means no auth header. Startup rejects inline api_key values, including in disabled fallback.

  4. Governed soul. data/personality/soul.md has SHA-256 drift detection and atomic writes; POST /soul/apply requires a human reason and an enforced injection scan. Restore audits an advisory scan of the vetted backup without enforcing it; /soul/reload and startup drift recovery adopt on-disk content unscanned. A missing soul self-initializes (Soul invariants, Rules 4–5).

  5. Confirmed external fallback. Grok (grok-4.5, api.x.ai) or Claude (claude-sonnet-5, api.anthropic.com) needs hybrid mode, that provider enabled and selected, user_confirmed_online: true on the request, and a key. Calls share the remaining api.graph_timeout_sec budget, and utils/endpoint_trust.py rejects rewritten provider URLs.

  6. HTTP and MCP. FastAPI serves the browser at /; the separate MCP server exposes sanitized retrieval only (sampling: None, no generation).

  7. Audit convergence. Every path converges at audit_logger before END; cyclaw-metrics reads the audit offline.

Six invariants include core import isolation; INVARIANTS.md maps Rules 1–9 to tests.

Storage/console. Embedded chroma defaults, optional pgvector (indexing.vector_backend); BM25 uses JSON, never pickle. static/terminal.html provides queries, first-run build, health, Soul/Sync/Filesystem panels, and authenticated Users/Audit.

Optional layers at a glance

LayerPurposeShips
Per-user authPasswords, sessions, device tokens, rolesoff
MemorySQLite/FTS5 facts and episodes, propose/apply, optional retrieval fusion and HTML exportoff
NeMo GuardrailsDeny-only input/output checks, deterministic fallback on NeMo failureon
Dropbox syncOut-of-band rclone corpus pullCLI
ConnectorsScoped filesystem, passive LAN inventoryoff
Telegram / OpenTweetPhone remote and X drafts through loopback /queryoff
Numbat stream / pre-action hookDerived NDJSON, observation only; deny-only gate before a confirmed external callon / off
Spend ledgerBilled token countson
Fine-tune kitSeparate QLoRA toolkittoolkit

Architecture

gate.py initializes the soul at startup; requests pass the body cap, Host allowlist, any required authentication, the 60/min per-IP limit, and the injection filter (in that order), then enter the graph as GraphState.

flowchart TD
    A(["Client\nHTTP POST /query"])
    A --> B

    subgraph GATEWAY ["gate.py — FastAPI 127.0.0.1:8787"]
        B["TrustedHostMiddleware\nHost header allowlist"]
        B --> C["Rate Limiter\n60 req/min per IP"]
        C --> D["Prompt Injection Filter\n40 patterns · config-driven"]
        D --> E["Build GraphState\nquery + user_confirmed_online"]
    end

    E --> F

    subgraph GRAPH ["graph.py — LangGraph 12-node State Machine"]
        F(["retrieve\nChroma + BM25 + RRF"])
        F --> G["route_by_score\nbest cosine ≥ 0.30?\n(RRF ≥ 0.028 if no cosine)"]
        G -->|"YES — local context"| X["guardrail_input\noffline rail · default on"]
        X -->|"blocked"| L
        X -->|"passed · high score"| H["local_llm\nOllama :11434"]
        G -->|"NO — vault miss"| I["user_gate\nneeds_confirm = true"]
        I -->|"confirmed + hybrid\n+ grok.enabled + provider=grok"| PG["pre_action_hook_grok\ndeny-only · off = pass-through"]
        PG -->|"allow"| J["grok_fallback\ngrok-4.5 · triple-gated"]
        I -->|"confirmed + hybrid\n+ claude.enabled + provider=claude"| PC["pre_action_hook_claude\ndeny-only · off = pass-through"]
        PC -->|"allow"| W["claude_fallback\nclaude-sonnet-5 · triple-gated"]
        I -->|"declined or offline"| X
        X -->|"passed · vault miss"| K["offline_best_effort\nlocal LLM · no RAG gate"]
        I -->|"confirmed=None — pause"| L
        H --> Y["guardrail_output\noffline rail · default on\ngrounding: local_llm only"]
        J --> Y
        W --> Y
        K --> Y
        Y --> L
        PG -.->|"deny"| L
        PC -.->|"deny"| L
        L(["audit_logger\nHMAC fingerprint · PII redact\nlogs/audit.jsonl\n+ derived Numbat stream"])
    end

    L --> M(["QueryResponse\nanswer · sources · model_used\nretrieval_mode · needs_confirm"])

    subgraph RETRIEVAL ["retrieval/hybrid_search.py"]
        N["ChromaDB\nsemantic · 384-dim cosine"]
        O["BM25Okapi\nkeyword · Porter stemming"]
        P["RRF fusion\nk=60 · equal weighting"]
        N --> P
        O --> P
    end

    F <-->|"hybrid search"| P

    subgraph SOUL ["utils/personality.py"]
        Q["soul.md\nSHA-256 drift detection"]
        R["SQLite / Postgres\nversion history"]
        Q <--> R
    end

    H <-->|"soul preamble\n≤ 8000 chars"| Q
    K <-->|"soul preamble"| Q

The MCP server calls the retriever directly after sanitization and never enters this gateway or graph. The diagram omits the per-answer NeMo check() and the post-graph CEL monitor (Optional layers).


API Key Setup (Soul Mutations)

/soul/*, /ops/*, /memory/*, /query/export/html, and /audit/summary require operator access. /health is public; /query requires a session or device token when auth.enabled is true. Operator credentials are:

  • Bearer CYCLAW_API_KEY, for HTTP clients and scripts (compared with hmac.compare_digest).
  • The console cookie. "Unlock operator tools" trades the key once for an HttpOnly, SameSite=Strict cookie (security.console_session_ttl_sec, 1 h shipped); "Lock" deletes it with matching TLS attributes, and rotating the key revokes every cookie.
  • An admin login, when auth.enabled is on (no key needed); operator and audit accounts do not get operator access.

Cookie writes require CSRF; cross-site requests fail. Tokens bind origin; TLS uses __Host- cookies. Because cookies lack port isolation, use a dedicated TLS hostname alongside untrusted services. Without CYCLAW_API_KEY, key/cookie access fails closed; enabled admin sessions still work.

macos/invoke-cyclaw.sh and powershell\Invoke-CyClaw.ps1 generate a missing key into the OS keystore and open a single-use #pair=... unlock link (5 minutes). To unlock by hand, copy the key into the dialog:

# macOS
security find-generic-password -a "$(whoami)" -s com.cgfixit.cyclaw.api-key -w | pbcopy
# Windows, from the CyClaw folder
. .\powershell\CyClaw-SecretStore.ps1; (Read-CyclawCredential com.cgfixit.cyclaw.api-key).Secret | Set-Clipboard

Do not persist the key with setx or a user environment variable; the launchers read it from the keystore into the gateway process only (powershell/README.md). Rotation, the macOS bootstrap, and 401 recovery: macos/README.md.

security.api_key_optional ships false; when set, a request skips the key only if the socket peer is loopback, no forwarding header is present, and the request is not cross-site (inert under Docker NAT). It does not disable per-user authentication or RBAC. Full boundary: INVARIANTS.md Rule 6 and the threat model (fourteenth amendment).

Per-User Authentication

Separate from the operator API key. gate_auth.py: scrypt passwords, a session cookie plus CSRF for browsers, named device tokens for scripts, roles admin, operator, and audit. Ships auth.enabled: false; while off, every /auth/* route returns 503. Assigned roles survive restarts, including demotions of the bootstrap account. Design, TLS, and the non-loopback bind rule: docs/AUTHENTICATION_DESIGN.md; first-boot curl and cyclaw-user: setup-guide.md. cyclaw-gen-cert writes the self-signed cert for the auth + TLS bind exception.


Spend Tracking

Billed Grok/Claude calls append tokens to logs/spend.jsonl; dollars are computed at read time, so rate-card fixes re-price history. Rows exclude queries, prompts, and keys, and a failed write drops the row, not the answer. Core Grok/Claude requests also reserve a durable call allowance before each POST attempt, retries included: 100 per UTC day and 1,000 per UTC month by default (zero denies all). Dollar spend is not enforced.

sourceWriterCovers
queryllm/client.pyConfirmed /query fallback
agenticnone since October 2026 (the agentic coding loop was removed)Historical rows only; still parsed and reported
evaltests/judge_eval.pyOpt-in judge runs, kept separately under logs/evals/

python -m metrics reports today and last_7d tokens and USD by provider and source, and its forensic Sequences section flags a blocked injection followed within 15 minutes by a paid call (no policy enforced). tests/spend_live_probe.py spends real money and is opt-in only. Ledger schema, rate bands, and probes.


Benchmarks and Evals

Only the retrieval gate blocks merges; none of these four paths is a graph node or a security control. Thresholds and limits.

EvaluationCommandScope
Retrieval gatepython -m tests.ci_rag_smokeEvery PR, no LLM. Corpus probes through route_by_score_node, then hit@5, Recall@5, and MRR on the 52-case fixture (44 scored, 8 out-of-corpus skipped). Metric floors and [FILTERED] injection-chunk assertions block CI
Local dogfoodCYCLAW_EVAL_DOGFOOD=1 python scripts/cyclaw-eval-dogfood.pyOpt-in real loopback model, one case per category (recipe)
Anthropic judgeCYCLAW_EVAL_LIVE=1 python tests/judge_eval.pyPaid opt-in Claude grades groundedness, completeness, abstention
Local judgeSame command with evals.local_judge.enabled: trueSame rubric on a second loopback model with a different configured tag; choose a separate family and calibrate it

Fixture retrieval scores 1.0 on all three metrics (no claim about arbitrary corpora). The reranker bake-off found no passing threshold, so vetoing stays off. The only published local run is the Qwen dogfood audit; no judge result is published yet.


Current development

Current changes and dated decisions live in the merged PRs and docs/changelog.txt. Install and contributor contracts: locks, Git hooks.


Optional layers

Dropbox sync. Out-of-band rclone pulls into data/corpus/, bounded by deletion/transfer limits and a single-instance lock; exit 10 requests reindex. Run python -m sync.cli setup, test, sync --dry-run, then sync. Status/scheduling: CLI guide, walkthrough. Generated schedules load encrypted-config passwords from OS keystores.

Native scheduling. Plist/task generators print activation commands; token-bearing jobs use keystore wrappers. Supervised gateway generators (macos/generate_service_plist.py, windows/generate_service_task.py) require --confirm and a nonempty --reason. Operations, design.

Fine-tuning. The separate QLoRA toolkit is excluded from runtime installs. Its CUDA training profile is currently blocked by dependency conflicts; CPU preparation/dry runs remain available: python tools/lora_finetune/build_cyclaw_corpus.py, then python tools/lora_finetune/dryrun_finetune.py. Training may download a checkpoint; pre-cache before no-egress use.

Connectors. Default-off, out-of-band fsconnect offers bounded reads and gated writes (refused on Windows); netconnect inventories explicit RFC1918/loopback CIDRs passively. Neither calls an LLM. Removed October 2026 components.

python -m agentic.fsconnect.cli status
python -m agentic.netconnect.cli status

Filesystem, passive network, and the package map.

NeMo Guardrails

guardrails.enabled: true ships in config.yaml; explicit false or an absent block disables it. utils/guardrail_bridge.py is the graph's only path to guardrails/.

GuardScope and refusal
Offline graph inputLocal and best-effort paths; returns block_message through audit_logger without a model call
Offline graph outputlocal_llm only; replaces answers below hallucination_threshold (0.18) or matching soul-leak markers
NeMo check()Wraps all four answer nodes (nemoguardrails==0.24.1); input refusal skips generation, output refusal replaces the answer
Broker fallbackMissing, failed, or unsupported live verdicts run deterministic input and soul-leak checks on every answer route; grounding stays local_llm only

Active rails are Python checks and add no model calls; NVIDIA's model-assisted self_check_* rails are inactive. NeMo failures audit guardrail_degraded. Verify an install with python -m pip check and python -m guardrails.verify_install (setup guide, package guide, NeMo reference, Track B record).

Numbat

CyClaw calls the external CLI pinned at 0.2.0 (schema 0.3.0); it never vendors or imports it.

PieceSwitchDefault and behavior
Streamnumbat.enabledOn. utils/numbat_emitter.py writes redacted audit/out-of-band events to logs/numbat-events.ndjsonl (rolls at 50 MiB); its bounded writer cannot hold requests
Pre-action hookpolicy.fallback.pre_action_hook.enabledOff. Prepared with engine: numbat and monitor-only rules in config/numbat/gate/; after consent, rules test --no-builtin-rules denies enforcing matches and every engine failure
CEL monitornumbat.cel.enabled, extra numbat-celOff. Two structured-field rules observe weak-retrieval cloud answers and hook/guardrail refusals after /query; never blocks
Offline scoringNoneOperator CLI and numbat-rules.yml; fixture, stream-contract, and CEL checks block CI

Nothing scores the live file during a request. The CLI and CEL extra are not in standard installs: keep their switches off until installed (an enabled hook without the binary denies every confirmed external call), trial rules before promoting any to enforce: true, and never use numbat hook as the command engine (it exits 0 on errors). Once enabled, /health reports hook and CEL readiness and /audit/summary shows pre_action_hook_last_verdict. Pre-action gate, stream, phase status, and the Track A acceptance record.

Telegram and OpenTweet

Both ship off and call loopback POST /query outside the core graph imports, reading credentials from the environment variable named in config. Telegram offers outbound notify or long-poll chat (no public webhooks), requires non-empty allowed_chat_ids, and can confirm one paid call only through the exact /online on <grok|claude> command with allow_hybrid_confirm on (default off); the triple gate still applies. OpenTweet forces user_confirmed_online: false, writes drafts, and refuses any answer whose model_used is not local (an online model or an offline best-effort reply to a vault miss, #1822); scheduled_date needs opentweet.schedule_enabled, and schedulers never send publish_now. Check either with python -m telegram.cli status / python -m opentweet.cli status. Telegram design and operations; OpenTweet design and operations.


Security Model

LayerMechanism
NetworkBinds 127.0.0.1:8787; request bodies capped at 1 MiB (security.max_request_body_bytes). A non-loopback api.host is refused except the documented auth + TLS path, or CYCLAW_ALLOW_NON_LOOPBACK_BIND (bind guard)
Endpoint trustLocal nodes: loopback or an exact host in models.local_llm.trusted_hosts (ships []). Online nodes: api.x.ai and api.anthropic.com only
Inputpolicy.prompt_filter: 40 banned_patterns, max_input_chars; same filter on MCP search
Rate limit60 req/min per IP, after same-origin rejection and before the filter; in-memory unless SQLite or Postgres is set
Proxy bypasshttpx clients set trust_env=False
TelemetryKill maps before any SDK import (invariant-guard G1), plus ONNX's post-import call; not a network firewall (SECURITY.md)
AuditHMAC-SHA256 query fingerprint + redacted metadata in logs/audit.jsonl, then the derived Numbat stream
Grok / ClaudeTriple gate item 5, then the opt-in deny-only pre-action hook
Soul writesHuman reason + enforced scan + atomic replace on POST /soul/apply only (What It Does item 4 lists the exceptions)
API keyFail closed: Bearer key, CSRF-guarded console cookie, or an admin login; the opt-in loopback bypass is peer-bound (API Key Setup)
GuardrailsOn by default, deny-only, deterministic on NeMo failure (NeMo Guardrails)
Optional surfacesConnectors, channels, and /memory/* ship off; /ops/* needs operator access and runs subprocess argv lists; no tokens in plist or task XML
/auth/*Present either way; 503 while auth is off. When on, /query needs a session or device token and refuses audit accounts; the last admin cannot be removed
ContainerNon-root, no-new-privileges, dropped caps, read-only rootfs; optional Falco (deploy/falco/) ships off
Dependency riskchromadb==1.5.9 carries CVE-2026-45829 and its HTTP-server siblings CVE-2026-45830/45831/45833, all accepted only for embedded PersistentClient. SECURITY.md
Commit/push gateWhen installed, tracked .githooks/ check secrets and private data at commit and push, protected-path edits at commit (reminder only at push), and protected-branch/ref rewrites (docs/GITHOOKS.md)

Full threat model: docs/THREAT_MODEL.md. Design notes: docs/security-philosophy/.


Project Structure

CyClaw/
├── gate.py  gate_ops.py  gate_auth.py  gate_memory.py   # gateway, /ops, /auth, /memory
├── graph.py                # 12-node LangGraph
├── metrics.py              # cyclaw-metrics: audit + spend + sequences
├── mcp_hybrid_server.py    # retrieval-only MCP
├── config.yaml             # tunables
├── retrieval/  llm/        # hybrid search, embeddings, rerank; local, Grok, Claude clients
├── utils/                  # sanitizer, logger, personality, spend, numbat_*, endpoint_trust, auth
├── guardrails/             # default-on rails, reached only via guardrail_bridge
├── memory/  agentic/  sync/  telegram/  opentweet/   # optional layers, off or CLI-only
├── macos/  powershell/  windows/                     # native installers and schedulers
├── spend/  schemas/  static/  tests/  docs/  deploy/
├── tools/lora_finetune/    # operator QLoRA kit, not a runtime extra
└── .github/workflows/

data/corpus/ is the sample corpus, data/personality/soul.md the live soul.


Documentation Map

Docs each section above links are not repeated here.

Read thisWhen you want
setup-guide.mdInstall paths, lock refresh, NeMo verification, and every REST call
locks/README.mdThe hashed lock families, who regenerates them, and the contract check
INVARIANTS.mdRules 1–9, code vs convention, and the test that pins each
CLAUDE.md / AGENTS.md / docs/GITHOOKS.mdRequest-path map, agent rules, and the commit/push security gate
docs/audits/2026-11-07-sandbox-consolidation.mdSandbox helper consolidation and #1797 closure criteria
.codex/README.mdCodex skill inventory, explicit-only tools, verification and trusted PR prompts
SECURITY.md / docs/THREAT_MODEL.mdEgress, accepted CVEs, disclosure; scope, bind exceptions, amendments
docs/AUTHENTICATION_DESIGN.md / docs/DOCKER.mdPer-user auth; GHCR image and compose hardening
docs/security-philosophy/Telemetry suppression, offline operation, and Numbat designs
macos/README.md / powershell/README.mdKeychain, Credential Manager, 401 recovery

License

Licensed under the MIT License.

Designed and built by Chris Grady, with AI tooling used under human review, CI, and the invariant guard.

Ver o original no GitHub

Bom para

Relacionados