armorer

Use Armorer As The Operator Surface

Use this skill to operate applications through Armorer rather than by hand.

Workflow

1. Inspect current state first.

Use commands like:

uv run armorer list
uv run armorer run <agent> status

2. Prefer Armorer commands over raw shell.

Examples:

uv run armorer install <agent> --yes --skip-scan
uv run armorer run <agent>
uv run armorer uninstall <agent> --force
uv run armorer app configure <agent>

3. Treat long-running work as job-aware work.

Background job state is stored in:

• ~/.armorer/jobs/*.json

If a chat/Core flow starts a job, track it through track_job.

Do not fire a long-running command and stop there. Monitor until it reaches a terminal state.

Minimum monitoring loop:

1. start the install/run/uninstall action
2. inspect job state, process state, or service/container state while it is active
3. distinguish slow progress from a stuck or stale operation
4. report success only after terminal verification

Examples:

• after uv run armorer install <agent> --yes --skip-scan

  • keep checking uv run armorer list
  • inspect the relevant job or container state if the install is still in progress
  • verify runtime status once the install completes

• after uv run armorer run <agent>

  • continue checking service or container health until the app is actually up
  • do not report success from launch intent alone

4. Start setup work with a short Q&A.

Do not assume configuration choices that belong to the user.

Before applying setup for an app:

1. inspect current Armorer or app config
2. tell the user what is already set
3. ask only for the missing or unclear values
4. ask one concrete question at a time
5. apply the config and verify it

Typical questions:

• which model provider to use
• exact model id
• API key or base URL
• which channels to enable
• which skills or tools to enable
• any required app-specific credentials

For channel setup, once the required credential has been collected:

1. ask whether Armorer should bind and verify that channel now
2. if the user defers, apply config but report channel verification as deferred
3. if the user confirms, bind and verify before reporting success
4. if the channel uses DM pairing, ask the user to send a message to the bot/app
5. ask the user to paste the pairing code they receive
6. approve that pairing through Armorer/OpenClaw before reporting the channel ready

If an existing value is already configured, say so and ask whether to keep it or replace it.

For model setup, preserve this order:

1. ask for the provider
2. ask for the exact model id
3. check whether a credential already exists for that provider
4. ask whether to keep or replace the existing credential
5. if replacement is needed, ask for the new API key or base URL

Do not ask about credential reuse before the model id is known.

For selected app-native skills, continue past selection:

1. inspect the skill requirements
2. filter out skills that are not feasible in the actual runtime
3. install any missing binaries in the app runtime context
4. if the app runs in Docker, install them where the container can actually access them
5. verify the binaries from the same runtime context
6. if a skill requires auth, login, bootstrap, or pairing, kick off that process too
7. verify the auth or bootstrap state from the runtime context
8. enable the skills in config
9. test the enabled skills with a minimal safe check

Do not assume a host-only install is sufficient for a containerized app. Do not expose infeasible skills as selectable options for the current runtime.

Examples of infeasible skills:

• host-only installer for a containerized runtime
• unsupported package manager for the target runtime
• dependency on a local desktop app the runtime cannot reach

5. Verify before reporting success.

Check at least one of:

• uv run armorer list
• runtime status command
• container or service state
• health endpoint
• resulting config files

Troubleshooting

If chat or Core looks wrong, inspect:

tail -n 120 ~/.armorer/chat_tui.log
docker logs --tail 120 armorer-core

If jobs look stuck:

uv run armorer core clear-queue
uv run armorer core clear-jobs

Use care before clearing jobs if you have reason to believe real work is still running.

If an operation appears hung, keep monitoring before declaring failure:

• inspect the active Armorer job record
• inspect relevant container or process state
• confirm whether there is live progress, a stale heartbeat, or a hard failure
• decide only then whether to retry, repair, or clear stale jobs

Source Files To Inspect

When behavior needs to change, start here:

• src/armorer/core.py
• src/armorer/tools/orchestrator.py
• src/armorer/main.py
• src/armorer/registry.py
• src/armorer/installers/dynamic.py

Guardrails

• Do not claim an install or setup succeeded without verification.
• Do not replace Armorer-managed flows with manual Docker commands unless Armorer lacks the capability.
• Preserve the training trace pipeline in ~/.armorer/training_data.