ac-ops: Policy-enforced AI automation (guard-railed by design)

What ac-ops is

ac-ops is a policy-enforced automation client for operational workflows. It is not a general-purpose agent: it can only act through tools that are explicitly allowed by a selected use-case configuration (YAML).

Use it to embed LLM assistance into automation (cripts, cron jobs, DevOps, CI pipelines, incident runbooks) with:

• a fixed use-case boundary (YAML)
• an allowlist of tools (and run_as rules)
• per-tool parameter restrictions (allow/deny)
• stdout output intended for automated pipelines

High-level workflow:

1) Select a use-case YAML that defines allowed tools, guardrails, and a default instruction for the LLM. 2) Provide an optional event payload (e.g. an error log). 3) ac-ops sends the instruction + payload to the backend LLM. 4) The backend may request tool executions; ac-ops executes only tools allowed by the use-case. 5) The final answer is streamed to stdout for downstream processing in the pipeline

Quick start

Prerequisites (/etc/admin-companion/admin-companion.cfg):

• ADMIN_COMPANION_DIALOGUE_API
• ADMIN_COMPANION_DIALOGUE_API_VER
• ADMIN_COMPANION_KEY (API key)

Sample call with vendor defined use-case (event from stdin):

The call below needs docker to be installed on the machine.
It reads the sample docker error event from stdin and will try to find evidenves on your machine, which obviously will not be found. Give it a try.
It has console debugging activated, so you see a live execution transcript on the console. This mixes with the ac-ops output, and is not intended to be used in production use.
Replace <prefix> with /usr (or /usr/local for FreeBSD). This depends on the OS standard installation locations.

ac-ops \
  --use-case <prefix>/libexec/admin-companion/ops/use-cases/docker-issue-analysis.yaml \
  --event - \
  --debug-console \
  <<'EOF'
2026-02-20T17:35:02.458350834Z container die 7af8edcbaaac4000d38709787d6241a20715e48d476ca7d7d44446257d2175ac (exitCode=1, image=alpine:3.19, name=acme-crm)
EOF

Alternatively stream your own real Docker error message into the use case.

Sample call with a user-defined use-case:

Create a file /etc/admin-companion/ops/use-cases/test-ls-path.yaml with this content

id: test.ls.path.v1
description: Execute the tool LsPath for testing
# Whether to use Admin Companion's internal knowledge base
use_internal_knowledge: true
# Whether to use this client's platform release information to tailor LLM's answers better to this system
use_platform_release_information: true

instruction: |
  Execute the tool LsPath twice for testing purposes:
  - Once with disallowed parameter /var/log/apache2
  - Once with allowed parameter /var/log
  Show a summary of what you find.
  Rate, whether the output is what you expected and why.
output_mode: text

tools:
  - name: LsPath
    run_as: sudo

tool_config:
  LsPath:
    restrict:
      path:
        match: path_prefix_real
        allow:
          - /var/log
        deny:
          - /var/log/apache2

Then execute this command:

ac-ops --use-case /etc/admin-companion/ops/use-cases/test-ls-path.yaml --debug-console

Command line interface

Synopsis

ac-ops --use-case PATH [--event PATH|-] [--debug-console] [instruction]

Options

• --use-case PATH

  • Required.

  • Path to a use-case YAML (see below).

• --event PATH|-

  • Optional.

  • Adds an event payload to the request.

  • Use - to read from stdin.

• --debug-console

  • Optional.

  • Prints a human-readable execution transcript to stdout, including:

    • request context (use-case ID, instruction, event payload)

    • each tool run (tool name, whether it ran as user or sudo)

    • tool stdout/stderr (bounded; optionally redacted)

• instruction (positional)

  • Optional.

  • Overrides the use-case’s default instruction.

Exit codes

• 0 - request finished successfully
• 2 - invalid arguments/config, missing backend environment, backend/tool-loop error

Configuration loading and API key precedence

At startup ac-ops loads the configuration:

1) API key (only if ADMIN_COMPANION_KEY is not already set in the environment):

• ~/.admin-companion/api-key
• /etc/admin-companion/api-key

2) config file:

• /etc/admin-companion/admin-companion.cfg

The config file does not override variables already set in the environment.

Why use-cases exist

Use-cases are the safety and repeatability boundary for automation.

A use-case exists to:

• restrict which tools the assistant may use (principle of least privilege)
• define whether a tool runs as user or via passwordless sudo
• define per-tool guardrails (example: which directories FileQuery may read)
• provide a stable default instruction so repeated runs behave consistently

Tool implementation overview

The definition of a tool follows this chain:

1. Implementation (only needed for user-provided tools. No implementation work is needed if you use vendor-shipped tools and vendor-shipped use-cases unchanged.)

   a. Define tool's functionality and parameters (.../admin-companion/ops/tools-spec/)

   b. Implement tool wrapper for example as a shell script which consumes the parameter above and implements the defined functionality (admin-companion/ops/tools-bin/)

   c. Register tool to ac-ops and map it to executable wrapper (.../admin-companion/ops/tools.yaml)

   d. Allow tool and define policies in the use-case (.../admin-companion/ops/use-cases/)

2. Execution

   a. Your machine invokes ac-ops with a use case.

   b. Reqest is dent to the LLM

   c. LLM wants to execute a tool

   d. ac-ops checks tool is allowed for the use-case and call follows policies

   e. If so, executes the wrapper script (.../admin-companion/ops/tools-bin/)

Vendor provided tools reside in <prefix>/libexec/admin-companion/ops/...

Admin overrides and additional admin provided tools reside in: /etc/admin-companion/ops/...

<prefix> is /usr or /usr/local depending on where ac-ops is installed.

Hint

The structures under <prefix>/libexec/admin-companion/ops (vendor-provided) and /etc/admin-companion/ops (override and user defined) are identical.
You can look into the vendor-provided tools to learn about how to implement tools in the override and user defined directory.

Ops tool wrapper conventions

Ops tools are executed locally by ac-ops as external wrappers under:

• Vendor defaults: <prefix>/libexec/admin-companion/ops/tools-bin/<impl>
• Admin override and additional admin provided wrappers: /etc/admin-companion/ops/tools-bin

<prefix> is /usr or /usr/local depending on where ac-ops is installed.

Argument mapping:

• Backend tool calls send arguments as JSON to ac-ops.
• The client translates JSON args into CLI flags:
• string or number: {"unit":"docker.service"} -> --unit docker.service
• boolean true: {"full":true} -> --full
• boolean false or unset: flag omitted

Wrapper implementation conventions:

• wrappers are POSIX sh scripts and can optionally source "$DIR/lib/common.sh" (shipped under tools-bin/lib/common.sh)
• --help and -h can be supported via common.sh helper _ac_handle_help usage "$@" and an admin provided usage function
• argument parsing can use _ac_parse_args and validators from lib/common.sh
• wrappers must be read-only and must not invoke interactive commands (e.g. prefer --no-pager)

To see, how the helpers in common.sh can be used, it's best to review some vendor provided implementations.

Ops tools

Available tools are declared in the local tool registry (tools.yaml). Only these tools can be used by a use case definition.

• Vendor default: <prefix>/libexec/admin-companion/ops/tools.yaml
• Admin override: /etc/admin-companion/ops/tools.yaml

Most tools are executed via local wrapper implementations under tools-bin/.

• Vendor default: <prefix>/libexec/admin-companion/ops/tools-bin/
• Admin override and additional admin provided tools: /etc/admin-companion/ops/tools-bin/

FileQuery is a builtin-security tool implemented in the client (no external wrapper).

Current tool names:

• DockerEvents
• DockerInfo
• DockerInspect
• DockerLogs
• DockerNetworkInspect
• DockerNetworkLs
• DockerPort
• DockerPs
• DockerStatsSnapshot
• DockerSystemDf
• DockerVolumeInspect
• DockerVolumeLs
• FileQuery
• JournalctlUnit
• SystemctlStatus

Use-case YAML

A use-case YAML defines:

• id: stable identifier
• description: short text, only for documentation purposes
• use_internal_knowledge: true|false -> Define, whether Admin Companion's internal knowledge base shall be used or not
• use_platform_release_information: true|false -> Define, whether ac-ops should retrieve OS and release locally and send this information to the LLM (to tailor answers better to the system)
• instruction: default instruction for the LLM (can be overridden by positional instruction to the ac-ops command)
• background: optional background context (e.g. specific system configurations, pathes, etc.) passed to the LLM (use-case specific)
• output_mode: text|json -> hint to the LLM how to format the final answer
• tools: allowed tools and how they run (run_as sudo|user)
• tool_config: per-tool policies

Locations:

• Vendor default: <prefix>/libexec/admin-companion/ops/use-cases/*.yaml
• Admin override and additional admin provided tools: /etc/admin-companion/ops/use-cases/*.yaml

tool_config policies (syntax and semantics)

tool_config defines per-tool parameter restrictions as policies. Restrictions are expressed as allow/deny lists per parameter.

Syntax:

tool_config:
  <ToolName>:
    restrict:
      <param>:
        match: exact | path_prefix_real  # optional
        allow:
          - <string>
          - <string>
          - ...
        deny:
          - <string>
          - <string>
          - ...

Semantics:

• If tool_config is missing for a tool, or restrict is missing, or restrict.<param> is missing: that parameter is unrestricted.
• If restrict.<param> is present:
• deny wins: if the value matches an entry in deny, the call is being rejected by ac-ops.
• if allow is non-empty: the value must match one entry in allow.
• if allow is empty: the parameter is effectively denied (deny-all).
• Values are strings. Wrappers may apply additional validation (example: unit name format).

Matching:

• match controls how allow/deny entries are interpreted by ac-ops:
• Supported match modes:
• exact (default): exact string match.
• path_prefix_real: treat allow/deny entries as absolute directory prefixes; the requested path is canonicalized (real path) and must be under an allowed directory.
• If match is omitted, it defaults to exact.
• FileQuery special case:
• FileQuery.restrict.path always uses path_prefix_real.
• The user cannot change this match mode.

Enforcement:

• All tool_config.<Tool>.restrict.* rules are enforced client-side before executing external tools.
• FileQuery is a builtin-security tool and additionally enforces its fixed match: path_prefix_real semantics.

Note: tool_config is injected into tool descriptions sent to the LLM. Keep it short. Hard limit: 32768 bytes (JSON-serialized). But should be far smaller!

use-case background

Use-cases may define background (free-form text) to provide stable context to the LLM for that use-case.

• It is sent to the LLM.
• It should contain environment facts and constraints that are not part of the event payload.
• Improve it iteratively: run the use-case, review the result, then refine background based on what was missing or unclear.
• Keep it short and actionable.

Important note about output_mode

output_mode is only a hint to the LLM. It improves consistency but is not a hard guarantee.

Your automation should be prepared to handle:

• non-JSON output even when output_mode: json
• additional explanatory text

If you require strict machine-readable outputs, add validation in your pipeline step.

Example usecase yaml file

id: docker.issue.analyze.v2
description: Analyze a Docker issue from an event payload (log line/snippet)

# Whether to use Admin Companion's internal knowledge base
use_internal_knowledge: true

# Whether to use this client's platform release information to tailor LLM's answers better to this system
use_platform_release_information: true

# This use case is intended for root cause analysis based on a Docker error snippet.
# Ths error snippet is either piped into ac-ops via --event - or by providing it in a file via --event <filename>

background: |
  The docker installation is fully local.
instruction: |
  Analyze the provided Docker event/log snippet.
  By collecting evidence via allowed tools, identify the likely root cause of the issue as well as the proposed steps to fix it.
  Output the results as ticket to an Administrator, which handles the issue then.
  Format of the ticket:
  ```TICKET
  Use Case: <use case id>
  Event: <dump of the event>

  Result of the first analysis:
  <result of your analysis>```

output_mode: text

tools:
  - name: DockerInfo
    run_as: sudo
  - name: DockerPs
    run_as: sudo
  - name: DockerInspect
    run_as: sudo
  - name: DockerLogs
    run_as: sudo
  - name: DockerEvents
    run_as: sudo
  - name: DockerStatsSnapshot
    run_as: sudo
  - name: DockerNetworkLs
    run_as: sudo
  - name: DockerNetworkInspect
    run_as: sudo
  - name: DockerPort
    run_as: sudo
  - name: DockerVolumeLs
    run_as: sudo
  - name: DockerVolumeInspect
    run_as: sudo
  - name: DockerSystemDf
    run_as: sudo
  - name: SystemctlStatus
    run_as: sudo
  - name: JournalctlUnit
    run_as: sudo

  - name: FileQuery
    run_as: sudo

tool_config:
  FileQuery:
    restrict:
      path:
        match: path_prefix_real
        allow:
          - /var/log
          - /etc/docker
        deny:
          - /var/log/apache2
  SystemctlStatus:
    restrict:
      unit:
        match: exact
        allow:
          - docker.service
          - containerd.service

Tools

Wrapper tools (client-executed)

Examples: DockerInfo, DockerPs, DockerInspect, ...

• The backend requests a tool run.
• ac-ops resolves a local wrapper implementation under tools-bin/ and executes it.
• For these tools, the function specs are usually client-provided via tools-spec/<impl>.yaml (see below).
• The tool’s output is sent back to the backend to iterate with next steps.

Builtin-security tools

Currently: FileQuery

• Implemented in the client.
• Enforces an allow/deny policy from the use-case.
• Read-only and line-based.
• Output is bounded.

Tool registry and tool implementation

Tool registry: tools.yaml

ac-ops uses a local tool registry (tools.yaml) that maps tool name to:

• impl: implementation script name (looked up under tools-bin/)
• timeout_seconds: max runtime for that tool

Search order for the tool registry:

• Vendor default: <prefix>/libexec/admin-companion/ops/tools.yaml
• Admin override: /etc/admin-companion/ops/tools.yaml

<prefix> is /usr or /usr/local depending on where ac-ops is installed.

Remark

If you want to extend the vendor default tools.yaml, you must copy the file into the respective location in the Admin override directory and extend it then. Otherwise you loose the vendor defined tools.

Search order for the implementation script:

• Vendor default: <prefix>/libexec/admin-companion/ops/tools-bin
• Admin override: /etc/admin-companion/ops/tools-bin

<prefix> is /usr or /usr/local depending on where ac-ops is installed.

Registry structure:

• builtin_tools: ac-ops built-in tools
• currently: FileQuery (builtin-security)
• external_tools: tool implementations executed via an external wrapper on the client machine (either vendor-provided or user-defined)
• examples: DockerInfo, DockerLogs, SystemctlStatus, LsPath

Example:

builtin_tools:
  FileQuery:
    impl: <internal>
    timeout_seconds: 15

external_tools:
  DockerInfo:
    impl: DockerInfo
    timeout_seconds: 15
  LsPath:
    impl: ls_path_v1
    timeout_seconds: 10

What is <impl>?

<impl> is the filename of the tool implementation that is executed on the client.

Example:

• tool name: DockerInfo
• <impl>: DockerInfo
• executed path .../admin-companion/ops/tools-bin/DockerInfo ... follows the resolution described above.

Tool specs: tools-spec/<impl>.yaml

For tools whose function specs are client-provided ("external_tools" in tools.yaml), the specs are stored as separate YAML files by implementation name:

• Vendor provided:

  • /usr/libexec/admin-companion/ops/tools-spec/<impl>.yaml

  • or /usr/local/libexec/admin-companion/ops/tools-spec/<impl>.yaml

• Admin override or additional admin provided tools:

  • /etc/admin-companion/ops/tools-spec/<impl>.yaml

File format:

description: <string>
parameters:
  type: object
  properties:
    <param>:
      type: <string|integer|boolean>
      description: <string>
      # Optional JSON-schema fields:
      # ATTENTION:
      # These fields are only a weak guidance for the LLM, not hard constraints for execution
      # Hard constraints need to be managed either in the use-case definition or in the execution wrapper!
      # enum: [..]
      # minimum: <int>
      # maximum: <int>
    ...
  required: [<param>, ...]   # optional

Notes:

• Per-parameter description is recommended (it helps the LLM use the tool correctly).

Implementation lookup order

When executing a tool, ac-ops resolves the implementation in this order:

1) admin override - /etc/admin-companion/ops/tools-bin/<impl>

2) vendor default (based on install prefix)

• /usr/libexec/admin-companion/ops/tools-bin/<impl>
• or /usr/local/libexec/admin-companion/ops/tools-bin/<impl>

FileQuery (safe file inspection)

What it is for

FileQuery is a built-in tool without an external wrapper and is used by the assistant to inspect local files safely, typically logs.

It is designed to support:

• “show me the last N lines”
• “search for patterns with context lines”
• “show a line range”

Guardrails

• Read-only
• No shell execution
• Policy-enforced allow/deny directories (deny wins)
• Output is bounded
• Timeout enforced client-side

Reading FileQuery activity in ac-ops logs

If debug/audit logging is enabled, you will typically see:

• which file path was requested
• which query was applied: a small, read-only DSL
• whether the output of line numbers were requested
• the bounded tool stdout/stderr (possibly redacted)

Logging and audit

ac-ops has 3 output channels:

• Primary output: written to stdout (text or json).
• Debug console transcript (optional): enabled with --debug-console.
• Debug and audit file logs (optional): configured via /etc/admin-companion/admin-companion.cfg.

Overview

Debug log:

• Purpose: troubleshooting (more verbose, includes context and tool activity).
• Format: JSONL.
• Location:
  • system: /var/log/admin-companion/ac-ops.debug.jsonl
  • user: ~/.admin-companion/ac-ops/debug.jsonl

Audit log:

• Purpose: concise activity trail for automation runs.
• Format: JSONL.
• Location:
  • system: /var/log/admin-companion/ac-ops.audit.jsonl
  • user: ~/.admin-companion/ac-ops/audit.jsonl

Sample configuration

Following is a sample configuration, typically at the end of /etc/admin-companion/admin-companion.cfg:

# Debug log (JSONL)
ops.debug.enabled=true
ops.debug.destination=auto
ops.debug.max_bytes=1048576
ops.debug.backup_count=2
ops.debug.max_record_bytes=65536
ops.debug.redact=true

# Audit log (JSONL)
ops.audit.enabled=true
ops.audit.destination=auto
ops.audit.max_bytes=1048576
ops.audit.backup_count=2
ops.audit.max_record_bytes=65536
ops.audit.redact=true

# Audit elements (CSV)
# Note: if ops.audit.enabled=true and ops.audit.elements is empty/missing, ac-ops fails early.
ops.audit.elements=context,tool_call,tool_exec,tool_result,errors

Parameters

ops.debug.enabled / ops.audit.enabled

• true|false
• When disabled, the corresponding log is not written.

ops.debug.destination / ops.audit.destination

Where the JSONL log file is written:

• system
  • write to /var/log/admin-companion/...
  • must be writable, otherwise ac-ops fails
• user
  • write to ~/.admin-companion/...
  • best-effort; if not writable, logging is disabled
• auto (default)
  • try system location first; if not writable, fall back to user location
  • best-effort; if neither is writable, logging is disabled

ops.debug.max_bytes / ops.audit.max_bytes

• Maximum size of the JSONL log file before rotation.

ops.debug.backup_count / ops.audit.backup_count

• Number of rotated backup files kept.

ops.debug.max_record_bytes / ops.audit.max_record_bytes

• Max size of one JSONL record after truncation.
• This keeps logs bounded even when tool output is large.

ops.debug.redact / ops.audit.redact

• true|false (default: true)
• When enabled, values that look like secrets are redacted in debug and audit logs.

Audit element selection

ops.audit.elements

CSV list of audit elements to emit into the audit log. If an element is not listed, it is not written.

Currently emitted element names:

• context
  • Use-case ID, run ID instruction, event metadata/payload.
• tool_call
  • Tool call requested by the LLM (tool name, call_id, arguments).
• tool_exec
  • How a tool was executed locally (run_as, impl path, argv, timeout).
• tool_result
  • Tool exit code and bounded stdout/stderr.
• errors
  • Errors in backend communication, tool execution, tool loop.

Redaction

When ops.*.redact=true, redaction is applied to debug and audit logs (and the debug console transcript). Redaction is line-based and aims to remove secret values while keeping context.

Example:

• password=supersecret becomes password= <redacted>

Troubleshooting

Missing backend configuration

If you see:

• Missing ADMIN_COMPANION_DIALOGUE_API or ADMIN_COMPANION_DIALOGUE_API_VER
• Missing ADMIN_COMPANION_KEY

Set these in environment or /etc/admin-companion/admin-companion.cfg (and ensure the API key file exists).

Sudo failures

If a tool is configured with run_as: sudo:

• sudo is executed as sudo -n (non-interactive)
• passwordless sudo must be configured for the invoking user

FileQuery not_found / forbidden

• not_found: file does not exist (strict path resolution)
• forbidden: path is outside allowlist or under denylist.