Admin Companion - Documentation

This is the documentation for client version 3.0+ of Admin Companion.
Click here to get to the documentation of client version 2.3.
Click here to get to the documentation of client version 2.0 - 2.2.
Click here to get to the documentation of client version 1.x.

Contents

Network Flow

ATTENTION

Version 2 of Admin Companion changes to the new domain name and a new port below. IP address stays the same.

The Admin Companion client needs to be able to send POST requests to and receive answers from these two Admin Companion API endpoints:

  • https://api.admin-companion.ai:443/dialogue/
  • https://api.admin-companion.ai:443/search/

Make sure, your firewalls do not block the traffic.

Simplified network flow:

Quick Start

  1. Regsiter for an Admin Companion account.
  2. Create an API key on the API Keys page in the web console (need to login to get there).
  3. Install the client software on your operating system. To do so, follow the description on the download page, according to your operating system.
  4. Make the client using the API key.
    • You always can insert the API key manually between the quotes in the Admin Companion configuration file at
      /etc/admin-companion/admin-companion.cfg
      in the line
      ADMIN_COMPANION_KEY=""
    • When using the .deb installation package, you also can give the API key during in the installation procedure.
      During the installation, the API key will be copied to the configuration file for you.
      You can always change the API key later by calling sudo dpkg-reconfigure admin-companion and entering the API key on the second configuration screen.
  5. Call for example
    ai Are you there?
    to check, Admin Companion is answering.
  6. If not, check the Admin Companion log file at $HOME/.admin-companion/admin-companion.log for the reason

Security Layer

The client software has a built-in security layer, which ensures, that only user-approved commands can be executed.
The Artificial Intelligence does never directly interact with the system. It only can communicate with the security layer of the client software . This security layer assures the user's approval before any command execution.

Using the client

You can invoke the Admin Companion client with the command: ai

Usage: ai [options] | [max request token size] [natural language request]
You only can give either an option or a natural language request, but never both at the same time.

[options]: See Command Line Parameters below

[max request token size]: -s <number of tokens> / --size <number of tokens>:

Admin Companion works with "max request token size" (also called context window), which is counted in tokens (one token equals to approx. 0.75 words).
The remembered dialogue cannot be longer than the "max request token size". When it gets longer, elder messages in the dialogue "fade out" from memory.
The standard "max request token size" is defined in the configuration file.
With this parameter you optionally can set another "max request token size" for this single request.
You might want to choose a smaller "max request token size" to safe money (billing is based on number of in and out tokens per request).
You might want to choose a bigger "max request token size", if you temporarily need to process much information or want to remember a longer dialogue history.

[natural language request]:

To instruct Admin Companion, you have two choices for the natrual language request:
  1. Give your instruction in clear text on the command line
    • In this case, you need to consider, that the shell interprets your input as parameters to the command.
      This means for example:
      • You need to escape brackets:
        Not: ai find and list the configuration files of the application xyz (you find the application in /usr/xyz)
        But: ai find and list the configuration files of the application xyz \(you find the application in /usr/xyz\)

      • Consider, that quotes are interpreted from the shell as quotes, which need to be closed again:
        Not: ai I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data
        But: ai I would like to create a backup script with 10 rotating files for the content of the path /mnt/data

        ...or just close the quote again at the end of the line. Not nice, but works:
        ai I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data'

      • Consider, that * and ? are replaced by the shell wich the respectively filtered content of the current directory.

  2. To get out of all this, you can start ai without any parameter
    • In this case, the Admin Companion client requests you to enter your instructions, which then can be multi line (just press "Enter" to go to the next line). Here you can even copy files as parts of the instructions. When you want to end your instruction, just send an EOF (End-Of-File), by pressing "Ctrl-D" at the beginning of a line.
      $ ai
      Enter your input. End with EOF (Ctrl+D or Ctrl+Z) on a new line:
      I'd like to create a backup script.
      I want to backup: /mnt
      Please tar zip the files
      The tarball should be written to /backup
      <Ctrl-D>

Samples:

  • ai Are you there?
  • ai -s 10000 Are you there?
    Admin Companion works with "max request token size" (also called context window), which is counted in tokens (one token equals to approx. 0.75 words).
    The remembered dialogue cannot be longer than the "max request token size". When it gets longer, elder messages in the dialogue "fade out" from memory.
    The standard "max request token size" is defined in the configuration file.
    With -s you can set another "max request token size" for this single request.
    You might want to choose a smaller "max request token size" to safe money (billing is based on number of in and out tokens per request).
    You might want to choose a bigger "max request token size", if you temporarily need to process much information or want to remember a longer dialogue history.
  • ai -v
  • ai -t We analyze an issue with our web server not reacting to requests on port 443.
    This sets a topic which is remembered and never fades out from memory until you clear it with the -r parameter.
  • ai
    This lets you enter the request interactively.

Command Line Parameters

  • -h or --help
    Display the help text
  • -l or --list
    Show the stored dialogue history
  • -c or --clear-messages
    Clear the conversation history. This makes sense to start a new topic and make Admin Companion forget the previous conversation. Also reduces the number of tokens and therefore the cost for the request.
  • -t [<topic>] / --set-topic [<topic>]
    This sets a topic for Admin Companion. The topic does not "fade out" from the dialogue but will stay in memory of Admin Companion. So, on long tasks, the focus stays on this topic.
    Note: When using -t, it must be the last option on the command line. The topic can be given on the command line or you can leave the topic empty, then you are requested to input the request interactively. Do not include the <> brackets in the topic.
  • -r or --remove-topic
    Removes the general topic, which has been set with -t or --set-topic previously.
  • -a or --allow-use-release
    Allow to retrieve and send the OS release number to allow Admin Companion to tailor the answers better to your OS release.
    This setting is stored persistently and used for future requests.
  • -d or --disallow-use-release
    Dis-allow to retrieve and send the OS release number. With this setting, Admin Companion's answers will be more general.
    This setting is stored persistently and used for future requests.
  • -m <model> / --model <model>
    Set the model to be used.
    Standard model is o3-mini. Currently only gpt-4o is allowed as <model> to change the request to use the gpt-4o model
  • -v or --version
    Show the version and revision of the client software.

Files used by Admin Companion client

The following files are used in context of Admin Companion client:

  • Folder: $HOME/.admin-companion/
    • admin-companion.log: Log file of the admin companion client. The file is rotated with two files at a size of about 1M each.
    • admin-companion.bill: This file logs for each request ths number of tokens consumed. The file is rotated with two files at a size of about 1M each.
    • conversation_history.pickle: This file stores the conversation history of the user in a persistent way, even over a system re-boot.
  • Folder: /etc/admin-companion/
    This folder contains all configuration files of the Admin Companion client.
  • Folder: /user/bin/
    This folder contains the executable admin-companion and the symlink to ai

Web Console - Dashboard

On the web console dashboard you see an overview of your balances and your usage on montly base (12 month) and daily basis (current calendar month).

Web Console - Requests

On this page you can see the meta date of the latest requests, which have been made on one of your API keys (without the contents of the request).

Web Console - API keys

API keys are used to authenticate the Admin Companion client's requests. Keep your API keys secret like a password!

You can create, manage and delete your API keys on the API Keys page in the web console.
You have the following options:

  • Create a new API key.
    You need to give the API key a name to subsequently identify the key.
    The API key will only be displayed once at creation time. Make sure to store it in a safe place. If you loose the API key, neither you nor us can restore it!
    But you can delete and re-create API keys at any time. Be aware, that the key will be displayed on the screen. Make sure no unauthorized person can see your screen.
  • Deactivate an API key temporarily by clicking on it's status symbol.
  • Rename an API key by clicking on the pen symbol at the end of the line of an API key
  • Delete an API key permanently
    A deleted API key cannot be restored. But you can create new API keys at any time
Once you have created an API key, you can use the API key in the Admin Companion client. You always can define the API key to be used in the Admin Companion client configuration file at /etc/admin-companion/admin-companion.cfg in the line
ADMIN_COMPANION_KEY="<Your API key>"
ATTENTION!
  • Debian and Ubuntu
    Be aware, that installing a new version of the Admin Companion client will overwrite a manually entered API key in the configuration file with the API key given at initial installation.
    You can enter an API key in the installation procedurem, when Admin Companion is installed the first time.
    You can change an API key by calling sudo dpkg-reconfigure admin-companion and entering the API key on the second configuration screen.
    This will copy the API key into the configuration file and preserve it for the next software update.
  • For RedHat and Fedora
    Be aware, that installing a new version of the Admin Companion client will overwrite the API key in the configuration file.
    Therefore, copy the API key to a safe place before installing a new version of the Admin Companion client.

Web Console - My Profile

The My Profile page on the web console allows you to change your Name, VAT Id and Address. You cannot change your country, company name or email address.

Web Console - Account

This page shows you your account balances. There are two balances:

  • Expiring balance. This balance expires at the end of a billing cycle. At each start of a billing cycle, when you pay the monthly fee, this amount is reset to the monthly payment value.
    You can then use that amount within the billing cycle by using Admin Companion.
  • Non-Expiring balanceThis balance will only expire, when your subscription is being cancelled. While you are subscribed to a monthly plan, any remaining amount in this balance will be transferred to the next billing cycle.
    When you choose the automatic refill feature (see below), any payments based on that will go into the non-expiring balance.
    When you change your monthly plan, you will immediately be charged the amount of the new montly fee (without changing the date of the billing cycles). This fee will also go to the non-expiring balance.
When you have an expiring balance and a non-expiring balance, Admin Companion usage is always deducted from the expiring balance first, until this is fully consumed. Only then, the non-expiring balance is consumed.

Automatic Refill feature: Standard behaviour is, that in case of full consumption of all your balances, Admin Comanion client declines further requests with an "Account limit reached" message in the log file.
If you activate the Automatic Refill feature, Admin Companion automatically charges your payment method again, when you consumed all your balances within a billing cycle. Any refills go to the non-expiring balance, which follows the mechanisms, as described above.
Refill is always the same amount, as the monthly fee.
Don't forget to click on "Update Account Settings" after changing the auto-refill to become effective.

Transactions: On the Account page you also can see your last 30 transactions (like monthly payments, refills, payment method changes, etc.)

My Subscription

On the subscription page you see, which Plan you currently are subscribed to. You can activate a subscription, change to another subscription or cancel your subscription.

Change plan: When you change between the plans S, M, L, the monthly fee of the new plan is immediately charged to your stored payment method and added to the non-expiring balance (See "Acoount" for details). Your further usage then will be billed immediately at the unit price of the new plan.

Update payment method: On this page you can also update your payment method.

Cancel: Cancellation will be scheduled to the end of the billing cycle. You can continue to use Admin Companion until the end of the billing cycle.
When your refill feature is activated, your payment method will still be charged for possible refill actions.
When you cancel a subscription, all non-expiring balance will expire at the end of the billing cycle.
Within the last about one hour before the end of a billing cycle, it is not possible to perform any changes on the subscription.
Your account will still be available for at least one year, so you can decide to subscribe to a plan later again.