Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Enabling auth orphans pre-existing agents, collections and skills (root user bucket)

Abierto
  • ¿Algo no está bien?
#12,665 2 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
go
Área
authentication, backend

Línea de trabajo

Start with core/services/agentpool/user_storage.go, where the empty user ID resolves to the base directory, then getUserID in core/http/endpoints/localai/agents.go. Step 1 is the narrowest first change: at startup, when auth is enabled and the root bucket holds agents, collections or skills, log a warning with the counts and a docs pointer. Steps 2 and 3 (admin listing, the LOCALAI_AUTH_LEGACY_OWNER migration) touch agent_pool.go and the collections and skills services, so they need maintainer direction first. Done means the warning appears in the logs in that state and not otherwise.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Is your feature request related to a problem? Please describe.

When an existing instance turns on LOCALAI_AUTH, everything that was created while auth was off stays in the
root bucket (userID == "") and becomes unreachable over the API — for every user, including admins.

What happens, per resource:

  • Agents. UserScopedStorage.resolve("") maps the empty user to the base directory
    (core/services/agentpool/user_storage.go), and with auth on every request carries a real user ID
    (getUserID in core/http/endpoints/localai/agents.go). GET /api/agents therefore never lists the legacy agents,
    and ?all_users=true does not include them either. The agents are still started by pool.StartAll(), but their
    LLM calls fail with 401 when their api_key is empty and LOCALAI_AGENT_POOL_API_KEY is unset. They keep running
    (including periodic_runs) without anyone being able to see, edit, pause or delete them.
  • Collections, skills / git repos, tasks / jobs, outputs. Same pattern: CollectionsBackendForUser,
    SkillsServiceForUser and the job service fall back to the root instance only for userID == "", so after the switch
    users get a fresh, empty users/<uid>/… area.
  • Agent state (character, scheduler state, long-term memory) has no API at all, so it cannot be exported before
    the switch either.

There is no startup message about it, and nothing in the docs says what happens to existing data. On our instance
(8 agents, about 100 collections, a few hundred thousand chunks) this would have looked like "all data gone" right
after enabling auth.

Reproduction (no models needed):

  1. Start LocalAI without auth, create an agent and a collection (POST /api/agents, POST /api/agents/collections).
  2. Restart with LOCALAI_AUTH=true and LOCALAI_ADMIN_EMAIL=<you>, register as that admin.
  3. GET /api/agents and GET /api/agents?all_users=true with the admin key: the agent is missing.
    GET /api/agents/collections: the collection is missing. The agent still shows up in the logs as running.

Related: re-creating the agents by hand under the admin works (POST /api/agents with the old config), but every
create or update without api_key auto-generates a new agent:<name> key that inherits the owner's role
(CreateAgentForUser / UpdateAgentForUser / ImportAgentForUser in core/services/agentpool/agent_pool.go). For a
migration done by an admin, that gives every migrated agent an admin-level key, and repeated updates pile up keys.
Passing an explicit api_key avoids both, but that is not obvious.

Describe the solution you'd like

Three steps, each useful on its own:

  1. Startup warning. When auth is enabled and the root bucket is not empty, log a warning with the number of root
    agents / collections / skills and a pointer to the docs. Cheap, and it turns a silent loss into a visible decision.
  2. Admin visibility of the root bucket. Show it to admins as an "unowned" group: ?all_users=true includes root
    agents and collections under a reserved owner (e.g. "" → "unowned"), the admin UI lists them, and admins can
    export (GET …/config, the existing agent export) and delete them. Read/export/delete only; no running as another
    user.
  3. Opt-in migration: LOCALAI_AUTH_LEGACY_OWNER=<email or user id>. On startup with auth on, move the root bucket
    once to that user's area (agents, collections, skills, tasks, outputs, agent state), write a marker so it never runs
    twice, and log what was moved. If the user does not exist yet, skip and warn. Agents moved this way keep an
    explicitly configured api_key; for empty ones the migration does not auto-generate an owner key but leaves
    them on LOCALAI_AGENT_POOL_API_KEY and warns, so a migration by an admin never mints admin-level agent keys.

Docs: a short section in the auth docs ("Enabling auth on an existing instance") covering the root bucket, the
bootstrap rule (the first registered user becomes admin, also in invite mode, unless LOCALAI_ADMIN_EMAIL is set),
the recommended order, and the api_key behaviour of agent create/update.

Describe alternatives you've considered

  • Re-create everything by hand under the admin via the API. That works for agent configs and lets us re-ingest
    collections, but agent state and long-term memory are lost, and it needs care with api_key (see above).
  • Keep auth off and put a reverse proxy with SSO in front. That's what we do today, but it gives no per-user
    separation inside LocalAI, which is the reason to use LOCALAI_AUTH in the first place.
  • Moving files on disk from the base directory to users/<uid>/ by hand. Possible, but it depends on internal layout
    details, so it is not something users should have to do.

Additional context

Found while testing a switch from an external UI to LocalAI's built-in auth on a copy of a production instance
(agent pool in LocalAGI mode). Happy to send a PR for step 1 (and the
docs) first, then 2 and 3 if the direction is fine with you.

AI-assisted draft (Claude Code), reviewed and submitted by the reporter.

Lenguaje dominante
Go
Estrellas
49.5k
Forks
4.5k
Merge medio
23 h 16 min
PR fusionados (30 d)
378

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de mudler/LocalAI

Todos los issues de mudler/LocalAI

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.