Two parallel activation paths for llama agents (ENABLE_LLAMA_AGENT vs [agents.X] TOML) #846

New issue

Open

opened 2026-04-16 10:03:43 +00:00 by dev-bot · 1 comment

dev-bot commented

2026-04-16 10:03:43 +00:00

Collaborator

Problem

Llama-backed sidecar agents can be activated through two different mechanisms:

Legacy: ENABLE_LLAMA_AGENT=1 env flag toggles a hardcoded agents-llama service block in docker-compose.yml.
Modern: [agents.X] TOML block consumed by hire-an-agent, emitting a service per block.

Neither the docs nor the CLI explain which path wins. Setting both produces a YAML mapping key "agents-llama" already defined error from compose because the service block is duplicated.

Sub-symptom: env-var naming collision

The two paths key secrets differently:

Legacy: FORGE_TOKEN_LLAMA, FORGE_PASS_LLAMA.
Modern: FORGE_TOKEN_<FORGE_USER_UPPER> — e.g. FORGE_TOKEN_DEV_QWEN.

A user migrating between paths ends up with two sets of secrets in .env, neither cleanly mapped to the currently-active service block. Silent auth failures (401 from Forgejo) follow.

Why it bites

New users follow whichever path they read first; the other lingers in .env and breaks the next bring-up.
Reasoning about which agents are actually active requires checking two files plus compose state.
Couples to #845 (profile destruction) and #847 (missing creds) — fixing those without consolidating activation just creates more half-states.

Proposal

Pick the TOML [agents.X] path as canonical.
Remove the ENABLE_LLAMA_AGENT branch and its hardcoded service block from the generator.
Detection of ENABLE_LLAMA_AGENT in .env at disinto up time: decide between
- (a) hard-fail immediately with a migration message, or
- (b) warn for one release, then hard-fail.
  Option (a) is simpler and appropriate since no external consumers depend on this flag.

Acceptance

One documented activation path.
ENABLE_LLAMA_AGENT removed from compose generator; presence in .env triggers a clear migration error.
.env.example and docs/agents-llama.md updated (see doc follow-up issue).

Related: #845, #847.

## Problem Llama-backed sidecar agents can be activated through two different mechanisms: 1. **Legacy:** `ENABLE_LLAMA_AGENT=1` env flag toggles a hardcoded `agents-llama` service block in `docker-compose.yml`. 2. **Modern:** `[agents.X]` TOML block consumed by `hire-an-agent`, emitting a service per block. Neither the docs nor the CLI explain which path wins. Setting both produces a YAML `mapping key "agents-llama" already defined` error from compose because the service block is duplicated. ## Sub-symptom: env-var naming collision The two paths key secrets differently: - Legacy: `FORGE_TOKEN_LLAMA`, `FORGE_PASS_LLAMA`. - Modern: `FORGE_TOKEN_<FORGE_USER_UPPER>` — e.g. `FORGE_TOKEN_DEV_QWEN`. A user migrating between paths ends up with two sets of secrets in `.env`, neither cleanly mapped to the currently-active service block. Silent auth failures (401 from Forgejo) follow. ## Why it bites - New users follow whichever path they read first; the other lingers in `.env` and breaks the next bring-up. - Reasoning about which agents are actually active requires checking two files plus compose state. - Couples to #845 (profile destruction) and #847 (missing creds) — fixing those without consolidating activation just creates more half-states. ## Proposal - Pick the TOML `[agents.X]` path as canonical. - Remove the `ENABLE_LLAMA_AGENT` branch and its hardcoded service block from the generator. - Detection of `ENABLE_LLAMA_AGENT` in `.env` at `disinto up` time: decide between - (a) hard-fail immediately with a migration message, or - (b) warn for one release, then hard-fail. Option (a) is simpler and appropriate since no external consumers depend on this flag. ## Acceptance - One documented activation path. - `ENABLE_LLAMA_AGENT` removed from compose generator; presence in `.env` triggers a clear migration error. - `.env.example` and `docs/agents-llama.md` updated (see doc follow-up issue). Related: #845, #847.