Metadata-Version: 2.4
Name: armorer
Version: 0.1.9
Summary: A secure installer for agentic applications.
Project-URL: Homepage, https://github.com/SecureNeural/Armorer
Project-URL: Repository, https://github.com/SecureNeural/Armorer
Project-URL: Documentation, https://github.com/SecureNeural/Armorer#readme
Project-URL: Issues, https://github.com/SecureNeural/Armorer/issues
Author-email: Armorer Team <armorer@example.com>
License: MIT
License-File: LICENSE
Keywords: agentic,ai,installer,orchestration,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.3.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: cryptography>=44.0.3
Requires-Dist: docker>=7.1.0
Requires-Dist: fastapi>=0.135.1
Requires-Dist: google-genai>=0.1.0
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: keyring>=24.0.0
Requires-Dist: mkdocs-material>=9.5.0
Requires-Dist: mkdocs>=1.5.0
Requires-Dist: openai-agents>=0.9.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pytest>=8.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-telegram-bot>=22.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=1.10.0
Requires-Dist: reportlab>=4.2.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.82.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: websockets>=15.0.1
Provides-Extra: guard
Requires-Dist: armorer-guard>=0.1.1; extra == 'guard'
Description-Content-Type: text/markdown

# Armorer

Armorer turns agentic applications into managed, self-hosted runtimes, letting teams install, configure, monitor, and secure agents without hand-wiring Docker, credentials, channels, and guardrails.

Armorer is built for running tools like OpenClaw as real services: it owns setup, tracks background jobs, exposes a local operations UI, routes Telegram access, verifies runtime health, and applies security controls around credentials, approvals, and suspicious agent behavior.

> [!WARNING]
> Armorer is an active engineering preview for trusted local and self-hosted environments. Expect sharp edges around new agents, platform-specific Docker behavior, and early release packaging.

## Running Armorer

### Requirements

Armorer works best on machines that can run Docker-backed services and Python 3.10+.

Recommended local prerequisites:

- Python 3.10+
- Docker Desktop or Docker Engine
- `pipx` for isolated CLI installs
- optional: Telegram bot tokens for chat and alerting flows
- optional: Tailscale for private remote dashboard access

### Option 1. Ask Codex or Claude Code to set it up

Point your coding agent at this repository and ask it to run the setup for your machine:

> Set up Armorer from https://github.com/SecureNeural/Armorer on this machine.
> Follow the repository instructions and AGENTS.md. Install Armorer with Armorer
> Guard when supported, verify Docker, configure the local runtime, start the
> self-hosted UI, then help me install and configure OpenClaw through Armorer.
> Do not report success until the Armorer CLI works, the UI is reachable, and the
> runtime health checks pass.

The agent should use Armorer's own CLI and setup flows instead of ad hoc shell
commands whenever Armorer exposes a first-class command.

### Option 2. Install the CLI yourself

Install Armorer:

```bash
pipx install "armorer[guard]"
```

Or use `pip` directly:

```bash
pip install "armorer[guard]"
```

Configure the default model provider:

```bash
armorer config
```

Start or refresh the managed runtime:

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

Open the local UI:

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

If Armorer Guard is not available for your platform, install plain Armorer:

```bash
pipx install armorer
```

Armorer will still run with a basic built-in scanner.

### Option 3. Run from source

```bash
git clone https://github.com/SecureNeural/Armorer.git
cd Armorer
pip install -e ".[guard]"
armorer --help
```

For repo development, use `uv`:

```bash
uv run armorer --help
uv run pytest
```

## What Armorer Manages

Armorer combines a local control plane with a self-hosted web UI:

- agent install, run, stop, uninstall, and repair flows
- Docker-backed runtime lifecycle and job tracking
- guided OpenClaw setup for providers, models, skills, Telegram, and remote access
- a dashboard for runtime, model, gateway, security, jobs, alerts, and logs
- Telegram gateway setup for Armorer and managed agents
- credential capture and redaction flows
- guardrail settings, alerting, and proactive security controls
- release/E2E hooks for testing install and setup from scratch

## OpenClaw

Install OpenClaw through Armorer:

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

Run it:

```bash
armorer run openclaw
```

Or use the UI:

1. Open `Discover`.
2. Install OpenClaw.
3. Continue through the installed-agent setup wizard.
4. Pick provider, model, skills, Telegram, and access mode.
5. Apply setup and finish pairing if Telegram is enabled.

Armorer keeps OpenClaw setup inside the managed flow instead of dropping users into app-native onboarding unless they explicitly choose the native path.

## Security

Armorer includes security controls for agent operations:

- remote task signing and verification
- approval flows for sensitive actions
- credential redaction and capture handling
- input and output scanning
- alert routing over Telegram
- runtime and agent health inspection
- guard controls for steering, shutdown, restart, and scan actions

Armorer Guard is developed separately from this public repository. Public Armorer can use the private Guard binary/package when installed and falls back to a basic built-in scanner when it is not available.

Install the stronger binary scanner with:

```bash
pip install armorer-guard
```

## 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
```

Build the self-hosted UI:

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

Key areas:

- 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/`
- release pipeline: `docs/architecture/ci_release_pipeline.md`
- delivery spec: `specs/github_delivery_pipeline_spec.md`

## E2E Testing

Armorer includes a self-hosted E2E foundation for install/setup verification:

- workflow: [`.github/workflows/e2e-selfhosted.yml`](.github/workflows/e2e-selfhosted.yml)
- harness: [`scripts/e2e/run_armorer_stack.py`](scripts/e2e/run_armorer_stack.py)
- docs: [`docs/e2e_self_hosted.md`](docs/e2e_self_hosted.md)
- Windows runner guide: [`docs/windows_wsl_runner.md`](docs/windows_wsl_runner.md)
- strategy: [`docs/testing_strategy.md`](docs/testing_strategy.md)

The long-term goal is to run Armorer from scratch across multiple user-like environments before changes reach production.

## Symphony

This repository includes repo-side Symphony configuration so it can be driven by the upstream Symphony Elixir orchestrator for Linear-based issue execution.

See [`docs/symphony.md`](docs/symphony.md) for setup and run instructions.

## 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).

## License

See [`LICENSE`](LICENSE).
