Agent runtimes
The runtime is the software that does an agent’s thinking. You choose one when you create an agent, on the Hosting step, and you can switch it later. Whichever you pick, the agent keeps the same identity, memory, channels, and credit pool.
Available runtimes
Section titled “Available runtimes”The create wizard offers these runtimes on both managed and self-hosted agents:
| Runtime | Kind | Models | Status |
|---|---|---|---|
| OpenClaw | Provider-backed | Any provider Alfe offers | Available (default) |
| Hermes | Provider-backed | Any provider Alfe offers | Coming soon |
| Claude Code | Terminal | Anthropic | Available |
| Codex | Terminal | OpenAI | Preview |
| Gemini CLI | Terminal | Preview | |
| Grok Build | Terminal | xAI | Preview |
Hermes appears in the wizard as Coming soon and can’t be selected there yet. A Preview runtime is selectable and labelled as a preview. If the wizard can’t load the runtime list, it shows only OpenClaw and Claude Code.
Provider-backed runtimes
Section titled “Provider-backed runtimes”A provider-backed runtime runs its own agent loop against whichever model you configure. You can move between models and providers without changing runtime, and your organization can restrict them with an approved-model policy.
Model usage goes through Alfe’s model routing and draws on your credit pool. To use your own provider account for a provider, bring your own key.
Terminal runtimes
Section titled “Terminal runtimes”A terminal runtime drives a provider’s official coding CLI once per turn, through an Alfe host that bridges it to chat and your channels. Choose one when you want that provider’s own coding agent, with Alfe’s identity, memory, and channels around it.
The CLI only speaks to its own provider, so the agent’s model picker only lists that provider’s models.
How runtimes are billed
Section titled “How runtimes are billed”A terminal agent uses the first of these sources it finds:
- Your stored credential. A key you save on the agent. Usage bills to your own provider account.
- The machine’s CLI login. Self-hosted only. Usage bills to whoever is signed in on that machine.
- Alfe credits. Usage goes through Alfe’s model proxy and draws on your credit pool. No key is needed.
The dashboard shows which source is active, for example Using Alfe credits. A managed agent never uses a machine login. If a stored key is refused, for example because you revoked it, the dashboard flags it so you can replace it.
Add a credential
Section titled “Add a credential”Open the agent’s Settings tab, or use the setup screen right after you create it. Each runtime takes one kind of credential:
| Runtime | Credential |
|---|---|
| Claude Code | A Claude subscription token or an Anthropic API key |
| Codex | An OpenAI project API key. Admin keys are refused |
| Gemini CLI | A Google API key |
| Grok Build | An xAI API key |
Alfe encrypts the credential for that one agent and only shows a mask afterwards. It refuses a key that clearly belongs to another provider.
To get a Claude subscription token, run claude setup-token in a terminal on any
machine with Claude Code installed, then paste the token it prints.
Sign in with a machine login
Section titled “Sign in with a machine login”On a self-hosted agent with no stored credential, sign in to the provider’s CLI on that machine, and the agent uses that login.
Setup installs its own copy of Codex, Gemini CLI, or Grok Build inside Alfe’s folder,
and leaves any copy you installed alone. When an agent uses your login, its Alfe chats
appear in your CLI’s history on that machine.
alfe remove cleans up those chats.
Claude Code is installed only if claude is missing. If it’s already on the machine,
setup uses that copy.
Next steps
Section titled “Next steps”- Switch an agent’s runtime and see what carries over.
- Connect your Claude Code if you want Alfe’s tools in your own terminal sessions.
- Read how model billing works.