Skip to content
amahub

Self-hosted runner

Many company tools live behind a VPN: an internal Jira, a wiki on the office network, databases with no public endpoint. A self-hosted runner pool moves session execution inside your network while the control plane — UI, queue, secrets, policies, audit — stays in amahub cloud.

How it works

Section titled “How it works”
  • Your machines run two containers: the runner (the agent sandbox) and its egress proxy. Both talk to the amahub API strictly outbound over HTTPS — there is nothing to open in your firewall.
  • The runner authenticates with an org-scoped token (rt_…). Every API call it makes is pinned to your organization: it can claim only your org’s jobs, post events only to your org’s sessions, and receives only your org’s egress allowlist.
  • With the org switched to Self-hosted, the cloud fleet stops claiming your jobs entirely — sessions wait for your runners.
  • OAuth consent still happens in the user’s browser (which is on your VPN anyway); connector secrets stay in the cloud vault and reach tools through the mcp-proxy, never landing on the runner box.

Install

Section titled “Install”

  1. Admin → Runners → switch Execution to Self-hosted (or do this last) → Create token, name it after the machine (dc-fra-01). The token is shown once.

  2. On a Linux machine with Docker inside your network:

    Terminal window
    git clone https://github.com/amahub/amahub
    cd amahub/mvp/deploy/self-hosted-runner
    cp .env.example .env    # set API_URL and RUNNER_TOKEN
    docker compose up -d --build

  3. Back in Admin → Runners the token shows online within seconds (a heartbeat rides every poll). Run any task — it executes on your machine.

Operations

Section titled “Operations”
Concern Answer
Scale Raise RUNNER_CONCURRENCY, or run the compose on more machines — one token per machine keeps revocation surgical.
Reach internal hosts Add them to EGRESS_EXTRA_ALLOW in the pool’s .env — the local egress proxy enforces the same allowlist+log discipline as the cloud one.
Rotate / revoke Revoke a token in Admin → Runners; the machine loses access on its next poll. Create a fresh token and update .env.
Offline pool If no runner is online, new sessions stay queued (the Runners page warns you). Switch the org back to Cloud to drain through our fleet.
Updates git pull && docker compose up -d --build — the runner is stateless; workspaces persist in the named volume.

Security notes

Section titled “Security notes”
  • The token authorizes runner-plane endpoints only — it cannot read the org’s data, settings or audit trail.
  • Model calls originate from your network (your egress IPs) using the org’s provider key delivered per-job.
  • Everything the runner does is still policy-checked and audited server-side, exactly like cloud runs.

Coming next

Section titled “Coming next”

Cloud Private Link (AWS PrivateLink / Azure Private Link / GCP PSC) for orgs that want cloud execution with private connectivity into their VPC — talk to us if you want early access.