Skip to main content
4 min read

Remote Runners

Remote Runners

Remote runners execute agent tasks inside your own infrastructure. No inbound connections are required. Use them when agents need tools, commands, or secrets that must stay in your network.

This page covers Platform (Aiden) remote runners under Workspace Settings -> Connections -> Remote Runners.

Available for roles: Admin Workspace Admin

Scope: Workspace

Catalog​

The Remote Runners page lists every runner registered for the workspace.

  • Add Runner opens the registration dialog.
  • Search runners and filter by status.
  • Refresh the list and choose which columns to show.
  • Table details typically include runner name and version, secrets mode (Local only or Sync with refs), attachments (agents or apps), capabilities (for example execute_command), and last heartbeat.

Add a remote runner​

Click Add Runner. The dialog title is Add remote runner: Register a runner that executes agent tasks in your infrastructure.

1. Register the runner​

Fill in:

FieldRequiredExample
NameYesdocs-capture-vpc-runner-1 (lowercase letters, numbers, hyphens only)
DescriptionYesDocs capture runner for SRE investigation in Demo Workspace
LabelsNoenv=docs-capture, team=sre
Attach toNoAttach an existing agent or app after creation
Runner secretsNoExpand and bind integration or generic secrets if needed

Then click Generate token. Do not generate a real token on shared stage unless you intend to register a runner; use Cancel after filling fields for docs walkthroughs.

2. Runner secrets (optional)​

Expand Runner secrets (optional) before you generate a token if the runner needs credentials.

info

Secret values are held in memory only. They are never written to disk. Local secrets in your cluster take precedence over any overlapping keys.

  • Integration secrets: One secret per integration type that Vault exposes for your workspace (for example AWS, GitHub, or GitLab), not a fixed shortlist. Choose an integration, select a secret, then Add. Add only what this runner needs. You can attach the same way when you create a runner or later from the runner secrets dialog.
  • Generic secrets: Key-value secrets that are not tied to a provider. Select a secret, then Add. You can add or remove generic secrets from the secrets dialog after create as well.

3. Copy credentials and start the runner​

After Generate token, the dialog shows credentials and install commands.

  • Runner ID: The name you registered (copyable).
  • Token , shown once, store it securely: Copy this immediately. You will not see it again.

Under Start your runner, choose CLI, Helm, or Docker. The page waits for a heartbeat and updates when the runner connects. Click Done when you are finished.

Replace <RUNNER_TOKEN> with the token from the dialog, and use your tenant mothership URL (the same host you use for Aiden, for example https://<tenant>.cloud.stackgen.com or your stage/production URL).

CLI​

Install the CLI with Homebrew if you do not already have it:

brew install stackgenhq/stackgen/aiden-runner

Start the runner with your token:

aiden-runner start \
  --runner-token <RUNNER_TOKEN> \
  --mothership https://<your-aiden-host> \
  --auto-discover

Helm​

helm upgrade --install aiden-runner \
  --repo https://appcd-public-releases.s3.us-east-2.amazonaws.com \
  aiden-runner \
  --set runner.mothershipUrl=https://<your-aiden-host> \
  --set runner.token=<RUNNER_TOKEN> \
  --create-namespace -n aiden-runner

Docker​

docker run -d --name aiden-runner \
  -e STACKGEN_URL=https://<your-aiden-host> \
  -e STACKGEN_RUNNER_TOKEN=<RUNNER_TOKEN> \
  -e AUTO_DISCOVER=true \
  ghcr.io/appcd-dev/stackgen-guild-aiden-runner:latest

4. Confirm the runner is online​

After the runner starts, the dialog status moves from Waiting for runner to connect when a heartbeat is detected. On the catalog page, confirm:

  • Last heartbeat is recent
  • Version is populated
  • Capabilities appear for the runner

Attach runners to agents and apps​

You can attach agents or apps during Add remote runner, or manage attachments later from the catalog. Agents that need private-network tools should use a runner that can reach those systems. See Agents and Integrations.

Last updated on