DOCSEARCHbyAlgolia
Submit Docs

Netclaw Documentation

repository·dev·Indexed 41 days ago

https://github.com/netclaw-dev/netclaw

An open-source, self-hosted autonomous operations agent built on Akka.NET. Netclaw consists of a core daemon (Netclaw.Daemon) and a TUI/CLI client (Netclaw.Cli) designed for secure AI agent execution on infrastructure ranging from Raspberry Pi to Cloud VMs. The documentation includes architectural overviews, UI design principles for the Operations Console, and a comprehensive behavioral evaluation suite for testing identity, memory pipelines, and tool-use autonomy.

Tokens
227.9K
Snippets
322
Records
971
Agent score
48%

What's inside Netclaw

  1. Overview of the netclaw-discord-socket specification

    dev

    The netclaw-discord-socket specification defines how Netclaw supports Discord as a first-class chat ingress/egress transport. It aims to provide operational parity to Slack Socket Mode by implementing a Discord gateway adapter.

    Key capabilities include:

    • Connection Management: Defines the gateway adapter's connection lifecycle and health reporting.
    • Event Normalization: Converts inbound Discord events into SendUserMessage format with deterministic thread-aware session identity.
    • Security: Implements ACL-gated dispatch for inbound messages.
    • Reply Targeting: Ensures replies are correctly targeted back to the originating Discord context.
    • Command Compatibility: Supports text-first slash command compatibility without requiring explicit Discord app-command registration.
    • Interactive Approvals: Handles interactive tool-approval by preferring Discord interaction controls while maintaining a deterministic text fallback.
    • Proactive Communication: Supports agent-initiated proactive Discord channel posts and ensures proactive threads are wired into the actor hierarchy and conform to thread-history-backfill.

  2. What is Netclaw?

    dev

    Netclaw is an always-on autonomous operations agent designed to run on various environments, from Raspberry Pis to cloud VMs. It is a single-process .NET 10 application built on Akka.Agents that functions as an autonomous operations platform rather than just a chat assistant. It can monitor environments, react to issues, investigate, delegate work, and manage its own schedule, primarily interacting with users via Slack.

    Key characteristics include:

    • Simplicity: Minimal moving parts and a small configuration footprint.
    • Security: Built-in audience disposition systems and approval gates with a default-deny, fail-closed posture.
    • Reliability: Uses curated skill feeds, persistent memory, and background tasks, optimized to work with small models (Qwen 3.5 9B and up).

  3. Overview of the netclaw-scheduling specification

    dev
    The netclaw-scheduling specification defines the framework for chat-driven scheduled task creation and management. It enables Netclaw to autonomously manage its own schedule through conversation, ensuring tasks are persisted, executed in isolation using Akka timers, and reported back with built-in failure handling and guardrails.

  7. Overview of the Netclaw CLI surface area

    dev

    The Netclaw CLI provides several key tools for managing the Netclaw environment:

    • netclaw init: A wizard for initial setup.
    • netclaw doctor: A diagnostic tool to check the health and configuration of your Netclaw installation.
    • netclaw config: The interface for managing settings.
    • netclaw approvals: A command used to manage persistent tool approvals.

  8. Overview of the netclaw-mcp Specification

    dev
    The netclaw-mcp specification defines the requirements for integrating Model Context Protocol (MCP) servers with Netclaw. It focuses on four primary areas: integration, validation, policy enforcement, and diagnostics. This ensures that MCP servers are correctly configured, securely invoked, and observable within the Netclaw ecosystem.

  9. Explore Netclaw UI Mockups and Design Artifacts

    dev

    The docs/ui/ directory contains planning artifacts for the Netclaw management interfaces, including page architectures, wireframes, and high-fidelity mockups. These files serve as the blueprint for the Operations Console and the Terminal User Interface (TUI).

    Key artifacts include:

    • Operations Console Mockups: Found in UI-001-ops-console-mockup.md, covering page architecture, wireframes, and component behavior.
    • Terminal TUI Wireframes: Found in TUI-001-command-wireframes.md, detailing the TUI experience for netclaw init, netclaw chat, and standard CLI commands.
    • High-Fidelity Visuals: ops-console-v1.html provides a static mockup for visual direction.

  10. What the Netclaw Eval Suite tests

    dev

    The Netclaw Eval Suite validates agent behavior by running prompts via netclaw chat -p against an eval container. It verifies two types of evidence:

    1. stdout output: Checks for tool calls ([tool:call]), specific text content, or the absence of hallucinations.
    2. daemon log patterns: Monitors the daemon's file log (located at $EVAL_HOME/logs/daemon-$(date +%F).log) for structured patterns such as:
      • turn_skill_auto_load
      • turn_memory_recall
      • turn_memory_checkpoint_enqueued

    Test Categories

    CategoryWhat It Validates
    Identity & Self-AwarenessKnowledge of name, version, repo, and session ID via identity files.
    Skill Discovery & ActivationLoading relevant skills (file, feed, MCP) while skipping unrelated ones.
    Memory PipelineMemory recall, identity-vs-memory routing, explicit saves, and automatic checkpointing.
    Tool Discovery & UseProgressive discovery, workspace selection, web search, and webhook configuration.
    Grounding & AlignmentFact verification via tools and resolving attachment paths from the session root.
    Autonomy & ExecutionExecuting tasks rather than just describing them.
    SubagentsDelegation via spawn_agent, preserving guidance, and project declaration.
    Coding ContextSwitching between worktrees/branches and verifying Git grounding.
    Complex Task ExecutionMulti-step tool chains and handling bounded tool output.
    Multi-Turn ConversationSession resume and speaker attribution recall.

  11. Overview of the netclaw-input-adapters specification

    dev

    The netclaw-input-adapters specification defines the standard for how inbound channel adapters interact with the Netclaw system. Its primary goals are to ensure that adapters:

    1. Construct trusted inputs: Provide data that the system can verify.
    2. Preserve channel capabilities and provenance: Maintain information about where the input originated and what the source channel is capable of.
    3. Resolve message audience: Correctly identify who the intended recipients of a message are.

  12. What is a local-control proof?

    dev

    A local-control proof is a versioned, ephemeral capability that grants a single daemon-host operation to a process that has access to the Netclaw key ring. It is designed to allow a host CLI to securely interact with a daemon to initiate sensitive operations, such as generating pairing codes, without exposing long-lived credentials.

    Key characteristics include:

    • Single-use: Once a proof is used to validate an operation, it cannot be reused.
    • Strict bounds: The proof is limited to a specific operation and a specific lifetime.
    • Ephemeral: The proof itself is short-lived and created on a call-local basis.