# 🛡️ Armorer CLI

**Secure Installer for Agentic Applications**

Armorer is a security-focused CLI tool designed to install and configure AI agents (like OpenClaw) with appropriate sandboxing based on user intent.

## 🚀 Quick Start

### Installation

Ensure you have Python 3.10+ installed.

```bash
# Clone the repository
git clone <repo-url>
cd Armorer

# Install with pip (editable mode recommended for dev)
pip install -e .
```

## ✨ Key Features

-   **AI-Driven Security Interview**: Automatically determines risk profiles based on your use case.
-   **Credential Vault**: Store API keys once in your system keyring and auto-fill them for any agent installation.
-   **Skill Armory**: A centralized library of MCP (Model Context Protocol) servers that can be injected into any agent.
-   **Intelligent Launcher**: Automatic detection of CLI capabilities with guided startup menus.
-   **Chat-Owned OpenClaw Setup**: Install and configure OpenClaw from Armorer chat/TUI with continuous progress, Telegram API verification, optional Armory skill injection, and final `armorer run openclaw status` validation.
-   **Clean Uninstallation**: One-command cleanup of containers, volumes, and files.

## 🚀 Quick Start

### Installation

To run `armorer` directly from anywhere, install it as a tool using `uv`:

```bash
uv tool install .
```

Now you can simply run:
```bash
armorer configure
armorer chat
# then ask: install openclaw
armorer run openclaw
armorer-redteam run --target openclaw
```

### Standalone Red-Team Tool

Armorer now ships a separate pipeline-friendly evaluator CLI:

```bash
# end-to-end disposable flow: trigger -> scan -> red-team -> report -> cleanup
armorer-redteam run --target openclaw

# reuse an existing alias and keep it running
armorer-redteam run --target openclaw --existing-alias openclaw-main --preserve

# add external scanners with placeholders
armorer-redteam run --target openclaw \
  --external-tool "nmap -sV 127.0.0.1 -p 18789,18790" \
  --external-tool "bash security/check_egress.sh {install_dir}"
```

Reports are written to `reports/redteam/<run_id>/summary.json` and `summary.pdf`.

### Example Workflow

1.  **Launch**: Run `armorer`
2.  **Interview**: The AI Security Architect will determine a **Risk Profile**.
3.  **Install**: Armorer clones the repo and searches Docker Hub for the best official images.
4.  **Configure**: API keys are auto-filled from your **Credential Vault**.
5.  **Inject**: Add a skill from the **Armory** (e.g., `armorer inject openclaw brave-search`).
6.  **Run**: Launch the app with guided startup assistance.

### OpenClaw From Chat

You can also ask Armorer chat/TUI to complete OpenClaw setup end-to-end:

```bash
armorer chat
```

Then ask for `install openclaw` or `setup telegram for openclaw`. Armorer will keep setup inside chat, collect provider/model/API key/channel inputs, optionally inject Armory skills, show continuous progress, surface any retry cleanup it performs, verify Telegram bot/chat settings against the Telegram API when configured, reject mismatched provider/model prefixes before reporting success, confirm OpenClaw-native skill directories still exist on disk, and verify the final instance with `armorer run openclaw status` plus `armorer run openclaw doctor` when that health check is available. On Telegram, select/confirm setup steps can also be completed with inline buttons directly in the chat thread, and high-risk lifecycle confirmations can now also be approved or cancelled in-thread with plain `confirm` / `cancel` replies while `/confirm <token>` still works for explicit approval. Signal supports the same plain-text confirmation flow. In the Textual TUI, pending setup prompts accept `/cancel`, and the classic `armorer chat` fallback now exposes visible cancel choices for managed select prompts instead of depending on hidden terminal escape behavior. On retries, `skip` can reuse existing OpenClaw runtime settings and `clear` can remove stale Telegram allowlists, alert chat targets, injected Armory skills, or extra skill directories without leaving chat. If the default OpenClaw instance is already installed, the managed flow now reuses and reconfigures that existing instance instead of failing on the same alias. If the Textual UI is unavailable, the classic `armorer chat` fallback now supports the same managed setup flow instead of dropping back to manual OpenClaw-native onboarding.


## 🛠️ Development

- **Run Verification**: `PYTHONPATH=src pytest -q`
- **Source Code**: `src/armorer/`

## 🧠 Knowledge Base

Armorer ships with built-in domain knowledge that informs its autonomous debugging and deployment decisions. Knowledge files cover Docker best practices, troubleshooting patterns, security, networking, databases, Dockerfile patterns, ARM/multi-architecture support, healthchecks, and a structured error-to-fix dictionary.

### User-Contributed Knowledge
Drop custom `.md` files into `~/.armorer/knowledge/` to extend the knowledge base. These files are automatically loaded alongside the built-in topics.

### Learned Fixes
When Armorer successfully repairs a deployment, it saves the error pattern and fix to `~/.armorer/knowledge/learned_fixes.md` for future reference.

## 🔧 Agentic Debugging

Armorer's repair agent uses multiple tools autonomously:
-   **Shell & File I/O** — inspect containers, edit compose files, create missing configs
-   **Knowledge Base** — search and retrieve Docker best practices and error patterns
-   **Google Grounding Search** — research unfamiliar errors with cited web results
-   **Paginated Log Reader** — navigate error logs in batches instead of truncated snippets

## 📊 Langfuse Observability (Optional)

Trace every LLM call, tool invocation, and agent decision in [Langfuse](https://langfuse.com). Install the optional extras and configure via the CLI:

```bash
pip install armorer[langfuse]
armorer config  # → Configure Model/Provider/Langfuse
```

### 🦙 Ollama Support (Local LLMs)
Armorer supports local LLMs via Ollama. 
1. Run `armorer config`
2. Select **Change Model** -> **ollama**
3. Enter your model name (e.g., `llama3.2`) and local base URL.


See [docs/langfuse.md](docs/langfuse.md) for full setup details.
