Manage Albedo with home-manager #
Use the Albedo module to declare the client, daemon service, and selected settings. Read daemon service ownership before replacing a CLI-installed service.
Add Albedo to your flake inputs, then import its home-manager module:
{
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:
{
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:
{
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.<name>.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:
- Stop the daemon with
albedo daemon --stop, and stop every other Albedo process that uses this home. - Activate your home-manager configuration.
- 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 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:
{
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. typemust bestdioorhttp. Albedo has nossetransport.- An
envorheadersvalue that contains{env:or{file:must be a whole"{env:NAME}"placeholder with a valid variable name, except anAuthorizationheader of exactly"Bearer {env:NAME}". That header becomes the server'sbearerTokenEnvVar, 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
Authorizationbearer header and a differentbearerTokenEnvVarfail 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).
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:
{
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
/mcpstay increds.jsonand override directenvand 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 changescreds.json. - A server you switch off in
/mcpstays off, unless the declaration setsenabled. - Removing a server from
programs.mcp.servers, or turning the integration off, leaves the server andenabled.mcpinextensions.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
commandandurl, the old transport's keys stay. The server still connects, but/mcprefuses 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 for shutdown and kernel
survival limits.
Implementation and verification #
Use these repository sources when changing a declaration or investigating activation:
module.nixdefines Albedo options, MCP translation, service environments, settings preflight, and activation ordering.evaluation.nixevaluates client and service combinations, settings, MCP imports, and generated native declarations.check-home.shexercises 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.nixruns those checks and compares rendered services with the fixtures used by the CLI registration tests.flake.lockpins 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
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 links the optional native procedures and explains their scope.