Admin Companion - Documentation

This is the newest version of the documentation
for client versions 4.0+

Click on the version numbers to get to older version's documentations: 3.1 - 3.2 3.0 2.3 2.0 - 2.2 1.x

Contents

Network Flow

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. There are three locations, where you can set the API key. Choose one of the following options:
    • Environment variable (user specific)
      Set an environment variable ADMIN_COMPANION_KEY to the API key value:
      export ADMIN_COMPANION_KEY="<Your API key>"
      To make this persistent, you can execute the command in your shell configuration file, for example in $HOME/.bashrc for bash. Use your own shell's resource file.
      Remember to restart your shell or call source $HOME/.bashrc after changing the file.
      You can check, if the environment variable is set by calling echo $ADMIN_COMPANION_KEY in your shell. It should return the API key value.
    • File $HOME/.admin-companion/api-key (user specific)
      Add a line in the format
      ADMIN_COMPANION_KEY="<Your API key>"
      in the file $HOME/.admin-companion/api-key
      You can add additional lines with a hash sign (#) at the beginning of the line, which will be ignored by the client software.
      Be sure to make the file readable only by you, for example with the command chmod 600 $HOME/.admin-companion/api-key.
    • File /etc/admin-companion/api-key (system wide)
      Attention:This solution can be a security risk, because every user on the system can see the API key!
      Add a line in the format
      ADMIN_COMPANION_KEY="<Your API key>"
      in the file /etc/admin-companion/api-key
      You can add additional lines with a hash sign (#) at the beginning of the line, which will be ignored by the client software.
      The file needs to be readable by everyone, but should be writable only by root, for example with the commands
      chown root:root /etc/admin-companion/api-key
      chmod 644 /etc/admin-companion/api-key

  5. Call for example
    ai "Are you there?"
    to check, Admin Companion is answering.
    Try to use your request in your own language. It will also work the same way:
    ai "¿Estás ahí?"
    ai "Est-ce que tu es là?"
    ai "Bist du da?"
  6. If it doesn't work correctly, 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] [model] [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>  or  --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.

[model]: -m <model-name>  or  --model <model-name>:

You can select, which model you would like to answer to your request. Available models are currently:
gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, o4-mini, o3-mini.
If you don't specify a model, the backend's default model is used, which is currently gpt-5 (subject to change without notice).
Hint: It is the small letter "o" in the model names, not a zero.
Sample: ai -m gpt-4.1 Are you there?

[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
    • The cleanest way is tu use quotes around your instruction:
      ai "I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data"
      This way, you can use all characters in your instruction without any problems.
    • If you leave out the quotes, please be aware 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'

        ...or just enclose the everything with quotes:
        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. Start ai without any parameter and enter your instruction interactively:
    • 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 100000 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.
  • -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/
    • api-key: The API key used by Admin Companion client. This file is optional, because there are other possibilities to store the API key.
    • 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 the 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/
  • admin-companion.cfg: Admin Companion Configuration file.
  • api-key: The API key used by Admin Companion client. This file is optional, because there are other possibilities to store the API key.
  • symlink_name: Internal file for installation/deinstallation. Never change this file.
    • 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 recurring fee, this amount is reset to the recurring 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 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 plan, you will immediately be charged the amount of the new recurring 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.
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 recurring 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 recurring 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 recurring fee of the new plan is immediately charged to your stored payment method and added to the non-expiring balance (See "Account" 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.