# Armorer

Armorer is a Docker-first control plane for installing, configuring, running, and securing agentic applications such as OpenClaw.

It combines:
- a CLI for installs, runtime lifecycle, debugging, and automation
- a self-hosted web UI for day-to-day operations
- security controls around remote channels, approvals, runtime inspection, and agent guardrails

## Distribution

Armorer is distributed through three channels:

- GitHub Releases for release notes and downloadable artifacts
- GHCR container images for the full application runtime
- PyPI for the Python CLI and automation workflows

Recommended default:

- Full self-hosted app: use the container image from the latest GitHub Release
- Developer CLI: use `pipx install armorer`

## Install

```bash
pipx install armorer
```

Or:

```bash
pip install armorer
```

For local development in this repo:

```bash
git clone https://github.com/SecureNeural/Armorer.git
cd Armorer
pip install -e .
```

Armorer supports Python 3.10+.

## Quick Start

Configure your default model provider:

```bash
armorer config
```

Start or refresh the managed runtime:

```bash
armorer rebuild all --clean --prune
```

Open the UI:

```text
http://127.0.0.1:3000
```

The UI talks to the local Armorer API and managed Docker runtime. `rebuild all` is intended to refresh both Docker-managed and non-Docker Armorer components.

## Core Workflows

### Install an agent

```bash
armorer install openclaw --yes --skip-scan
```

Or use the UI:

1. Open `Discover`
2. Install OpenClaw
3. Armorer redirects to the installed agent detail page
4. Continue through the guided setup wizard

### Run an agent

```bash
armorer run openclaw
```

Or use the installed-agents page in the UI.

### Uninstall an agent

```bash
armorer uninstall openclaw
```

The UI also supports uninstall with confirmation and live progress.

## Web UI

The self-hosted UI includes:
- Overview dashboard with runtime, model, gateway, and security status
- Discover page for installable agents
- Installed agents directory and per-agent detail pages
- Guided OpenClaw setup
- Settings for model provider, Telegram, security, and advanced runtime configuration
- Jobs page for terminal output and background task progress
- Alerts and runtime events pages
- Chat UI with local history and OpenClaw session switching

## OpenClaw Setup

OpenClaw setup is managed by Armorer and happens in a guided wizard:

1. Model
2. Skills
3. Web search
4. Telegram
5. Apply setup
6. Pair Telegram if needed

Important behavior:
- Armorer mirrors OpenClaw’s discovered provider and model catalog
- OpenClaw gets its own Telegram bot token
- Armorer can reuse your Telegram identity for allowlists, but it should not reuse Armorer’s own bot token
- If Telegram is already authorized for that agent, pairing code entry is optional

## Telegram

Armorer supports a host-managed Telegram gateway.

Current behavior:
- Telegram bot tokens are verified before save
- token changes can trigger a guided restart flow
- remote Telegram tasks are signed and validated by Armorer core
- the UI can auto-discover your Telegram user/chat identity after you message the bot

Recommended setup:
- use one Telegram bot token for Armorer
- use a different Telegram bot token for each OpenClaw agent

If two runtimes poll the same bot token, Telegram will return `409 Conflict` and the bot will not behave reliably.

## Security

Armorer includes:
- remote task signing and verification
- confirmation/approval flows for sensitive actions
- LLM guard controls for input and output scanning
- alerting and proactive monitoring controls
- runtime and agent health inspection

The UI exposes the main security settings directly and keeps advanced controls in a separate section.

## Useful Commands

```bash
armorer
armorer config
armorer rebuild all --clean --prune
armorer install openclaw --yes --skip-scan
armorer run openclaw
armorer uninstall openclaw
armorer gateway telegram
armorer ui-api --host 127.0.0.1 --port 8788
armorer-redteam run --target openclaw
```

## Development

Run tests:

```bash
uv run pytest
```

Run the self-hosted UI build:

```bash
cd web/armorer-ui-selfhost
npm run build -- --webpack
```

Relevant areas of the codebase:
- CLI and lifecycle: `src/armorer/main.py`, `src/armorer/cli/`
- web API: `src/armorer/web/`
- OpenClaw integration: `src/armorer/apps/openclaw/`
- self-hosted UI: `web/armorer-ui-selfhost/`

## Releasing

Release automation lives in [`.github/workflows/release.yml`](.github/workflows/release.yml).

The release workflow publishes:
- a PyPI package
- a multi-arch GHCR container image
- a GitHub Release with Python and self-hosted UI artifacts

Detailed release steps are in [`docs/releasing.md`](docs/releasing.md).

## Notes

- Armorer is currently Docker-first for managed agent runtimes.
- The self-hosted UI build output such as `.next/` should remain untracked.
- If rebuilds start failing due to Docker disk pressure, use `armorer rebuild --prune` or standard Docker prune commands.
