# Usage Guide

## 1. Configure Providers

Before installing agents, you must configure your AI providers. Armorer stores your API keys securely in your system's keychain.

```bash
armorer configure
```

-   **Interactive Prompts**: You will be asked to select a provider (OpenAI, Anthropic, etc.) and enter your API Key.
-   **Security**: Keys are **never** stored in plain text.

## 2. Install an Agent

Use the `install` command to securely set up an agent.

```bash
armorer install openclaw
```

For OpenClaw first-run setup, prefer `armorer chat` or the Textual TUI and ask for `install openclaw`. That managed flow keeps provider/model/API key/channel setup, retry cleanup, Telegram verification, and final `armorer run openclaw status` validation inside Armorer instead of dropping you into the native onboarding shell.

### The Security Interview
Armorer's **AI Security Architect** will interview you to determine the risk profile:

1.  **Vulnerability Scan**: First, the codebase is scanned for security risks (RCE, unsafe code).
2.  **Interview**: The AI asks about your use case (e.g., "Do you need file access?").
3.  **Profile Selection**:
    -   `SANDBOXED`: No network, no file access.
    -   `SCOPED_READ`/`SCOPED_WRITE`: Access to specific folders only.
    -   `HIGH_RISK`: Full access (Discouraged).

## 3. Run the Agent

Start an installed agent with the `run` command:

```bash
armorer run openclaw
```

### Interactive Mode & Agent Guidance
If the application is a CLI tool, Armorer will ask how you want to run it:
-   **Background**: Runs silently as a server (ideal for persistent gateways).
-   **Interactive CLI**: Drops you directly into the application's shell.

**Agent Guidance**: If you run a CLI app without arguments, Armorer's AI Agent will analyze the help text and offer a menu of common startup commands (e.g., "Run Setup Wizard").

You can also pass arguments directly when you intentionally want a native app command:
```bash
armorer run openclaw -- onboard
```

For OpenClaw first-run setup, prefer the managed chat/TUI flow below. That path keeps provider/model/API key/channel collection, retry cleanup, and final verification inside Armorer instead of dropping into the native onboarding shell.

## 4. Uninstalling

To remove an agent, its containers, volumes, and files:

```bash
armorer uninstall openclaw
```

This ensures a clean system state by cleaning up Docker resources and local directories.

## 5. Secure Chat & Oversight

Armorer includes a powerful conversational interface that allows you to interact with the **Armorer Core** (the background security service).

```bash
armorer chat
```

Through this chat, you can:
-   **Audit History**: "Check openclaw's history for leaked keys."
-   **Manage Metadata**: "I moved my logs to .hidden_logs, please monitor that folder."
-   **Perform Redactions**: If Armorer finds a secret, it will prompt you via an interactive menu to redact it.
-   **Install OpenClaw End-to-End**: Ask `install openclaw` or `setup telegram for openclaw` and Armorer will keep the flow inside chat, collecting provider/model/API key/channel inputs, surfacing retry cleanup, verifying Telegram bot/chat settings against the Telegram API when configured, rejecting mismatched provider/model prefixes, confirming OpenClaw-native skill directories still exist, and verifying 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 in the chat thread, and high-risk lifecycle confirmations can 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 fallback chat exposes visible cancel choices for selection prompts.

### OpenClaw Chat Setup
For OpenClaw specifically, `armorer chat` and the Textual TUI now own the first-run setup flow:

-   Armorer asks for provider, model, API key, Telegram channel details, and skill scan paths directly in chat.
-   Provider/model choices are written into OpenClaw-native runtime config (`.openclaw/openclaw.json`), and provider auth is synced into the install-local env files (`.env` and `.openclaw/.env`) so the final instance does not depend on a follow-up native onboarding pass.
-   Armorer can also inject Armory skills directly into OpenClaw during setup, so MCP-style skills are configured in the final instance rather than only discovered later.
-   OpenClaw-native skill directories are written into `skills.load.extraDirs`, so chat-collected scan paths reach the OpenClaw runtime instead of stopping at Armorer-only state.
-   Progress is streamed through the status bar while install/setup commands run.
-   If a queue job stalls or is superseded by a retry, Armorer surfaces the last visible progress, cleans up or supersedes stale task files, and makes that cleanup visible in chat/TUI instead of leaving the session stuck.
-   Skip-based retries can reuse an existing OpenClaw runtime by reading previously written settings from both the install root `.env` and `.openclaw/.env`, so a partially configured instance does not need to be re-onboarded manually.
-   Retry prompts also support `clear` for optional OpenClaw settings, so chat/TUI can remove stale Telegram allowlists, alert chat targets, injected Armory skills, and extra skill directories instead of only reusing them.
-   If the default OpenClaw alias already exists, the managed flow reuses and reconfigures that registered instance instead of trying to reinstall on the same alias and failing.
-   Fresh installs fail early if provider, model, or required remote-provider API keys are still missing, instead of reporting a successful install with unusable runtime config.
-   Telegram bot/chat configuration, default model selection, provider/model prefix consistency, provider auth sync, and OpenClaw skill directories are verified after setup instead of only being stored in Armorer config.
-   When the registered OpenClaw runtime advertises a health-check shortcut, Armorer runs `armorer run openclaw doctor` after `status` so dead provider credentials or broken model endpoints surface before setup is declared healthy.
-   If Textual is unavailable, the classic CLI chat fallback still understands the same structured setup prompts, so the managed OpenClaw flow stays inside Armorer instead of falling back to manual OpenClaw-native onboarding.

### Sandbox Mode (Optional)
By default, the CLI runs on your host machine for speed. To run the CLI itself inside a Docker container for maximum isolation ("Inception Mode"), use:

```bash
ARMORER_SANDBOX=1 armorer chat
```

## 6. Managing the Core Service

The **Armorer Core** runs in the background to monitor agents and process chat commands.

```bash
# Check if the Core is active
armorer core status

# View internal logs (debugging)
armorer core logs

# Restart/Update the Core
armorer core restart
```

For more details on how the oversight system works, see the [Oversight Hub Documentation](features/oversight.md).

## 7. Messaging Security Controls

If you use Telegram/Signal gateways, configure security controls before production use:

1. Set admin allowlists:
   - `ARMORER_TELEGRAM_ADMIN_USER_IDS`
   - `ARMORER_TELEGRAM_ADMIN_CHAT_IDS`
2. Set a task signing key:
   - `ARMORER_TASK_SIGNING_KEY` (vault secret)
3. Keep confirmations enabled for high-risk actions:
   - Telegram uses inline confirmation buttons and also accepts in-thread `confirm` / `cancel` replies; `/confirm <token>` still works for explicit approval.
   - Signal accepts in-thread `confirm` / `cancel` replies and still supports `/confirm <token>` for explicit approval.
4. Tune rate limits:
   - `ARMORER_TELEGRAM_RATE_LIMIT_COUNT`
   - `ARMORER_TELEGRAM_RATE_LIMIT_WINDOW_S`

See [Security Baseline](security_baseline.md) for full details and defaults.

### OTEL Monitoring (Default for OpenClaw)

OpenClaw is monitored via OTEL event feeds by default (instead of file tracking).

- Armorer reads runtime events from: `~/.armorer/otel_events/*.jsonl`
- Guard inspection runs on OTEL event payloads in near real-time.
- File tracking is still used for redaction overwrite of runtime files.
- To use full legacy file-first tracking for a specific agent, switch its `monitoring_mode` to `file` in the app registry entry.

For any agent that supports OTLP/HTTP emission, point it to Armorer's local collector endpoint:

```bash
armorer gateway otel setup
```

Default endpoint is `http://127.0.0.1:4318` and collector output is persisted in `~/.armorer/otel_events/`.
