Codakey
Play
← Back to alfred

How to Deploy & Use alfred

Alfred: Personal Agentic Infrastructure

This guide provides comprehensive instructions for deploying and using Alfred, your self-hosted, always-on personal agentic infrastructure.

Prerequisites

Before installing Alfred, ensure you have the following:

  • Python 3.11+: Alfred is built on Python 3.11 and newer.
  • Agentic Runtime: Alfred connects to an existing agentic runtime. Choose one of the following:
    • Claude Code: Requires claude to be available in your system's PATH.
    • OpenClaw: Requires openclaw to be available in your system's PATH.
    • Zo Computer: Requires a ZO_API_KEY environment variable for HTTP API access.
  • Temporal: Alfred's workflow engine is powered by Temporal. You will need a Temporal cluster running or access to a Temporal Cloud instance.
  • Obsidian: Alfred maintains a knowledge graph in an Obsidian vault. While not strictly a prerequisite for installation, you will need an Obsidian vault for Alfred to operate effectively.
  • Hardware: A Mac Mini, VPS, or personal cloud instance to host Alfred.

Installation

Alfred can be installed directly from PyPI.

  1. Install Alfred:

    pip install alfred-vault

  2. Quickstart Setup: This command will guide you through initial configuration and create necessary files.

    alfred quickstart

  3. Start Alfred:

    alfred up

Configuration

Alfred's configuration is managed through a unified YAML file (typically created by alfred quickstart) and environment variables.

Environment Variables

  • ZO_API_KEY: Required if you are using Zo Computer as your agent backend.
  • .env file: Alfred loads environment variables from a .env file in its root directory. This file supports KEY=VALUE pairs and does not override existing system environment variables.

Unified Configuration File

The alfred quickstart command generates a unified configuration file (e.g., config.yaml). This file contains settings for logging, agent backends, and worker configurations.

Example Configuration Snippets:

  • Logging:

    logging:
  level: INFO # INFO, DEBUG, WARNING, ERROR
  dir: ./data # Directory for log files

  • Agent Backend (Example: Zo Computer):

    agent:
  backend: zo_computer
  # Other backend-specific settings

Vault Structure

Alfred expects an Obsidian vault with specific record types and YAML frontmatter. The alfred quickstart command should set up a basic vault structure.

  • Record Types: Alfred works with 20 structured record types (e.g., people, tasks, conversations, projects).
  • Wikilinks: Records are interlinked using Obsidian's wikilink syntax.
  • Frontmatter: YAML frontmatter is used for structured metadata within records.

Build & Run

Alfred is a Python application primarily run via its CLI. There's no separate "build" step beyond installation.

Running Locally (Development)

  1. Start Alfred's core services and dashboard:

    alfred up --live

    The --live flag will launch a live TUI dashboard to monitor worker status, feed entries, and mutations.

  2. Start a Temporal Worker: In a separate terminal, start the Temporal worker to execute workflows.

    alfred temporal worker

Running Workflows

  • Trigger a specific workflow:

    alfred temporal run DailyBriefing

    Replace DailyBriefing with the name of your desired workflow.

  • Register scheduled workflows:

    alfred temporal schedule register crons.py

    This command registers workflows defined in crons.py (or your specified file) with the Temporal scheduler.

Interacting with Alfred

  • Inbox Processing: Drop files into the inbox/ directory, and the Curator worker will process them.
  • CLI Ingestion: Use alfred ingest for bulk ingestion of data.
  • Interface: Alfred meets you where you are, supporting various interfaces depending on your chosen agent runtime (Telegram, WhatsApp, Slack, iMessage, Email, CLI).

Deployment

Alfred is designed for self-hosting.

Recommended Platforms

  • Mac Mini: For a local, always-on personal server.
  • VPS (Virtual Private Server): Such as Hetzner, for cloud-based hosting with full control.
  • Personal Cloud Instance: Any personal cloud environment where you can run Python applications and manage your data.

Deployment Steps (General)

  1. Prepare your environment:

    • Install Python 3.11+.
    • Install necessary system dependencies for your chosen agent backend (e.g., claude, openclaw).
    • Set up your Obsidian vault directory.
    • Ensure network access to your Temporal cluster.

  2. Install Alfred: Follow the pip install alfred-vault step.

  3. Configure Alfred:

    • Run alfred quickstart to generate your configuration.
    • Adjust config.yaml to suit your deployment environment (e.g., log directories, agent backend settings).
    • Set any required environment variables (e.g., ZO_API_KEY) in your .env file or directly in the environment.

  4. Start Services:

    • Start the main Alfred process: alfred up. Consider using a process manager like systemd, Supervisor, or pm2 (for Node.js, but can manage Python scripts) to ensure it runs continuously and restarts on failure.
    • Start the Temporal worker: alfred temporal worker. This should also be managed by a process manager for reliability.

  5. Monitor: Use alfred up --live (if running on a terminal you can access) or check logs in the directory specified by logging.dir in your configuration.

Troubleshooting

Common Issues and Solutions

  • alfred command not found:

    • Solution: Ensure pip's script directory is in your system's PATH. This is usually handled automatically by pip installations. You might need to restart your terminal.

  • Agent backend not found or configured incorrectly:

    • Error: Messages indicating claude or openclaw are not in PATH, or ZO_API_KEY is missing.
    • Solution:
      • For claude or openclaw: Verify the executables are installed and their location is included in your system's PATH environment variable.
      • For Zo Computer: Ensure the ZO_API_KEY environment variable is set correctly before starting Alfred. Check your .env file or system environment.

  • Temporal connection issues:

    • Error: Workflows fail to start or workers cannot connect to the Temporal cluster.
    • Solution:
      • Verify your Temporal cluster is running and accessible from the machine hosting Alfred.
      • Check Temporal client configuration in Alfred (if applicable, often configured via environment variables or a temporalio.worker.Worker setup).
      • Ensure necessary ports are open (default Temporal port is 7233).

  • Obsidian vault not found or inaccessible:

    • Error: Workers report errors when trying to read from or write to the vault.
    • Solution:
      • Confirm the path to your Obsidian vault is correctly configured in Alfred's settings (usually established during quickstart).
      • Check file system permissions to ensure Alfred has read/write access to the vault directory.

  • Workers crashing or restarting frequently:

    • Error: The TUI dashboard shows workers in a "restarting" state, or logs indicate frequent failures.
    • Solution:
      • Examine the logs (./data/alfred.log or tool-specific logs) for detailed error messages.
      • Common causes include LLM API errors (rate limits, invalid requests), file system issues, or misconfigurations.
      • If an LLM is consistently failing, check your API keys and model availability.

  • No activity after dropping files into inbox/:

    • Error: Files in inbox/ are not processed by the Curator.
    • Solution:
      • Ensure the alfred up process is running. The Curator worker watches this directory.
      • Check the Curator's logs for any errors or indications it's not starting or processing files.
      • Verify the inbox/ directory path is correctly configured and accessible.
← Project overviewView alternatives to alfred →