# Manage Albedo with home-manager Use the [Albedo module](../nix/home-manager/module.nix) to declare the client, daemon service, and selected settings. Read [daemon service ownership](daemon-lifecycle.md#daemon-service) before replacing a CLI-installed service. Add Albedo to your flake inputs, then import its home-manager module: ```nix { imports = [ inputs.albedo.homeModules.default ]; programs.albedo.enable = true; services.albedo.enable = true; } ``` `programs.albedo.enable` adds the client package to your profile. `services.albedo.enable` declares `albedo.service` on Linux or the `systems.albedo.daemon` login agent on macOS. The two enable options are independent. A service alone does not add the client to PATH. `programs.albedo.package` defaults to this flake's joined `albedo` package. `services.albedo.package` defaults to `programs.albedo.package`. To choose a separate daemon package, set `services.albedo.package`. That package must provide `bin/albedo daemon --serve`, including its daemon runtime. No package metadata is required. Ambient `ALBEDO_DAEMON` overrides can still affect packaged startup. The service uses `${home.homeDirectory}/.albedo`. Set `home.homeDirectory` to exactly the value of `$HOME`, without a trailing slash. Equivalent symlinked paths still fail the daemon-home identity check. On Linux, the CLI's `XDG_CONFIG_HOME` must match home-manager's `xdg.configHome`. If unset, the CLI uses `$HOME/.config`. Setting `ALBEDO_HOME` for the CLI selects a different daemon home and service name. It does not change this module's `${home.homeDirectory}/.albedo` declaration. The module creates a missing daemon directory with mode 0700, preserves an existing directory, and keeps data when you disable the service. ## Install skills `programs.albedo.skills` links named skill directories into `~/.albedo/skills` when either the client or service is enabled. Use the same directory sources for other agents to share skills: ```nix { programs.albedo.enable = true; programs.albedo.skills = { review = ./skills/review; changelog = pkgs.writeTextDir "SKILL.md" '' --- name: changelog description: Write a changelog entry for a completed change. --- Describe the user-visible change in one sentence. ''; }; } ``` Each directory must contain `SKILL.md`. Its frontmatter name must match the attribute name. Scripts and other resources remain available beside it. Skill contents enter the Nix store, so keep secrets elsewhere. Albedo also discovers `~/.agents/skills`. You do not need to declare those skills again. A skill in `.albedo/skills` wins over one with the same name in `.agents/skills` at the same scope. Project skills take precedence over both user directories. Run `/reload session` in an existing session after activation to pick up changes, or start a new session. No daemon restart is needed. ## Declare global settings Set `services.albedo.settings` to native JSON objects for your global settings: ```nix { services.albedo = { enable = true; settings = { config.active = "local"; config.providers.local = { extension = "openai"; baseUrl = "http://127.0.0.1:8000/v1"; protocol = "chat_completions"; model = "your-served-model"; }; extensions.enabled.mcp = true; extensions.subagents.maxOpenChildren = 8; capabilities.global.skills."example-skill" = false; picker.thinking = true; }; }; } ``` | Key | File under `${home.homeDirectory}/.albedo` | Native fields | | -------------- | ------------------------------------------ | --------------------------------------------------------- | | `config` | `config.json` | `active`, `providers..baseUrl`, `model`, `protocol` | | `extensions` | `extensions.json` | `enabled`, `subagents`, `mcp.servers`, extension sections | | `capabilities` | `capabilities.json` | `global.skills`, `global.instructions`, `global.mcp` | | `picker` | `picker.json` | `thinking`, `tools`, global UI preferences | These native keys differ from the HTTP API. Session preferences stay in SQLite. The option checks JSON types, not Albedo's schema, so Albedo can still reject a valid JSON value when it reads the file. All declared values enter the world-readable Nix store. Keep credentials in Albedo's credential store. Declared nested values win, undeclared keys survive, and arrays replace existing arrays. Removing a declared key keeps its last stored value. An empty document or a disabled service stops managing the file and leaves it in place. New files use mode 0600. Existing files keep their modes, even permissive ones. ### Activate with the daemon stopped Activation merges into files the daemon also writes, and it does not stop the daemon itself. A running daemon can overwrite the merge, including by replaying its settings journal. To apply settings reliably: 1. Stop the daemon with `albedo daemon --stop`, and stop every other Albedo process that uses this home. 2. Activate your home-manager configuration. 3. If the daemon is not running afterwards, start it with `albedo daemon`. When the service is enabled and activation manages at least one nonempty settings document, its preflight refuses an existing `${home.homeDirectory}/.albedo/.settings-recovery` before the write boundary. It also refuses a dangling symlink at that path. Start Albedo so it finishes recovery, stop it, then activate again. Activation merges one file at a time in alphabetical order. If a later file fails, for example because it holds malformed JSON, the earlier files stay merged and activation stops. Fix the file and activate again. When declarations change, home-manager normally restarts a running service. Reapplying unchanged declarations over interactive edits does not request a restart, so a running daemon can keep cached settings. Restart it with `albedo daemon --stop` and `albedo daemon`. With `systemd.user.startServices = "suggest"` or `false`, run the suggested commands yourself. See [Daemon service](daemon-lifecycle.md#daemon-service) for lifecycle limits. ## Share MCP servers with other clients home-manager's `programs.mcp.servers` declares MCP servers once for several clients. To add them to Albedo's `mcp.servers` in `extensions.json`, set `services.albedo.enableMcpIntegration`: ```nix { programs.mcp = { enable = true; servers = { everything = { command = "npx"; args = [ "-y" "@modelcontextprotocol/server-everything" ]; }; codeberg = { command = "forgejo-mcp"; args = [ "transport" "stdio" "--url" "https://codeberg.org" ]; env.FORGEJO_ACCESS_TOKEN.file = "/run/secrets/codeberg_token"; }; context7 = { url = "https://mcp.context7.com/mcp"; headers.CONTEXT7_API_KEY = "{env:CONTEXT7_API_KEY}"; }; }; }; services.albedo = { enable = true; enableMcpIntegration = true; }; } ``` The import does nothing unless `services.albedo.enable`, `services.albedo.enableMcpIntegration`, and `programs.mcp.enable` are all set. Albedo does not read `~/.config/mcp/mcp.json`, the file `programs.mcp` writes for other clients. A server with `url` becomes an `http` server. A server with `command` becomes a `stdio` server. An `Authorization` header of `"Bearer {env:NAME}"` becomes `bearerTokenEnvVar`, so a token is named once for every client. Other fields, including Albedo's own such as `cwd`, `bearerTokenEnvVar`, `enabledTools`, and `callTimeoutMs`, are copied as written. If at least one server is imported, `enabled.mcp` is set to `true`, so the `mcp` extension is on by default. To keep it off, declare `services.albedo.settings.extensions.enabled.mcp = false`. ### Server names and values Albedo accepts Evaluation fails with a message naming the server when an imported server cannot work in Albedo: - A name must start with a letter or digit, use only letters, digits, `_`, and `-`, and have at most 64 characters. - `type` must be `stdio` or `http`. Albedo has no `sse` transport. - An `env` or `headers` value that contains `{env:` or `{file:` must be a whole `"{env:NAME}"` placeholder with a valid variable name, except an `Authorization` header of exactly `"Bearer {env:NAME}"`. That header becomes the server's `bearerTokenEnvVar`, which Albedo sends as the bearer token; the header is dropped and the other headers arrive as written. Albedo fills no placeholder inside text anywhere else, so `"Bearer {env:TOKEN} extra"` is refused. - A server cannot name two variables for one token: an `Authorization` bearer header and a different `bearerTokenEnvVar` fail evaluation. Albedo sends a literal `env` or header value as written. A whole `"{env:NAME}"` value becomes Albedo's `{ "env": "NAME" }` reference, which reads `NAME` from the daemon's environment when the server connects. The daemon runs under systemd or launchd, not your shell, so variables from your shell profile are not set there. Give the service the variable, for example with `systemd.user.services.albedo.Service.EnvironmentFile` on Linux or `launchd.agents.albedo-daemon.config.EnvironmentVariables` on macOS, or save the secret through `/mcp` instead. If the variable is missing, that server does not connect. A stdio server gets only `HOME`, `PATH`, `TMPDIR`, `TEMP`, `TMP`, and the variables its `env` names, not the rest of the daemon's environment. An `env` entry with `file` runs the server through a script that home-manager generates. The script reads the file each time the server starts, so the secret never enters the Nix store, and `/mcp` shows the script as the server's command. The script runs `cat` from the service PATH. If your home-manager profile does not provide coreutils, add `pkgs.coreutils` to `home.packages`. Ensure `cat` is available before relying on a file-backed variable. A bare `command` such as `forgejo-mcp` is looked up on the same service PATH (see [Tools available to the daemon](#tools-available-to-the-daemon)). ### Override an imported server For the generated declaration, a server under `services.albedo.settings.extensions.mcp.servers` replaces the shared server of the same name. Supply its full definition: ```nix { services.albedo.settings.extensions.mcp.servers.context7 = { type = "http"; url = "https://mcp.context7.com/mcp"; bearerTokenEnvVar = "CONTEXT7_TOKEN"; }; } ``` Values in Albedo's settings use Albedo's native form, such as `env.TOKEN.env = "VARIABLE"`, and are not translated. ### What activation keeps Imported servers merge into `extensions.json` like other declared settings: - Secrets saved through `/mcp` stay in `creds.json` and override direct `env` and header values. A file-backed environment wrapper sets its variables afterwards, so the file values win over saved credentials. To use a saved credential instead, remove the file reference from the declaration and activate again. Activation never reads or changes `creds.json`. - A server you switch off in `/mcp` stays off, unless the declaration sets `enabled`. - Removing a server from `programs.mcp.servers`, or turning the integration off, leaves the server and `enabled.mcp` in `extensions.json`. Delete the server with Ctrl+D in `/mcp`. - Keys you remove from a server stay in the file. If you switch a server between `command` and `url`, the old transport's keys stay. The server still connects, but `/mcp` refuses to edit it. Delete it with Ctrl+D in `/mcp`, then activate again to write it fresh. ## Tools available to the daemon The service PATH includes `home.profileDirectory` and `nix.package` when set. Install the tools the agent needs through `home.packages`. The daemon package provides its own runtime. The service does not inherit your interactive shell's PATH, so migrating from `albedo daemon install` can change which tools it finds. For additional tools, extend the native service environment. On Linux, set `systemd.user.sessionVariables.PATH` and include the profile and system paths you need. On macOS, override `launchd.agents.albedo-daemon.config.EnvironmentVariables.PATH` with `lib.mkForce`. Include your system or Homebrew directories there if needed. These replace the service PATH. Keep the home-manager profile so the daemon can find its tools. ## Migrate an installed service Before enabling the declaration, run `albedo daemon uninstall` with the client that owns your existing service. Then activate your home-manager configuration. CLI-installed and home-manager services have different names. Leaving both registered makes service control ambiguous, so Albedo refuses service mutations. If both are already registered, disable the home-manager service and activate, uninstall the CLI service, then enable and activate the home-manager service. Once home-manager owns the declaration, use home-manager to update or remove it. Albedo refuses `daemon install` and `daemon uninstall` for external declarations. It can start a supported, already loaded idle service and stop its authenticated daemon. It never reloads or bootstraps an external declaration. It reads the loaded registration, not the service file, which must still exist. ## Apply service changes home-manager owns registration and activation. Follow the `systemd.user.startServices` setting of the home-manager version in your configuration. The pinned version defaults to `true`, which uses `sd-switch`. Changed active services normally restart, wanted inactive services can start, and removed active services stop. With `suggest`, run the suggested commands yourself. home-manager can skip reload if the user manager is unavailable. Until the reload, systemd reports `NeedDaemonReload=yes` for a changed unit and Albedo refuses to start it. On macOS, home-manager uses the GUI domain and waits for the Nix store before exec. Its activation handles agent replacement. A disabled launchd override blocks start until its owner or operator resolves the override. Albedo does not change it, and home-manager activation does not guarantee that it is cleared. On macOS, file edits do not change the loaded registration until you activate again. A failed activation can leave the old loaded definition, and Albedo starts what the manager holds. Inspect `albedo daemon status` after a change. Package selection alone does not prove which daemon is running. See [Daemon service](daemon-lifecycle.md#daemon-service) for shutdown and kernel survival limits. ## Implementation and verification Use these repository sources when changing a declaration or investigating activation: - [`module.nix`](../nix/home-manager/module.nix) defines Albedo options, MCP translation, service environments, settings preflight, and activation ordering. - [`evaluation.nix`](../nix/home-manager/evaluation.nix) evaluates client and service combinations, settings, MCP imports, and generated native declarations. - [`check-home.sh`](../nix/home-manager/check-home.sh) exercises generated activation fragments, including existing-file modes, merge precedence, recovery-record refusal, and partial failure. A later file failure leaves earlier file merges in place. - [`check.nix`](../nix/home-manager/check.nix) runs those checks and compares rendered services with the fixtures used by the [CLI registration tests](../cli/internal/loginservice/daemon_selection_test.go). - [`flake.lock`](../flake.lock) pins the home-manager input used for these checks. A consumer can select a different home-manager revision, whose activation behavior must be checked separately. The settings preflight exists only when `services.albedo.enable` is true and the effective settings contain a nonempty document. Declaring no managed settings does not install a universal recovery guard. Keep the daemon stopped while merging files, and do not delete its recovery record by hand. [Runtime settings recovery](../robot-docs/settings.md#persistence-and-recovery) uses the daemon's lock and journal, not the activation merge procedure. Generated-service checks do not exercise every real native-manager behavior. The [daemon lifecycle verification guide](daemon-lifecycle.md#implementation-and-verification) links the optional native procedures and explains their scope.