passepartout/docs/USER_MANUAL.org

Passepartout User Manual

• Introduction
• Installation
  • Quick start (curl)
• Configuration
• Interacting with Passepartout
  • Terminal User Interface (TUI)
  • Command Line Interface (CLI)
  • TUI Commands
  • Human-in-the-Loop Approval
• The Memex Structure
• Deployment
  • Bare metal (Debian / Fedora)
  • Binary install (save-lisp-and-die)
  • systemd service (auto-start on boot)
  • Docker
  • Backup
  • Restore
• Troubleshooting
  • The daemon won't start
  • The TUI connects but shows "Disconnected"
  • The LLM returns garbage or fails to respond
  • Memory fails to load on startup

Introduction

Welcome to Passepartout. Passepartout is a neurosymbolic AI agent and a Lisp Machine operating system designed to autonomously maintain your Memex (knowledge base) and interact with you via multiple, equal-citizen interfaces.

Installation

Passepartout is bootstrapped via a single shell script.

Quick start (curl)

curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configure

This will:

1. Install system dependencies (SBCL, Emacs, git, curl, socat — detected for Debian or Fedora)
2. Install Quicklisp (Common Lisp package manager)
3. Tangle literate Org sources into runnable Lisp
4. Launch the interactive setup wizard (LLM providers, gateways)

If you already have Emacs installed, the installer skips it and uses your existing installation.

Configuration

The system is configured via a `.env` file in the project root. Essential variables include:

• `OPENROUTER_API_KEY`: Your LLM provider key.
• `PROVIDER_CASCADE`: The fallback order for LLM providers (e.g., `openrouter,ollama,anthropic`).
• `MEMEX_DIR`: The absolute path to your knowledge base (defaults to `~/memex`).

Interacting with Passepartout

Because of the Unified Envelope Architecture, the kernel treats all clients as interchangeable. You must first boot the background daemon:

./passepartout --boot &

Terminal User Interface (TUI)

For a rich, split-pane terminal experience:

./passepartout tui

Command Line Interface (CLI)

For raw, pipe-friendly interaction:

./passepartout cli

TUI Commands

When connected via the TUI, the following commands are available (type them in the input area and press Enter):

Command	Action
/help	List all available commands
/focus <project>	Set the agent's foveal focus to a project by name
/scope memex	Set scope to full memex (all projects visible)
/scope session	Set scope to current session only
/scope project	Set scope to focused project only
/unfocus	Clear the foveal focus
/approve HITL-xxxx	Approve a pending HITL action by its token
/deny HITL-xxxx	Deny a pending HITL action by its token
/theme <name>	Switch theme (dark, light, solarized, gruvbox)
/cost	Toggle session cost display in status bar
/voice on	Enable voice capture (planned v0.7.3)
/voice off	Disable voice capture
/quit	Save history and exit (planned v0.3.3)

For multi-line input, start the line with \ then press Enter to insert a newline without sending.

Human-in-the-Loop Approval

When the Dispatcher blocks a high-risk action (shell command, network call, core file modification), it creates a Flight Plan requiring your approval.

1. The TUI displays a yellow message: → HITL required: /approve HITL-ab12
2. Review the proposed action in the Dispatcher trace (expand with Tab)
3. Type /approve HITL-ab12 to approve, or /deny HITL-ab12 to deny
4. Approved actions are re-injected into the pipeline and executed
5. Denied actions are discarded and the Dispatcher records the decision as a permanent rule

Each approval or denial teaches the Dispatcher — the rule counter in the status bar ([Rules: 47]) increments with every decision.

The Memex Structure

Passepartout assumes a local folder structure representing your "Memex".

• Core memories and identities are mapped to Org-mode files.
• The `Scribe` background worker distills chronological logs into structured Zettelkasten notes.
• The `Gardener` continuously repairs broken links and flags orphaned nodes.

Deployment

Bare metal (Debian / Fedora)

The configure command supports both Debian-based (Ubuntu, Pop, Mint) and Fedora-based (RHEL, Rocky) distributions. It detects your distro automatically and installs the correct packages.

./passepartout configure              # interactive
./passepartout configure --non-interactive  # headless
./passepartout configure --with-firewall    # also open port 9105

After configuration, you can re-run configure any time to add providers or link gateways.

Binary install (save-lisp-and-die)

For platforms where SBCL cannot be installed (corporate laptops, shared hosts, constrained environments), a self-contained binary is provided:

curl -fsSL https://github.com/amrgharbeia/passepartout/releases/latest/download/passepartout -o passepartout
chmod +x passepartout
./passepartout daemon

This binary bundles SBCL, all required Lisp code, native embedding inference, and a Swank server on port 4005. The experience is identical to a source install — the REPL is available, skills hot-reload, and the image is mutable. Memory survives snapshots.

The binary is a convenience for constrained platforms. It is not a sealed container. The system remains constitutionally open — connect with SLIME, trace functions, inspect memory objects, modify the system while it runs.

systemd service (auto-start on boot)

./passepartout install service

Installs a user-level systemd unit that starts the daemon on login. Logs are available via journalctl --user -u passepartout.service -f.

To remove:

./passepartout uninstall service

Docker

A Debian-based Docker image is provided for containerized deployment.

cd infrastructure/docker
docker-compose up -d

This builds an image from debian:trixie-slim with all dependencies pre-installed. The memex directory is mounted from the host.

Backup

./passepartout backup ~/my-backup.tar.gz

Backs up the config, data, and memex directories.

Restore

./passepartout restore ~/my-backup.tar.gz

Restores from a backup file. Run passepartout doctor afterward to verify integrity.

Troubleshooting

The daemon won't start

• Check SBCL is installed: which sbcl
• Run passepartout doctor to diagnose
• Check port 9105 is free: lsof -i :9105
• Check the log output for errors

The TUI connects but shows "Disconnected"

• The daemon may have crashed. Run passepartout daemon in another terminal
• If the daemon is running, check it's listening: lsof -i :9105
• Use /reconnect (planned v0.6.0) to reconnect without restarting the TUI

The LLM returns garbage or fails to respond

• Run passepartout doctor to verify your LLM provider keys
• Check PROVIDER_CASCADE in your .env file
• Try switching models: edit .env and restart the daemon
• If using local models via Ollama, verify Ollama is running: ollama list

Memory fails to load on startup

• Check /memory.snap exists and is valid S-expression format
• Run passepartout doctor to diagnose memory integrity
• If corrupted, delete /memory.snap and restart — the daemon starts with empty memory