← Back to all guides

By hand

MarkdownOpen in ClaudeOpen in ChatGPT

At the end, the runner is set up from files you wrote yourself, with the same result as the portal's line and the runner's page. Use it to see every setting, or when your company wants each line reviewed.

At a glance

Time: 20 minutes.

What you need:

Steps:

  1. Download the files
  2. Write runner.env
  3. Start the runner and sign it in
  4. Engines, GitHub and a workspace from the terminal
  5. A permanent address
  6. Slack from slack.env

Run every command in the loopgate folder. A line in a file always wins over the runner's page.

Steps

  1. Make the folder and download the kit's files.

    mkdir -p ~/loopgate && cd ~/loopgate
curl -fsSLO "https://loopgate.dev/runner/{compose.yaml,runner.env.example,slack.env.example}"
cp runner.env.example runner.env && chmod 600 runner.env

  2. Fill in runner.env (nano runner.env; save and leave with Ctrl+O, Enter, Ctrl+X):

    • LOOPGATE_CONTROL_PLANE: keep https://app.loopgate.dev.
    • LOOPGATE_INSTALL_TOKEN: delete the line to sign in with a device code in step 4, or paste a token from the portal's Devices → Add a runner and skip step 4.
    • LOOPGATE_RUNNER_NAME: the name on the portal's Devices page. Set it; otherwise the page shows the container's id.
    • LOOPGATE_RUNNER_URL: a permanent address (step 7). Leave it out for the temporary one.
    • OPENAI_API_KEY, ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN: an API key instead of signing in to a subscription.
    • GH_TOKEN, the three GIT_CONFIG_ lines and the GIT_AUTHOR_/GIT_COMMITTER_ names and emails: a GitHub token and the identity commits carry, instead of Settings → GitHub.

  3. Start it.

    docker compose up -d

    You should see: the image download (about 170 MB the first time), then each container Started.

  4. Sign the runner in to your org.

    docker compose exec runner loopgate login --no-open

    You should see: Open <address>, Code: … and Waiting for confirmation in your browser. Open the address on your laptop, sign in as an owner or admin and enter the code; the box then says Signed in as <your email>.

  5. Install and sign in to engines from the terminal. Codex and Claude Code print an address and a code to open on your laptop; pi opens its own screen, where you choose Trust (this session only), type /login openai-codex (choose Device code login) or /login anthropic, then /quit.

    docker compose exec runner loopgate engines install codex
docker compose exec -it runner loopgate engines login codex
docker compose exec runner loopgate engines install claude-code
docker compose exec -it runner loopgate engines login claude-code
docker compose exec -it runner pi

    In pi, /model sets the model a step on pi runs when nobody picked one. The copilot picks GPT-6 Luna by itself.

  6. After a change to runner.env, restart the runner.

    docker compose up -d runner

  7. For a permanent address, follow Cloudflare Tunnel steps 1 to 7 (its token goes in tunnel.env) or Tailscale steps 1 to 5, then put the address on the LOOPGATE_RUNNER_URL line, with no slash at the end, and restart (step 6).

  8. For Slack from a file, create the app as in Connect Slack steps 2 to 4, then cp slack.env.example slack.env && chmod 600 slack.env and fill it in:

    • SLACK_APP_TOKEN and SLACK_BOT_TOKEN: the xapp- and xoxb- tokens.
    • LOOPGATE_SLACK_WORKSPACE_ID: the T… id in your Slack workspace's web address.
    • LOOPGATE_SLACK_MEMBERS: <Slack id>:<member id> pairs separated by commas. docker compose exec runner loopgate team lists the member ids; a Slack id is under Copy member ID on a person's profile.
    • LOOPGATE_SLACK_REPO: the workspace every task works in, by name or as /repos/<name>.
    • LOOPGATE_SLACK_MAX_COST_USD and LOOPGATE_SLACK_MAX_HOURS: the most one task may spend.
    • LOOPGATE_RUNNER_URL: the runner's address, for the thread's links.

    Then docker compose up -d slack. A slack.env with SLACK_APP_TOKEN wins over Settings → Slack.

Check

docker compose exec runner loopgate whoami
docker compose logs runner slack

You should see: Signed in as <your email> with your org, Runner ready at https://…, and with a slack.env, Loopgate Slack worker is connected for T….

Next

Open the runner from the portal's Devices page. Anything you left out of the files, the runner's page still sets: Engines, GitHub and your repository.

If something is off

  • <NAME> is required. or <NAME> must be a positive number. A line in slack.env is empty or wrong. Fix it, then docker compose up -d slack.
  • LOOPGATE_SLACK_MEMBERS must read U0123:mem_abc,U0456:mem_def. The people line has a typo.
  • Ignoring Slack events from workspace T…. The app is installed in another Slack workspace than LOOPGATE_SLACK_WORKSPACE_ID.
  • Anything else. Update, back up, fix says what each line means.