Connect an agent

Step 2 of 3. Two to three minutes of your time; on the first run the app spends a few more preparing its local runtime. At the end your machine is listed in HolyCode under Agents, with a model and a channel connected.

What you do

HolyAgent is the agent on your machine and the only thing installed on your side. You sign in to it with the same HolyCode ID as the workspace, and the app registers the machine under your account by itself: there is no separate key to issue or paste.

If the machine should also build your code projects, that is a separate small install, a runner. It is added from Builds with one command and runs alongside the app.

Steps

1. Download HolyAgent for Mac (Apple Silicon) and open it.
2. Sign in with HolyCode ID. The app shows a code and opens HolyCode ID in your browser: sign in there with your workspace account, check that the browser shows the same code and confirm.
3. The setup wizard starts. For a first agent the defaults are right:
   • Set up a new runtime and the profile Local runtime + Daenerys registration: the agent runs on this machine and is registered under your account. The account comes from your HolyCode sign-in; the wizard asks for no key.
   • Install mode Docker (recommended): the app installs Docker Desktop if needed and builds its containers. This is the part that takes a few minutes.
   • The agent’s name, mission and look, then one or more roles from the catalog or a role of your own.
   • At least one AI model: an API key, OAuth or a CLI sign-in for a cloud provider; local Ollama and LM Studio are already wired in. The key stays on the machine.
   • The environment check installs missing tools. Secure Tunnel and Public Domain are optional.
   • Review & Complete.
4. In HolyCode open Agents: the machine is there as your agent.
5. In the agent panel open Communication channels and connect the first one: Telegram is the fastest to try; WhatsApp, Instagram and voice work the same way, the panel shows what each needs.

If you already have an agent and want this app to open it instead of setting up a new one, choose Use configured agent runtime on the first step of the wizard.

Screenshot: HolyCode ID sign-in and the machine under Agents — TODO

Let the machine take builds

Builds of code projects run on runners. A runner is HolyAgent in build mode: no window, a background service in your user session.

1. In HolyCode open Builds → Add → Runner, or + Runner on the Runners tab. The wizard has three steps:

   • Machine: Mac (macOS) or Linux server, and the name the runner will have in Builds.
   • Abilities: which builds the runner takes (macOS scripts, Xcode, Docker, Developer ID signing and so on) and how many at once.
   • Install: press Issue key. The key is one-time, valid for 24 hours and works only for this runner.

2. On the Mac open Terminal as the user who will build, without sudo, and paste the command from the wizard (Copy command). It looks like this:

   curl -fsSL https://…/api/runners/install.sh | bash -s -- --key denroll_… --name "Office mini"

   The script checks the machine (it needs Python 3.12 from Homebrew and git, and tells you how to install what is missing), registers the runner and installs it as the LaunchAgent org.holycode.ci-runner.

3. Watch the wizard: the status changes from “Waiting for the first signal from the machine…” to Online, and the runner appears on the Runners tab.

The runner and the HolyAgent app live side by side on one Mac: the runner has its own LaunchAgent, its own folder (~/.holycode-ci/holyagent-runner) and port, and leaves the app and other LaunchAgents alone. Running the same command again updates the runner; its registration stays. The script is Mac-only for now: for a Linux server the wizard points to the manual setup.

A key that is issued but not installed yet sits on Runners as a card marked “awaiting install”: there you can show the command again or Revoke the key.

Screenshot: the “+ Runner” wizard and the runner online — TODO

What you have

• Your machine under Agents in HolyCode, with a model and a channel connected.
• If you added a runner: it is Online under Builds → Runners and takes the builds that match its abilities.

If something is off

• Sign-in stops at a second factor: account owners and administrators need a passkey or an authenticator app code; add one in your HolyCode ID profile and sign in again.
• The code has expired: start signing in again.
• The machine is not under Agents: on the wizard’s Authentication step the account you are signed in as must be shown; if it says no session was found, sign in to HolyCode and go through the step again. The Local standalone profile does not register the machine at all.
• The runner command rejects the key: the key is used, expired or revoked; issue a new one in Builds → Runners → + Runner. A key issued for a Linux server does not fit a Mac: choose Mac (macOS) in the wizard.
• The script asks for Python or git: install what it names (brew install python@3.12, xcode-select --install) and run the same command again.

An agent for Workforce on a server without a window is connected differently, with a one-time key from Workforce → Nodes: see Workforce.

Next

First message and approval: give the agent a task and approve its first outbound message.