small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo docs home-manager.md
16 kB · 350 lines
Markdown
at main

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:

  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 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.
  • 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).

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 /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 for shutdown and kernel survival limits.

Implementation and verification #

Use these repository sources when changing a declaration or investigating activation:

  • module.nix defines Albedo options, MCP translation, service environments, settings preflight, and activation ordering.
  • evaluation.nix evaluates client and service combinations, settings, MCP imports, and generated native declarations.
  • 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 runs those checks and compares rendered services with the fixtures used by the CLI registration tests.
  • 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 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.