MetallicClaw

A tiny C-native agent runtime for edge machines and local automation.

MetallicClaw is a small C-native agent runtime for edge machines and local automation.

It gives a networked Linux or macOS box the agent pieces that usually require a much heavier stack: OpenAI-compatible model calls, skills, MCP, filesystem tools, a local gateway, session history, safety policy, cancellation, rollback journals, and benchmarkable runtime overhead.

The current optimized binary is under 100 KB on macOS arm64, excluding system libraries.

Why

Most agent frameworks assume Python, Node, a web app, a database, and a pile of runtime services. MetallicClaw tries the opposite shape:

• one C binary
• JSON config
• JSONL sessions
• Markdown skills
• editable SOUL.md personality
• bounded MEMORY.md and USER.md
• local files for state
• OpenAI-compatible API for reasoning
• explicit policy around dangerous tools

The model can be slow or expensive. The agent runtime should not be.

What Works Today

Area	Status
Provider	OpenAI-compatible chat completions over libcurl
Agent loop	Multi-turn sessions, model tool calls, selected skill injection
Skills	Discovers Markdown SKILL.md files from local skill directories
MCP	Stdio bridge for listing and calling MCP server tools
Tools	Filesystem read/write/search/list, shell execution, web search, skills, memory, MCP, rollback
Safety	Policy-gated dangerous tools, TLS verification, timeouts, cancellation
State	JSON config, JSONL session logs, bounded memory files, rollback journals, no database
Gateway	Local HTTP gateway for version, health, skills, and agent calls
Images	Basic image input through CLI, gateway, and Telegram photos
Telegram	Long-polling Telegram bridge with visible command menu, images, and YOLO toggle
Bench	Startup/runtime overhead and stress loops for local performance checks

Status

MetallicClaw is early software. It is useful as a working kernel, research prototype, and edge-agent experiment. It is not yet a full remote automation platform.

Current strengths:

• tiny C runtime with fast startup
• OpenAI-compatible chat completions
• multi-tool calling
• skill discovery from skills/**/SKILL.md
• MCP stdio bridge
• local HTTP gateway
• basic vision input for image-capable OpenAI-compatible models
• provider retries, TLS checks, and circuit breaker
• policy-gated dangerous tools
• rollbackable write_file
• cancellation for running sessions
• stress benchmark command

Known limits:

• gateway exposes a small project-specific HTTP API
• no streaming tokens yet
• rollback only covers write_file
• image bytes are sent for the current turn only; session logs store an [image attached] marker instead of replaying image data later
• JSON parsing is intentionally small and should be replaced before hostile internet exposure
• MCP servers are launched per request rather than pooled

Install

Install the latest binary with:

curl -fsSL https://raw.githubusercontent.com/sethupavan12/MetallicClaw/main/install.sh | sh

The installer downloads a release archive, verifies the .sha256 file, and installs metallicclaw to $HOME/.local/bin by default.

After install, update in place with:

metallicclaw update

Manual release archives are named by target:

metallicclaw-darwin-arm64.tar.gz
metallicclaw-linux-x86_64-gnu.tar.gz

See docs/INSTALL.md for custom install directories, version pinning, manual downloads, Homebrew tap setup, and uninstall steps.

Install From Source

Dependencies:

• C compiler with C11 support
• make
• pkg-config
• libcurl
• bash, python3, and curl for the test suite

macOS:

brew install curl pkg-config
make

Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libcurl4-openssl-dev curl python3
make

Run tests:

make test

The test suite includes a compiled C unit runner with hundreds of checks for JSON handling, profile setup, skills, sessions, tools, rollback, policy, cancellation, and benchmarks, plus shell integration tests for CLI, provider, MCP, gateway, timeout, and recovery behavior.

Install locally:

make install PREFIX="$HOME/.local"

Binary Releases

Release assets include stable aliases for installers and versioned archives for manual pinning:

metallicclaw-darwin-arm64.tar.gz
metallicclaw-linux-x86_64-gnu.tar.gz
metallicclaw-v0.4.1-darwin-arm64.tar.gz
metallicclaw-v0.4.1-linux-x86_64-gnu.tar.gz

The Linux GNU binary is dynamically linked and expects glibc plus libcurl at runtime. Build from source if you need a different libc, architecture, or distribution baseline.

Quick Start

./build/metallicclaw init
./build/metallicclaw doctor
export OPENAI_API_KEY='...'
./build/metallicclaw doctor
./build/metallicclaw chat --session main

One-shot agent call:

./build/metallicclaw agent --session main --message "read README.md and summarize it"

Basic image input:

./build/metallicclaw agent --session vision \
  --message "describe this image" \
  --image-url "data:image/jpeg;base64,..."

Show a readable session transcript:

./build/metallicclaw sessions show --session main

Run the gateway:

./build/metallicclaw gateway --host 127.0.0.1 --port 18789
curl http://127.0.0.1:18789/version
curl http://127.0.0.1:18789/health

Run the benchmark:

./build/metallicclaw bench --runs 50
./build/metallicclaw bench --stress --runs 100000

Core Commands

metallicclaw init [--profile NAME]
metallicclaw doctor [--json]
metallicclaw chat [--session ID] [--skill NAME]
metallicclaw agent [--session ID] [--skill NAME] [--image-url URL] --message TEXT
metallicclaw cancel --session ID
metallicclaw update [--version VERSION] [--install-dir DIR]
metallicclaw skills list
metallicclaw skills view NAME
metallicclaw tools call NAME JSON_ARGS
metallicclaw sessions show [--session ID]
metallicclaw sessions clear [--session ID]
metallicclaw sessions search TEXT
metallicclaw bench [--runs N] [--stress]
metallicclaw gateway [--host 127.0.0.1] [--port 18789]
metallicclaw telegram [setup|list|run NAME|chats NAME|unlink NAME]

Configuration

metallicclaw init creates a profile under ~/.metallicclaw by default. Set METALLICCLAW_HOME to use another directory.

The profile includes SOUL.md, an editable personality file injected into the agent prompt. Use it for voice and behavior preferences. It cannot override runtime safety rules, provider policy, or tool policy.

Example config.json:

{
  "provider": "openai-compatible",
  "model": "gpt-4.1-mini",
  "base_url": "https://api.openai.com/v1/chat/completions",
  "api_key_env": "OPENAI_API_KEY",
  "max_retries": 1,
  "connect_timeout_ms": 10000,
  "request_timeout_ms": 120000,
  "tls_verify": true,
  "allow_plain_http": false,
  "tool_policy": "allow",
  "circuit_failure_threshold": 5,
  "circuit_cooldown_ms": 30000
}

See docs/CONFIGURATION.md.

Skills

Skills are folders containing SKILL.md files:

skills/my-skill/SKILL.md

The scanner reads YAML frontmatter fields such as name, description, and platforms, then injects a selected skill into the agent prompt.

metallicclaw init seeds practical defaults: filesystem, shell, project, mcp, debugging, and godmode. They are normal profile skills and can be edited or replaced.

./build/metallicclaw skills list
./build/metallicclaw chat --skill hello

See docs/SKILLS.md and examples/skills/hello.

Tools And Safety

Built-in tools:

• read_file
• write_file
• search_files
• list_dir
• shell_exec
• web_search
• skills_list
• skill_view
• memory
• mcp_list_tools
• mcp_call_tool
• rollback_transaction

Dangerous tools can be gated:

{
  "tool_policy": "ask"
}

With ask, dangerous tools require METALLICCLAW_APPROVE_ALL=1 or METALLICCLAW_APPROVE_<TOOL_NAME>=1.

See docs/SECURITY_MODEL.md.

MCP

Create ~/.metallicclaw/mcp.json:

{
  "servers": [
    {
      "name": "example",
      "command": "python3 '/absolute/path/to/MetallicClaw/examples/mcp/echo_server.py'",
      "timeout_ms": 30000
    }
  ]
}

Then call:

./build/metallicclaw tools call mcp_list_tools '{"server":"example"}'
./build/metallicclaw tools call mcp_call_tool '{"server":"example","name":"tool_name","arguments":{}}'

See docs/MCP.md.

Documentation

• Architecture
• Getting started
• Tutorials
• Examples
• Command guide
• CLI reference
• Configuration
• Security model
• Skills
• Memory
• Web search
• MCP
• Gateway
• Benchmarking
• Edge deployment
• Troubleshooting
• Release process
• Roadmap
• Vision

Open Source

MetallicClaw is MIT licensed. See LICENSE.

Read CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md before opening issues or pull requests.