siclaw

Siclaw

Read-only investigation copilot for SRE teams

Website | Documentation | Slack

Siclaw is an open-source AI agent for DevOps and SRE teams. It is built for read-only infrastructure diagnostics: gather evidence, form hypotheses, validate them, and return a clear root-cause analysis without changing your environment directly. Describe a problem in plain language and Siclaw investigates it from the terminal, the web UI, or your team's chat channels.

Deep investigation: diagnosing a CrashLoopBackOff in seconds

Features

• Deep Investigation — A 4-phase workflow for evidence gathering, hypothesis testing, and root-cause analysis
• Investigation Memory — Learns from past incidents to improve future investigations
• Read-Only by Default — Investigates and recommends next steps without changing your environment directly
• Team Workflows — Shared web UI, credentials, channels, triggers, and scheduled patrols
• Reusable Skills — Turn repeated diagnostic playbooks into reviewable runbooks
• Extensible — Connect external tools and data sources through MCP
• Multi-Channel Access — Use Siclaw from the terminal, web UI, or chat channels

Architecture

Three deployment modes share one agent core: TUI (single-user terminal), Local Server (Gateway + SQLite, multi-user), Kubernetes (isolated AgentBox pod per user). The Knowledge System feeds the agent with accumulated investigation experience (IM Phase 0–1 ✓) and team-wide knowledge via Qdrant (KR0 — in progress).

Prerequisites

• Node.js >= 22.12.0 — Download
• npm — Comes with Node.js
• kubectl — Optional, only needed if you want Siclaw to investigate Kubernetes clusters

Quick Start

Siclaw supports three deployment profiles. For local usage, start from a dedicated working directory because Siclaw stores most runtime data in .siclaw/ relative to where you launch it.

mkdir -p ~/siclaw-work
cd ~/siclaw-work

1. TUI Mode — Personal, local, lowest barrier

Run the agent directly in your terminal. No server, no database. All operations are read-only by default — safe to run on your workstation.

# Install globally
npm install -g siclaw

# Run (interactive — prompts for LLM provider on first launch)
siclaw

# Single-shot
siclaw --prompt "Why is pod nginx-abc in CrashLoopBackOff?"

# Continue last session
siclaw --continue

Build from source

git clone https://github.com/scitix/siclaw.git && cd siclaw
npm ci && npm run build:web && npm run build
npm link                 # register `siclaw` command globally

siclaw                   # TUI mode
siclaw --prompt "..."    # single-shot mode

# Uninstall: npm unlink siclaw -g

Tip: Any OpenAI-compatible endpoint works — swap baseUrl for DeepSeek, Qwen, Kimi, or a local Ollama server.

2. Local Server — VM or laptop, recommended for daily use

A lightweight web UI backed by SQLite. No MySQL, no Docker required.

npm install -g siclaw

# Start the server
siclaw local

# Open http://localhost:3000
# Login: admin / admin (default credentials)
# Configure providers in Models
# Import kubeconfigs in Credentials

Build from source

git clone https://github.com/scitix/siclaw.git && cd siclaw
npm ci && npm run build:web && npm run build
npm link                 # register `siclaw` command globally

siclaw local             # start local server

# Uninstall: npm unlink siclaw -g

On first startup, Siclaw creates a local admin account:

• Username: admin
• Password: admin

Set SICLAW_ADMIN_PASSWORD before first launch if you want a different bootstrap password.

3. Kubernetes — Team / enterprise

Production deployment uses Helm plus three container images: gateway, agentbox, and cron.

Build and push images if you are using your own registry:

make docker REGISTRY=registry.example.com/myteam TAG=latest
make push REGISTRY=registry.example.com/myteam TAG=latest

Then deploy the chart with a MySQL URL:

helm upgrade --install siclaw ./helm/siclaw \
  --namespace siclaw \
  --create-namespace \
  --set image.registry=registry.example.com/myteam \
  --set image.tag=latest \
  --set database.url="mysql://user:pass@host:3306/siclaw"

The default chart exposes the Gateway Service on service port 80 and NodePort 31000.

Configuration

TUI / CLI

• TUI reads .siclaw/config/settings.json
• The first-run wizard can generate this file for you
• Kubernetes credentials should be imported through /setup
• Investigation reports are written to ~/.siclaw/reports/

Minimal example:

{
  "providers": {
    "default": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-YOUR-KEY",
      "api": "openai-completions",
      "models": [{ "id": "gpt-4o", "name": "GPT-4o" }]
    }
  }
}

Local Server / Kubernetes

• Configure providers in the Models page
• Import kubeconfigs, API tokens, and SSH credentials in Credentials
• Configure Slack, Lark, Discord, and Telegram in Channels
• Create inbound webhook endpoints in Triggers
• Configure MCP servers in MCP Servers

Documentation

• Getting Started
• CLI & Local Server
• Kubernetes Deployment
• LLM Providers
• MCP Servers

Tech Stack

Layer	Technology
Runtime	Node.js 22+ (ESM-only)
Language	TypeScript 5.9
Agent	pi-coding-agent / claude-agent-sdk
Database (gateway)	MySQL or SQLite (via sql.js) + Drizzle ORM
Database (memory)	node:sqlite + FTS5 + bge-m3 embeddings
Frontend	React + Vite + Tailwind CSS
K8s Client	@kubernetes/client-node
MCP	@modelcontextprotocol/sdk
Realtime	WebSocket (ws)

Community

• Slack — Chat with the team and other users
• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions, ideas, and general discussion

Contributing

See CONTRIBUTING.md for development setup, architecture overview, and pull request guidelines.

Looking for a place to start? Check out issues labeled good first issue.

License

Apache License 2.0