# Clawgate

> Zero-trust capability proxy for AI agents. Scoped access to files, git, and tools via signed tokens. No mounts, no credentials, fully audited.

- **Type:** MCP server
- **Install:** `agentstack add mcp-m64github-clawgate`
- **Verified:** Pending review
- **Seller:** [M64GitHub](https://agentstack.voostack.com/s/m64github)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [M64GitHub](https://github.com/M64GitHub)
- **Source:** https://github.com/M64GitHub/clawgate
- **Website:** https://clawgate.io/

## Install

```sh
agentstack add mcp-m64github-clawgate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](LICENSE)
[](https://ziglang.org)
[](https://github.com/M64GitHub/clawgate/releases)
[](https://github.com/M64GitHub/clawgate/releases/latest)

# ClawGate

**ClawGate** is a secure capability proxy for isolated AI agents. It lets agents access files, run git commands, and invoke registered tools on your primary machine - all through cryptographically signed capability tokens with fine-grained, time-bounded, audited access control.

Think of it as **SSH keys meet JWT tokens meet capability-based security** - designed specifically for the AI agent era. Isolation without compromise.

## Why ClawGate

You're running [OpenClaw](https://github.com/openclaw/openclaw), Claude Code, or any AI agent on an isolated machine - a Mac Mini, a VPS, a container. Smart move. But now your agent needs access to your files, your repos, your tools. The usual approaches don't hold up:

| Approach | Risk |
|----------|------|
| NFS / SMB mount | Full filesystem access. Agent gets pwned → you get pwned |
| SSH + rsync | Credentials stored on agent machine. Same problem |
| Manual copy | Tedious. Breaks flow. Doesn't scale |
| Cloud sync | Your code on someone else's servers |

None of these assume the agent might be compromised. ClawGate does. Every operation is scoped to specific paths and tools, signed with Ed25519, encrypted end-to-end, time-bounded, revocable, and fully audited. The agent gets exactly what it needs - nothing more.

## Getting Started

### Requirements

- **Platforms:** Linux or macOS (uses Unix sockets for local IPC)
- **Build:** Zig 0.16+ (if building from source)

> **Note:** Windows is not currently supported. WSL2 works but is untested.

### Install

On both machines (your laptop and the agent machine):

```bash
curl -sSL https://clawgate.io/install.sh | sh
```

Or build from source:

```bash
git clone https://github.com/M64GitHub/clawgate && cd clawgate
zig build -Doptimize=ReleaseSafe
sudo cp zig-out/bin/clawgate /usr/local/bin/
```

### Setup

**Generate keys** (on your laptop):

```bash
clawgate keygen
# Creates ~/.clawgate/keys/secret.key and public.key
```

**Copy public key to agent machine:**

```bash
mkdir -p ~/.clawgate/keys                                    # on agent
scp ~/.clawgate/keys/public.key agent-machine:~/.clawgate/keys/  # from laptop
```

**Grant access** (on your laptop):

```bash
clawgate grant --read ~/projects --ttl 24h
# Or with git:  clawgate grant --git ~/projects --ttl 24h
# Or a tool:    clawgate grant --tool calc --ttl 4h
```

**Add the token** (on agent machine):

```bash
clawgate token add ""
```

**Start daemons:**

```bash
clawgate --mode agent                              # agent machine (start first)
clawgate --mode resource --connect :53280 # your laptop
```

Done. Your agent can now access exactly what you granted.

> **Detailed walkthroughs:** [OpenClaw Quick Setup](docs/OPENCLAW-QUICK-SETUP.md) (5 minutes) · [Custom Tools Guide](docs/TOOL-GUIDE.md)

## Agent Integration

### OpenClaw

ClawGate was built for [OpenClaw](https://github.com/openclaw/openclaw). Add the skill file - copy `skills/clawgate/SKILL.md` to your workspace, or paste it directly into a chat message (Telegram, WhatsApp). The agent learns the commands from it. **Done.**

```bash
# Your agent can now use:
clawgate cat ~/projects/app/src/main.zig
clawgate ls ~/projects/app/src/
clawgate write ~/projects/app/notes.md --content "TODO: refactor"
clawgate git ~/projects/app status
clawgate git ~/projects/app diff HEAD~3
clawgate tool remote-list                   # Discover available tools
clawgate tool calc                          # Invoke registered tools
echo "2+2" | clawgate tool calc             # With stdin
```

### Any Agent

ClawGate works with **any AI agent** that can call CLI commands (Claude Code, Cursor, etc.) or use **MCP** servers (Claude Code, Codex, etc.).

### Example Interaction

Resource daemon logs audit events (on private laptop)

Token list (on isolated agent)

## Capabilities

### File Operations

Read, write, list, and stat files on your primary machine. Large files (>512KB) are automatically truncated with metadata.

```bash
clawgate cat ~/projects/app/src/main.zig          # Read
clawgate cat --offset 1024 --length 512 large.log  # Chunked read
clawgate ls -l --depth 2 ~/projects/app/           # List
clawgate stat --json ~/projects/app/config.toml    # File info
clawgate write ~/projects/notes.md --content "..."  # Write
clawgate write --append ~/projects/log.md --content "..."  # Append
```

### Git Operations

Run git commands on repositories hosted on your primary machine with three permission tiers:

| Tier | Grant Flag | Allows |
|------|-----------|--------|
| **Read-only** | `--git` | status, diff, log, show, blame, branch (list), ... |
| **Write** | `--git-write` | add, commit, checkout, merge, rebase, reset, ... |
| **Full** | `--git-full` | push, pull, fetch, remote add/remove, submodule |

```bash
clawgate grant --git ~/projects/** --ttl 24h

clawgate git ~/projects/myapp status
clawgate git ~/projects/myapp log --oneline -20
clawgate git ~/projects/myapp diff HEAD~3
```

> **Scope tip:** `--git` also enables file read/list/stat. Use `~/projects/myapp/**` if you want to browse files inside the repo with `clawgate cat` or `clawgate ls`. For git-only access, the exact repo path is sufficient: `~/projects/myapp`.

Git commands run through allowlists with blocked flags (`-c`, `--exec-path`, `--git-dir`, `--work-tree`) to prevent scope escapes. See the [Design Document](docs/DESIGN.md) for the full specification.

### Custom Tools

Proxy **any command-line tool** through ClawGate's secure pipeline. Tools are registered on the resource machine - the agent can only invoke what has been explicitly registered and granted.

```bash
# Register a pure stdin/stdout tool (no filesystem access)
clawgate tool register calc \
  --command "bc -l" \
  --allow-args "-q" \
  --timeout 10 \
  --description "Calculator (bc)" \
  --example 'echo "2+2" | clawgate tool calc'

# Register a tool that accesses files (scope required)
clawgate tool register rg \
  --command "rg" \
  --scope "projects/webapp" \
  --timeout 30 \
  --description "Ripgrep search"

# Grant and use (agent side)
clawgate grant --tool calc --ttl 4h
echo "2+2" | clawgate tool calc
```

Each tool has **three layers of argument security**:

| Layer | Protection |
|-------|------------|
| **Flag validation** | Allowlist or denylist mode for command flags |
| **Path scoping** | Path arguments validated against `--scope` |
| **CWD confinement** | Subprocess runs with CWD set to `$HOME` |

Tools that access the filesystem **must** have a `--scope`. Tools without a scope (like `calc`) block all path-like arguments. Commands are executed via direct argv - never through a shell. No shell expansion, no pipes, no semicolons. Output is truncated at the configured limit.

```bash
clawgate tool ls                     # List registered tools
clawgate tool info calc              # Show tool details
clawgate tool update calc --timeout 30
clawgate tool remove calc
clawgate tool test calc -q           # Test locally (no daemon needed)
clawgate tool remote-list            # Discover tools via daemon
```

### Token Revocation

Revoke tokens before they expire. The revocation list lives on the resource machine and is checked on every incoming request - a revoked token is a dead credential, even if the agent still holds it.

```bash
clawgate revoke cg_a1b2c3... --reason "compromised"
clawgate revoke --all --reason "key rotation"
clawgate revoked ls                  # List revoked tokens
clawgate revoked clean               # Remove expired entries
```

### Skill Generation

ClawGate auto-generates markdown skill files from the tool registry, making registered tools discoverable by AI agents:

```bash
clawgate skills generate             # Generate to skills/clawgate/
clawgate skills export /path/to/dir  # Export to custom directory
```

Tool management commands (`register`, `update`, `remove`) automatically regenerate skill files after modifying the registry.

## How It Works

### Capability Tokens

When you run `clawgate grant`, you create a **capability token** - a JWT signed with Ed25519:

```json
{
  "iss": "clawgate:resource:mario-laptop",
  "sub": "clawgate:agent:mario-minipc",
  "exp": 1706832000,
  "cg": {
    "cap": [
      {
        "r": "files",
        "o": ["read", "list", "stat", "git"],
        "s": "/home/mario/projects/**"
      },
      {
        "r": "tools",
        "o": ["invoke"],
        "s": "calc"
      }
    ]
  }
}
```

This token says: *"The agent on mario-minipc can read, list, and stat files, run read-only git commands under `/home/mario/projects/`, and invoke the `calc` tool - until the expiry time."*

Tokens are **self-contained** - the resource daemon validates the signature and checks permissions without any database lookup.

### Scope Patterns

```bash
clawgate grant --read /home/mario/file.txt         # Exact file
clawgate grant --read /home/mario/projects/*       # Direct children only
clawgate grant --read /home/mario/projects/**      # Recursive (all descendants)
clawgate grant --read /home/mario/projects/*.zig   # Glob pattern
clawgate grant --git /home/mario/projects/**       # Git read-only + file read
clawgate grant --git-write /home/mario/projects/** # Git read+write
clawgate grant --git-full /home/mario/projects/**  # Git full (+ push/pull)
clawgate grant --tool calc                         # Single tool
clawgate grant --tools-all --ttl 4h                # All registered tools
clawgate grant --read --tool calc /home/mario/**   # Files + tool combined
```

### Audit Trail

Every operation is logged persistently to `~/.clawgate/logs/audit.log` on the resource machine:

```
2026-02-07T14:30:45Z AUDIT req=req_1384782a op=git path=/home/m64/space/ai/clawgate success=true
2026-02-07T14:30:46Z AUDIT req=req_79565e1c op=read path=/etc/shadow success=false error=SCOPE_VIOLATION
```

Denied operations that never reach the resource daemon fail immediately on the agent side:

```
> clawgate ls /etc/hosts
Error: No token grants list access to /etc/hosts
```

### Architecture

ClawGate is split into two cooperating sides: the **resource side** (your laptop) and the **agent side** (the isolated machine).

**Resource Side (your laptop)**

- **Resource Daemon** - Verifies token signatures, checks revocation list, enforces scope and permissions, executes file/git/tool operations, writes audit events
- **Tool Registry** (`~/.clawgate/tools.json`) - Tool configurations, argument validation rules, execution limits
- **Protected Resources** - Your local files and repos, never mounted or shared directly, only accessed via validated requests

**Agent Side (isolated machine)**

- **Agent Daemon** - Stores capability tokens, proxies requests to the resource daemon, exposes a local IPC interface (Unix socket)
- **AI Agent** - Any AI system (OpenClaw, Claude Code, Cursor, etc.), talks only to the local agent daemon, never has direct filesystem access
- **MCP Server** (optional) - Runs over stdio, connects to the agent daemon via Unix socket, exposes `clawgate_read_file`, `clawgate_git`, `clawgate_tool`, and more

The resource daemon connects to the agent daemon over TCP (`:53280`). All requests pass through this single encrypted channel. The resource daemon is the only component that touches the filesystem and executes tools.

## Features

| Feature | Description |
|---------|-------------|
| **Fine-grained access** | Grant specific paths and tools, not "everything" |
| **Custom tool proxy** | Register any CLI tool with path scoping, argument validation, CWD confinement |
| **Git operations** | Three-tier git access: read-only, write, full (push/pull) |
| **Token revocation** | Revoke tokens before expiry, resource-side enforcement |
| **Time-bounded tokens** | 1h, 24h, 7d - you choose |
| **Persistent audit trail** | Every operation logged to `~/.clawgate/logs/audit.log` |
| **Issuance tracking** | Every granted token recorded for audit and bulk revocation |
| **Tool discovery** | Agent can list available tools via daemon |
| **Skill generation** | Auto-generated agent-readable docs from tool registry |
| **Large file handling** | Files >512KB automatically truncated with metadata |
| 🦞 **OpenClaw native** | Skill file included |
| **Fast** | Pure Zig, zero dependencies, minimal latency |
| **Defense-in-depth security** | 16 layers - see [Security](#security) below |

## Security

ClawGate is a security tool. We take this seriously.

### Threat Model

**Assumed threat:** The agent machine is compromised (e.g., via prompt injection). The attacker has full control of the agent process and any tokens stored there.

**Defense layers:**

| Layer | Protection |
|-------|------------|
| **Transport** | X25519 key exchange + XChaCha20-Poly1305 encryption |
| **Forward secrecy** | Fresh ephemeral keys per session |
| **Authentication** | Ed25519 signed tokens |
| **Authorization** | Per-request scope validation |
| **Revocation** | Resource-side revocation list, checked every request |
| **Path safety** | Canonicalization, traversal protection |
| **Git allowlists** | Tiered command allowlists, blocked flags (`-c`, `--exec`) |
| **Argument validation** | Per-tool allowlist/denylist for command flags |
| **Tool path scoping** | Path arguments validated against per-tool scope |
| **CWD confinement** | Tool subprocesses execute with CWD = `$HOME` |
| **No shell execution** | Tools run via direct argv, no shell interpolation |
| **Output limits** | Per-tool configurable output truncation |
| **Symlink rejection** | All symlinks unconditionally rejected |
| **Forbidden paths** | ~/.ssh, ~/.aws, ~/.gnupg - hardcoded, ungrantable |
| **Time limits** | Tokens expire, limiting blast radius |
| **Audit** | Every operation logged locally |

### Security Practices

- **Security audit every development phase** - We don't ship without review
- **Output size limits** - File reads, git output, and tool output capped and truncated
- **Zero dependencies** - Zig stdlib only, no supply chain risk

### Reporting Vulnerabilities

Found a security issue? Email security@clawgate.io (or open a private advisory on GitHub). See [SECURITY.md](SECURITY.md) for our full security policy.

## CLI Reference

```
ClawGate - Secure capability proxy for isolated AI agents

Usage:
  clawgate --mode agent             Run agent daemon (listens for connections)
  clawgate --mode resource          Run resource daemon (connects to agent)
  clawgate mcp-server               Run MCP server (stdio)

Capability Management (primary machine):
  clawgate grant [opts] [path]      Grant access (path optional for tool-only)
    --read                          Allow read operations
    --write                         Allow write operations
    --git                           Git read-only (+ read, list, stat)
    --git-write                     Git read+write (+ file write)
    --git-full                      Git full access (+ push/pull/fetch)
    --tool                    Grant access to a registered tool
    --tools-all                     Grant access to all registered tools
    --ttl                 Token lifetime (2h, 24h, 7d)
  clawgate keygen                   Generate Ed25519 keypair

Token Revocation (primary machine):
  clawgate revoke               Revoke a token by ID
  clawgate revoke --all             Revoke all issued tokens
    --reason                  Revocation reason
  clawgate revoked ls               List revoked tokens
  clawgate revoked clean            Remove expired entries

Tool Registry (primary machine):
  clawgate tool register      Register a new tool
    --scope                  Semicolon-separated scope (relative to $HOME)
  clawgate tool ls                  List registered tools
  clawgate tool info          Show tool details
  clawgate tool update        Update tool configuration
  clawgate tool remove        Remove a tool
  clawga

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [M64GitHub](https://github.com/M64GitHub)
- **Source:** [M64GitHub/clawgate](https://github.com/M64GitHub/clawgate)
- **License:** MIT
- **Homepage:** https://clawgate.io/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-m64github-clawgate
- Seller: https://agentstack.voostack.com/s/m64github
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.