AlfredOS

An open-source, self-hostable, multi-user, multi-persona, security-hardened agentic OS.

Status: Pre-implementation. The design is in PRD.md; the operating manual for AI agents working in this repo is in .rulesync/rules/CLAUDE.md.

Community: Join the AlfredOS Discord to ask questions, share builds, or follow development.

What is AlfredOS?

AlfredOS is a long-lived agentic runtime that hosts AI personas — specialized agents with their own purposes — and lets them:

• Converse with users across pluggable platforms (Discord + Telegram + TUI for MVP).
• Share multi-layered memory (working, episodic, semantic, vector, knowledge graph) per user, with auto-save and auto-recall.
• Coordinate with each other, with explicit safety rails (loop detection, budget caps, audit visualization).
• Extend themselves with new skills under a reviewer-gated change process — never validating their own work.
• Run continuously as a bounded autonomous OODA loop, with full audit trail and one-command rollback.

AlfredOS is hardened from day one against prompt injection, credential leakage, and PII exfiltration. Trust tiers, a dual-LLM split, a capability-gated tool layer, outbound DLP, secret brokering, canary tokens, and a cross-provider reviewer agent are all part of the MVP — not later additions.

Alfred (no "OS") is the name of the default persona — the head butler — who ships enabled out of the box. Specialist personas (Lucius, Oracle, Diana) are bundled as examples; operators enable them as needed.

Quickstart

Not yet implemented. Target experience for v0.1:

git clone https://github.com/alfred-os/AlfredOS
cd AlfredOS
bin/alfred-setup.sh        # macOS/Linux; on Windows, run inside WSL
docker compose up -d
alfred user add --authorization operator --name "Your Name"   # one-time
alfred chat                 # start a TUI conversation

docker compose up -d now starts alfred-core as a long-running daemon
(alfred daemon start, restart: unless-stopped) — earlier releases ran it as a
one-shot command runner. One-off subcommands still work via
docker compose run --rm alfred-core <cmd> (migrate, user add, chat, …) because
run overrides the service command. Run bin/alfred-setup.sh before
docker compose up -d: it seeds the audit.hash_pepper and provisions secrets the
daemon requires to boot. Skip it and the daemon refuse-boots and, under
restart: unless-stopped, crash-loops.

docker compose up -d also starts alfred-gateway — the always-up resumable front
door that holds an alfred chat session across a core restart. As of this release the
gateway links to the core: the daemon binds comms-tui.sock on the shared
alfred_run volume and the gateway dials it (its compose-internal
alfred-gateway:9464/metrics gateway_core_link_up gauge reads 1 once both are up;
see ops/prometheus/prometheus.yml). Note: the alfred_run volume inherits ownership
from the image on first creation; if you are upgrading an older deployment that
already has an alfred_run volume with the wrong owner, run
docker compose down && docker volume rm <project>_alfred_run before up -d so it is
re-created owned by the alfred user.

AppArmor hosts (Ubuntu 23.10+ and other userns-restricted Linux): the dual-LLM
quarantine child runs under bubblewrap, which builds an unprivileged user namespace.
On hosts with kernel.apparmor_restrict_unprivileged_userns=1 (the modern Ubuntu
default) the kernel refuses that namespace unless the container runs under an AppArmor
profile carrying userns,. bin/alfred-setup.sh loads the bundled
docker/apparmor/alfred-bwrap profile for you. If you run docker compose directly
(skipping the setup script), load it first or alfred-core crash-loops with
bwrap: No permissions to create new namespace:

sudo apparmor_parser -r docker/apparmor/alfred-bwrap

Run all docker compose commands from the repository root: the compose
security_opt: seccomp=docker/seccomp/alfred-bwrap.json path resolves relative to the
compose-invocation directory, not the compose file. macOS and non-AppArmor Linux hosts
need none of this (the security_opt lines are runtime no-ops there). The bundled PBS
interpreter adds roughly +110 MB to the alfred-core image.

Enable Discord (Developer Mode walkthrough)

AlfredOS ships a DM-only Discord adapter hosted by the gateway. Operator
workflow for a fresh deploy:

1. Create a bot in the Discord developer portal. Visit
   https://discord.com/developers/applications, create a new
   application, then create a Bot user under it.

2. Enable the Message Content gateway intent. Bot settings →
   Privileged Gateway Intents → toggle Message Content on. Without
   this, the adapter sees every DM as empty content and never reaches
   the orchestrator.

3. Copy the bot token. Bot settings → Reset Token → copy.

4. Set the token in .env. Open your .env file (copy from
   .env.example if you have not already) and set:

   ALFRED_DISCORD_BOT_TOKEN=YOUR-TOKEN-HERE
   

   The token is read by alfred-core on boot and delivered to the
   gateway-hosted Discord child over fd-3 at spawn time. The gateway
   and child never hold the token in their environment.

5. Invite the bot to a server with the bot scope. AlfredOS only
   reads DMs; you do not need any guild-message permissions yet.

6. Bind your Discord user to the operator identity. In Discord:
   Settings → Advanced → Developer Mode → right-click your user → Copy
   ID. Then on the host:

   alfred user bind --slug <your-operator-slug> --platform discord --platform-id <snowflake>
   

   The setup script offers an interactive prompt for this in its final
   step.

7. Start the gateway.

   docker compose up -d alfred-gateway
   

8. Verify the adapter is ready. Once the gateway is up, run:

   alfred gateway adapters --wait-ready discord
   

   This polls until the Discord adapter reports ready or the timeout
   expires. Exit 0 means the adapter reached on_ready and is
   accepting DMs. Then send the bot a DM from your Discord account; the
   round-trip lands through the orchestrator with audit + budget +
   episodic memory + DLP all in place.

Secrets file — permission propagation matrix

~/.config/alfred/secrets.toml is plaintext for Slices 2 and 3.
ADR-0012 documents this as
a known risk; secrets management hardening (containerised secret broker)
ships in Slice 4 per
ADR-0015.
In the meantime:

• macOS: Docker Desktop maps the host file's uid/gid to the
  container uid/gid directly; chmod 600 on the host applies inside
  the container too. The setup script runs export UID GID because
  macOS bash 3.2 does not export UID by default.
• Linux: user: "${UID:-1000}:${GID:-1000}" in
  docker-compose.yaml resolves to the operator's real uid/gid; the
  bind-mount's chmod 600 is enforced by the kernel exactly as on the
  host.
• WSL2: same as Linux, with the caveat that running docker compose
  from PowerShell (vs wsl) sees a different uid namespace. Run the
  setup script from inside WSL to keep the perms consistent.

Backup-vector reminder: if you back up your ~/.config with
restic, borg, or similar, exclude ~/.config/alfred/secrets.toml
or the backup will contain plaintext API keys. The ALFRED_DISCORD_BOT_TOKEN
lives in .env (not in secrets.toml); exclude .env from any backup
that should not retain plaintext credentials. The containerised secret
broker lands in Slice 4; until then, the operator owns both exclusions.

Configuration

Operator-facing environment variables live in .env.example;
copy it to .env and edit. The Slice-3 trust-boundary section documents the
plugin-launcher, capability-gate, and supervisor knobs (sandbox policy
directory, plugin UID, perf-gate force-run, redis maxmemory, state-git path).

Gate selection

The capability gate has two implementations: RealGate (Postgres-backed)
and DevGate (fail-open stubs, development-only). Selection is effectively
opt-out of DevGate: only ALFRED_ENV=development (or unset/empty/whitespace,
which short-circuits the bootstrap to DevGate) selects the stub. Anything else
— including typos — falls through to RealGate:

This means a typo in a production deployment safely falls through to
RealGate. The matching startup log event (bootstrap.gate_selected,
INFO-level) carries the exact env value the bootstrap read so an operator
who set ALFRED_ENV=prod (instead of production) can confirm which gate
they ended up on. The plugin runbook
(docs/runbooks/slice-3-plugins.md)
walks through the full Slice-3 deployment, including the launcher and the
supervisor.

Design

See PRD.md for the full design, including:

• Architecture overview
• The 7 capability pillars + persona system
• Security model and prompt-injection defenses
• Memory model
• Reviewer-gated self-improvement
• Token caching and cost control
• Deployment and self-healing
• MVP scope vs. roadmap

Contributing

Contributions welcome. Read CONTRIBUTING.md and our CODE_OF_CONDUCT.md. Contributions are licensed under the project's Apache-2.0 license.

For Python work specifically: docs/python-conventions.md is the canonical reference (tooling, types, errors, async, testing, security, i18n). AI agents should dispatch the alfred-python-developer subagent, which applies it without being asked. The docs/adr/ directory holds the Architecture Decision Records that explain why the conventions look the way they do. The most recent — ADR-0014: pluggable hooks for every action — records the Slice 2.5 hooks subsystem.

If you (or an AI agent) are contributing to this repository, also read .rulesync/rules/CLAUDE.md for repo conventions, security rules, and the self-improvement process.

Security

If you have found a security vulnerability, do not open a public issue. Use GitHub Security Advisories to report privately. See SECURITY.md for details.

License

AlfredOS is licensed under the Apache License, Version 2.0. See the LICENSE and NOTICE files for the full terms.

Plugins communicate with the core via the MCP subprocess boundary (stdio / HTTP) and are not considered derivative works; plugin authors may license their work however they choose.