Skip to content

Agent Connector

Agent Connector Configuration

Shares: Outbound Agent Secure Exposed Access

The Agilicus Agent Connector facilitates connection from a bastion network and end-users. It installs on a device somewhere inside the protected network, making an outbound connection.

The Agent Connector is self-updating. Once installed it will stay up to date. The live Changelog shows the updates that have occurred.


Installation instructions are given from the Admin portal during the creation step. Each Agent Connector has 2 unique parameters: a GUUID (which identifies it), and an OpenID Connector Issuer (which controls its authentication domain).

During the creation of the Agent Connector you will give it a name. This name should have some meaning for you, e.g. the site it is installed in, the host it is installed on, etc.

Theory of Operation

Installation will create a Service Account (for the Agent Connector to run as). See “Agent Connector Sign-In” for more information.

The Agent makes an outbound-only connection, through your existing firewall (often with no configuration changes).

Once the Connector is installed, you can later add new directories to share, new services to expose, entirely from the administrative web interface.

The Connector will automatically keep itself up to date and pick up new configuration. Set it and forget it.

Uninstall / Delete

When you no longer need an Agent Connector, you should first uninstall it from the host it is on. Then you may delete it from the Admin portal

Download / Install

Instructions per platform are given, personalised, in the administrative portal. They are also shown below for reference.

If you wish, you may download the binaries from these links.

Install as per the instructions below ( agilicus-agent client --install --agent-id UUID --oidc-issuer https://auth.YOURDOMAIN ). Once installed, the software will automatically keep itself up to date using The Update Framework.

NOTE: If the agent is used solely on the client side (e.g. ssh ProxyCommand, Launcher) no install is needed, it just needs to be on the path.

Linux Specific


The Agilicus Agent runs as an unprivileged system user. This means that, by default, it will not have permission to read files in a shared directory created by you. To give it access, create a group whose purpose is to group users who have permission to read and write shared files on the machine. Add the agilicus user to the group, then give that group permission to access the shared folder.

# Set up the shares group and add the agilicus user to it
sudo addgroup shares
sudo usermod -a -G shares agilicus
# Configure the share and all files within it to allow access to the shares group
sudo chgrp -R shares my-shared-directory
sudo chmod -R g+srw my-shared-directory
# Ensure files created by the agent and other users have the proper permissions
sudo setfacl -d -m g::rwx my-shared-directory


The Agilicus Agent runs from systemd. You can stop it with

sudo systemctl stop agilicus-agent

You can permanently uninstall it with

sudo /usr/bin/agilicus-agent client --uninstall --cfg-file /etc/agilicus/agent/agent.conf.enc.yaml

Windows Specific


The Agent Connector runs as a Windows Service. You will be given instructions to download it, and will then run it as an Administrative user to install. A command line will be generated you can copy, which will look similar to below.

%UserProfile%\Downloads\agilicus-agent.exe client --install --agent-id XXXXXXXXX --oidc-issuer

Once the Agilicus Agent is installed, it will automatically configure itself and keep itself up to date.


"%ProgramFiles%\Agilicus\Agent\agilicus-agent.exe client --uninstall --cfg-file "%ProgramFiles%\Agilicus\Agent\agent.conf.enc.yaml"

Windows Notes

NOTE: WebClient Service

You may need to manually enable the Windows WebClient service if you will use the connector to mount a remote WebDav Share to this machine. Normally this is set to run on demand, but in some environments it may be disabled.

NOTE: Windows Failover Clustering High Availability

To configure the Agilicus Agent for 1+1 ACTIVE/PASSIVE on Windows Cluster Server, use a Generic Service. For more information, see Agilicus Agent Windows Cluster Server

Kubernetes Specific


In a similar fashion to the Linux install above, download the binary. In the command line, change ‘–install’ to ‘–kubernetes-install’. This will run and then give you a kubectl command line to run. You may inspect/modify the generated YAML before applying.

bin/agilicus-agent client --kubernetes-install  --agent-id XXXXXXX --oidc-issuer --no-upgrades
INFO[2021-06-24T19:32:40.695380725-04:00] Starting client - version v0.59.0-5-g3c7a28f-dirty 
INFO[2021-06-24T19:32:41.073253518-04:00] Download public key file                     
INFO[2021-06-24T19:32:41.073370301-04:00] Will install into directory /tmp/agilicus-agent-3835986779 
INFO[2021-06-24T19:32:41.261896657-04:00] Fetch agent configuration                    
INFO[2021-06-24T19:32:41.261933338-04:00] Write agent configuration file in temp directory 
INFO[2021-06-24T19:32:42.473685368-04:00] Output Kubernetes YAML                       
INFO[2021-06-24T19:32:42.517497179-04:00] Now run:
 kubectl apply -f /tmp/agilicus-agent-3835986779/agilicus-agent.yaml 
INFO[2021-06-24T19:32:42.51752864-04:00] Installation Complete              

The YAML that is applied to your system will:

  1. Create a namespace agilicus-agent
  2. Create a service-account in that namespace
  3. Create a PersistentVolumeClaim of 100Mi
  4. Create a Deployment with no privilege
  5. Create a Secret with initial credentials

The Deployment will need outbound (and only outbound) connectivity to the Internet. Specifically, it will need to be able to reach and . No inbound connectivity will be created, no Ingress, no LoadBalancer.