Install

This page condenses INSTALL.md. Budget about 30 minutes on an already-provisioned dev machine, or 60 to 120 minutes for a fresh laptop, server, or dedicated agent box. For the full doc with every troubleshooting case, read it on GitHub.

Recommended: Install Alfred Desktop

Alfred Desktop is the native Mac/Linux starting point for most local installs. It watches the fleet, reviews plans, checks memory candidates, runs safe local repairs, detects existing configuration, and starts or reconnects to the local runtime. It is the full local installer and control surface over the same Alfred core used by the CLI.

1. Download the signed Mac package or Linux build from Download.

2. Open Alfred Desktop and choose Install or repair in Setup.

3. Setup bootstraps dependencies, seeds the full built-in fleet, deploys the local CLI/agents into ~/.alfred, installs first-party starter skills, attempts the pinned code-memory doctor, starts alfred serve, and continues through GitHub, engine, repo scope, roster naming, optional Slack, and in-app repair/status checks.

4. If you prefer to start the API manually later, run:

   alfred serve --port 7010 --no-browser

For source builds:

cd clients/desktop
npm install
npm run tauri dev

The desktop app reads the same $ALFRED_HOME state and GitHub records as the CLI. You can still run Alfred entirely from the terminal when you are setting up a server, CI-like host, or headless agent box.

CLI-only install

Use this path when you deliberately want no GUI, are setting up a headless host, or are developing Alfred itself.

Source checkout path:

git clone https://github.com/luminik-io/alfred.git ~/code/alfred
cd ~/code/alfred
bash install.sh
gh auth login                     # GitHub
claude auth login                 # Claude Code auth
./bin/alfred-init.py              # choose agents, repos, schedule, and Slack

macOS Homebrew path, if you prefer package-manager installs:

brew tap luminik-io/alfred https://github.com/luminik-io/alfred
brew install alfred-os
alfred-install
gh auth login                     # GitHub
claude auth login                 # Claude Code auth
alfred-init                       # choose agents, repos, schedule, and Slack

The Homebrew formula installs the latest tagged release and puts the Alfred commands on your PATH: alfred, alfred-init, alfred-install, alfred-deploy, and alfred doctor. Use the source checkout path when you want main, framework edits, or Linux.

Full fleet for one repo or an explicit comma-separated repo list:

./bin/alfred-init.py \
  --non-interactive \
  --agents all \
  --repos your-org/api,your-org/web \
  --slack-webhook skip

This is the zero-guess path for a single operator, a small team, or an AI coding tool setting up one or more explicit repos. It assumes GH_ORG is set, gh auth login has completed, and claude has completed first-run auth. The repo owner must match GH_ORG; the runtime agents store the bare repo name in $ALFRED_HOME/.env and build GH_ORG/repo at firing time. The command enables the full engineering fleet using exact installer selectors: planner, architect, senior-dev, reviewer, test-engineer, fixer, triage, e2e-runner, ops-watch, automerge, agent-cleanup, memory-harvest, memory-auto-promote, code-map-refresh, agent-morning-brief, fleet-doctor, fleet-recap-morning, fleet-recap-evening, shipped-summary-daily, and shipped-summary-weekly. Huntress and Gordon self-idle until their target URL or ECS cluster settings exist. It assigns the selected repo list to each repo-operating agent, skips Slack safely, seeds prompt templates into ~/.alfred/prompts/, creates standard GitHub labels on the selected repos, writes launchd/agents.conf, writes the shared scheduler manifest, updates $ALFRED_HOME/.env, runs deploy, and runs doctor. Deploy removes an AMS service only when Alfred’s ownership marker identifies it as managed; custom or operator-owned units stay untouched.

The architect role is enabled in the full fleet and shows as Batman in the default theme. It stays idle until alfred architect setup writes the parent planning repo, approval channel, trusted operator settings, and ARCHITECT_AUTO_EXECUTE=approval-gate. It only acts on approved agent:large-feature parent issues.

For a framework-only install with no agents configured, run bash deploy.sh && ./bin/alfred doctor; doctor should report 0 passed, 0 failed.

Deploy never claims or removes an unmarked AMS service. If one occupies Alfred’s reserved service path, deploy stops with a cleanup instruction instead of leaving a stale daemon running or overwriting operator-owned configuration.

Install With Claude Code or Codex

Claude Code, Codex, or another local coding assistant can drive setup if you give it explicit values and guardrails. Use the copy-paste prompt in docs/AI_ASSISTED_INSTALL.md.

The important rules:

• start with one explicit repo, or one explicit comma-separated repo list
• use the full fleet
• keep Slack skipped unless you paste a webhook
• do not create AWS profiles during first install
• pause for browser auth flows
• run alfred auth status and alfred doctor before trusting scheduled firings

For repo checkout layout, read Workspace patterns.

What install.sh does

Idempotent (safe to re-run). It detects the host OS and picks a lane: Homebrew on macOS, apt on Debian/Ubuntu.

1. Detects the host: macOS (Homebrew) or Debian/Ubuntu Linux (apt). See Linux for the systemd path.
2. Installs the package-manager prerequisites: Homebrew if missing on macOS; on Linux, apt-get installs the base packages.
3. Installs python@3.11, git, gh, jq, node, uv (plus awscli on macOS; install AWS CLI v2 manually on Linux).
4. npm install -g @anthropic-ai/claude-code.
5. Creates $ALFRED_HOME (default ~/.alfred) and $WORKSPACE_ROOT (default ~/code).
6. Seeds $ALFRED_HOME/.env from the template, prompts for GH_ORG, OPERATOR_NAME, OPERATOR_EMAIL.
7. Leaves shell rc files alone. The scheduler, CLI, and native app load $ALFRED_HOME/.env directly.
8. Reports auth status for gh, aws, claude.

What the base installer does not do (deliberately):

• Authenticate gh / aws / claude. Interactive flows you should see.
• Create AWS IAM users, secrets, or Slack webhooks. One-time human decisions.
• Choose which agents should run. Use ./bin/alfred-init.py for that.
• Run deploy.sh. That side-effects the host scheduler (launchd on macOS, systemd --user on Linux); you should know what’s about to load.
• Install a hosted agent gateway, hosted MCP server, or external dashboard. Alfred Desktop installs the local full fleet and first-party starter skills. In the CLI-only path, alfred-init.py --agents all configures the local full fleet; run alfred skills install --starter when you want the first-party starter skills too. Optional vendored and fetched integrations remain explicit operator choices. Redis Agent Memory is provisioned locally for recalled lessons; deploy.sh starts the local service. FleetBrain stays under ALFRED_HOME for review and reliability state.

Non-interactive

For automation:

ALFRED_NONINTERACTIVE=1 \
  GH_ORG=myorg \
  OPERATOR_NAME='Your Name' \
  OPERATOR_EMAIL=you@example.com \
  bash install.sh

Per-stage skips: --skip-brew, --skip-npm.

For alfred-init.py, --agents all is the default full engineering roster. Use --agents starter only for a small lab setup. Use --repos owner/repo for one repo, or --repos owner/api,owner/web,owner/mobile for multi-repo. owner must match GH_ORG.

After install

Point Alfred at your fleet’s Slack channel and (optionally) AWS:

• Slack setup: create the app, mint the webhook.
• AWS setup: IAM-per-agent, Secrets Manager.
• Claude Code and Codex: Pro vs Max sizing, account routing, engine routing.

Then try the fleet safely:

• Tutorial: custom agent in 30 minutes: builds Echo end-to-end after the default fleet is already installed.

Troubleshooting

Full list in INSTALL.md on GitHub. The most common:

• install.sh stops on an unsupported host: the apt lane targets Debian/Ubuntu. Other Linux distros need their packages installed by hand; the framework itself is distro-agnostic once the prerequisites are present.
• claude: command not found from a scheduled agent: the scheduler unit’s PATH doesn’t include the npm global bin. Set CLAUDE_BIN in $ALFRED_HOME/.env.
• gh auth login browser doesn’t open: use the device-code flow: gh auth login --hostname github.com --git-protocol https --web.