Use on-prem integrations with Aiden

Your most useful tools often sit behind a firewall. Grafana runs in a private VPC, Kafka brokers have no public address, GitHub Enterprise is only reachable over the corporate network. Aiden runs in the cloud, so by default it cannot reach any of them.

You can still give Aiden access. You install a small program called a remote runner inside your network. When you connect an integration, you tell Aiden to use that runner. From then on, every time an agent uses the integration, the work happens on the runner, next to your tool, and only the result goes back to Aiden.

Available for roles: Admin Workspace Admin

Scope: Workspace

What you can do with it

Investigate alerts with your internal Grafana. An SRE agent can read dashboards and query metrics from a Grafana instance that only your VPC can see.
Check private Kafka. Ask "Which consumer groups on prod Kafka are lagging?" and get an answer from brokers that never leave your network.
Work with GitHub Enterprise. Let an agent read repositories and pull requests hosted on your own GitHub server.
Meet compliance rules. Traffic to your systems starts inside your perimeter, so you do not open firewall ports or publish internal endpoints.

How it works

The runner connects out to Aiden over HTTPS and asks for work. You never open an inbound port.
When an agent needs your tool, Aiden hands the request and the saved credentials to the runner.
The runner starts a short-lived helper container, talks to your tool, and sends the answer back.

Aiden still plans the work, checks your policies, and records the audit trail in the cloud. Only the calls to your tool happen inside your network.

Use the normal cloud connection instead when your tool already has a public, secured API. You skip running anything yourself.

Before you begin

You are an Admin or Workspace Admin in Aiden.
You can run either a Kubernetes cluster or a Linux host with Docker inside the network that reaches your tool.
You have credentials for the tool, such as an API token or username and password. Read-only credentials are best to start with.
Not every integration can run on a runner. When you add the integration, Aiden only lets you pick a runner if that integration supports it.

Step 1: Install a runner in your network

Register a runner in Workspace Settings -> Connections -> Remote Runners and copy its token. The Remote Runners page walks through registration.

Then start it in one of two ways.

On Kubernetes. Install the Aiden runner Helm chart (runner version 0.4.0 or later). Most installs need only these values:

runner:
  mothershipUrl: https://cloud.stackgen.com
  existingSecret: aiden-runner-token

The Kubernetes Secret aiden-runner-token holds the runner token under the token key. For private registries, proxies, and access limits, see Runner settings reference.

On a host or VM with Docker. Use runner version 0.4.1 or later:

aiden-runner start \
  --mothership https://<your-aiden-host> \
  --runner-token <RUNNER_TOKEN> \
  --sidecar-runtime=docker

--sidecar-runtime=docker lets the runner start helper containers for integrations.

Wait until the runner shows as Online on the Remote Runners page.

Step 2: Connect your tool through the runner

Open Workspace Settings -> Connections -> Integrations.
Click Add integration and pick your tool, for example Grafana or Kafka. You can also edit an existing integration.
Enter the credentials and the address of your tool. Use the address as seen from inside your network, for example https://grafana.internal.example.com.
In Remote runner, pick the runner you started in Step 1.
Click Save, then Test Connection.

A successful test means the runner reached your tool. The integration now lists the tools agents can use.

Step 3: Give an agent access

A working connection does not yet give any agent access. Attach the integration to each agent that should use it:

Open the integration and click Attach to, or open the agent and add it under Integrations.
Pick the agent, for example your SRE agent.

You do not need to attach the runner to the agent for this. Aiden already knows which runner the integration uses. Attach the runner separately only if you also want the agent to run its own commands, such as kubectl, on that machine.

Step 4: Try it

Ask the agent a question that needs your tool. For example:

"Show me the error rate panel from the checkout dashboard in Grafana for the last hour."
"List the topics on prod Kafka and flag any consumer group with lag over 10,000."

Then check that the answer used real data. In Audit Logs or the execution history you will see the integration's tool call and the runner that handled it.

Keep it safe

Start read-only. Give the integration a token that can look but not change anything. Upgrade only when you have a clear need.
Use separate runners for separate environments. One runner for production, another for staging, so a single runner never holds every credential.
Add policies to the agent. Block or require approval for risky actions with Policies and Approvals. Policies apply when an agent uses a tool, not when you click Test Connection.
Avoid "always allow" for everything. If you need unattended runs, auto-approve only the specific tools and actions you trust.
Name integrations clearly. prod-kafka tells you more than kafka1 when you read audit logs.
Treat the runner token like a password. Revoke and replace it if it leaks.
Pin and upgrade on purpose. Run a known-good runner version in production and upgrade when you choose to.

Troubleshooting

What you see	What to try
You cannot pick the runner, or it says it can't run integrations	Make sure the runner is online and on a supported version. On Docker, start it with `--sidecar-runtime=docker`.
Test Connection fails the first time	The runner may still be downloading the integration image. Wait a minute and retry. Pre-download images on busy runners.
Test Connection fails with a network error	Check the tool's address from inside your network. On Docker, `localhost` means the container, not your host; use a real hostname or `host.docker.internal`. Check firewalls and TLS certificates.
Test Connection works, but the agent never uses the tool	Confirm the integration is attached to the agent. Try naming the tool in your question, for example "using prod Grafana".
A policy did not block Test Connection	This is expected. Policies apply to agent tool use. Test them with a real agent request.
The runner cannot download images	Make sure the runner can reach your image registry. For private or air-gapped registries, see the reference below.

Runner settings reference

Most installs never need these. Use them for a private image registry or a proxy.

Connection and commands

Value	Default	Description
`runner.mothershipUrl`	`https://cloud.stackgen.com`	Address of Aiden that the runner connects to.
`runner.token`	`""`	Runner token beginning with `sg_aios_`. The chart stores it in a Kubernetes Secret.
`runner.existingSecret`	`""`	Name of an existing Kubernetes Secret that holds the runner token. Use this instead of `runner.token` to keep the token out of Helm values.
`runner.allowedClis`	`kubectl,helm,aws,gcloud,az,gh`	Command-line tools the runner may run. Shells and interpreters stay blocked unless you allow them.
`runner.strictSandbox`	`false`	Blocks shell characters such as `$`, `>`, `;`, and `&` in commands.

When you set more than one CLI with Helm's --set, escape the commas:

--set 'runner.allowedClis=kubectl\,helm'

Integrations and private registries

Value	Default	Description
`runner.integrationSecrets`	`{}`	Advanced. Maps an integration type to a Kubernetes Secret in the runner namespace. Aiden normally sends saved credentials with each request, so leave this empty.
`runner.sidecarImageRegistry`	`""`	Pulls integration images from this registry instead of the public one. Use it for private or air-gapped registries.
`runner.sidecarImages`	`{}`	Sets a full image reference for specific integration types. Takes priority over `runner.sidecarImageRegistry`.
`runner.sidecarImagesRequireLocal`	`false`	Refuses public images unless you set a private image above.

Scheduling

These apply to the runner and to the helper containers it starts.

Value	Default	Description
`global.scheduling.nodeSelector`	`{}`	Node labels that decide where the runner and its helpers run.
`global.scheduling.tolerations`	`[]`	Tolerations for the runner and its helpers.
`nodeSelector`	`{}`	Chart-level node selector. Replaces `global.scheduling.nodeSelector` when set.
`tolerations`	`[]`	Chart-level tolerations. Replace `global.scheduling.tolerations` when set.

Proxy and trusted certificates

Value	Default	Description
`proxy.enabled`	`false`	Sends the runner's outbound traffic through an HTTP or HTTPS proxy.
`proxy.existingSecret`	`""`	Kubernetes Secret with `HTTP_PROXY`, `HTTPS_PROXY`, and optionally `NO_PROXY`.
`trustBundle.enabled`	`false`	Mounts a PEM certificate bundle so the runner trusts your internal certificates.
`trustBundle.existingConfigMap`	`""`	ConfigMap with the certificate bundle. Do not combine with `trustBundle.existingSecret`.
`trustBundle.existingSecret`	`""`	Secret with the certificate bundle. Do not combine with `trustBundle.existingConfigMap`.

Kubernetes access

By default the runner gets read-only access to common resources across the cluster, never to Kubernetes Secrets. Turn on namespace mode to limit it to its own namespace.

Value	Default	Description
`rbac.createClusterReadRole`	`true`	Creates cluster-wide read-only access when namespace mode is off.
`rbac.rules`	`[]`	Extra rules added to the cluster-wide role.
`rbac.namespaced.enabled`	`false`	Limits access to the install namespace and turns off cluster-wide access.
`rbac.namespaced.createReadRole`	`true`	Adds default read-only rules in the namespace, excluding Secrets.
`rbac.namespaced.rules`	`[]`	Extra rules added to the namespace role.

Example that limits the runner to read-only access in its own namespace:

runner:
  mothershipUrl: https://cloud.stackgen.com
  existingSecret: aiden-runner-token
  allowedClis: kubectl

rbac:
  namespaced:
    enabled: true

Remote Runners: register and manage runners
Integrations: connect tools and attach them to agents
Supported Integrations: which tools are available
Policies and Approvals: control what agents can do
Audit Logs: review what ran
Integrations for SRE: use in-network tools during investigations

What you can do with it​

How it works​

Before you begin​

Step 1: Install a runner in your network​

Step 2: Connect your tool through the runner​

Step 3: Give an agent access​

Step 4: Try it​

Keep it safe​

Troubleshooting​

Runner settings reference​

Connection and commands​

Integrations and private registries​

Scheduling​

Proxy and trusted certificates​

Kubernetes access​

Related pages​