Get Started

Installing DAAF is easy and straightforward by design:

No prior experience with terminal, Docker, or Claude Code required. There are detailed explanations throughout this guide so you have a strong intuition for what’s going on under the hood -- but besides the reading, the whole process shouldn’t take more than 10 minutes start-to-finish.

Prerequisites (~5 minutes)

What you need

Computer with internet

You’ll need internet access to download project files and interact with Claude (the AI that powers DAAF). All data analysis runs on your own hardware, so your computer should be generally capable of intermediate-level data analysis. Don’t worry about Python packages or dependencies -- that’s all handled for you behind the scenes. Your dataset files stay on your machine inside the Docker container (but note that analytical outputs like sample rows, statistics, summaries, are sent to Anthropic’s servers as part of the Claude Code conversation -- see the Support FAQ for the full picture on data privacy).

Anthropic account

DAAF uses Claude as its AI engine. Because DAAF relies on cutting-edge frontier models and asks them to do a lot of thorough work (deep-diving into data, writing and reviewing code, producing intensive plans), a high-usage Anthropic account is required. At $100–200/mo, this is the biggest barrier to entry. Here are your main options:

Max subscriptionRecommended
$100–200/mo flat rate ↗. Best value for regular use -- a flat monthly rate is typically much cheaper than paying per-use. We rarely hit rate limits on the $200/mo plan. Team and Enterprise subscriptions also work, though mileage may vary based on organizational settings. Rate limits may apply during heavy parallel use. Ideal for researchers who plan to use DAAF regularly.

API key
Pay per token ↗ with no monthly cap. Unlimited use, but more complex analyses can easily cost $50+ in API fees. For reference, many find they would have paid roughly 10x more via API key than the corresponding Max subscription price over the same period. No rate limits on usage. Best for only occasional use or organizations with existing API arrangements.

OpenRouter
Pay-per-token via openrouter.ai ↗ with a 5.5% fee on credit purchases. Same general trade-offs as the Anthropic API key, but provides more flexibility on model providers and model options, especially if you already use OpenRouter for other purposes. Requires configuration via environment_settings.txt -- see Advanced Configuration below. DAAF requires Opus-class models -- stick with Anthropic’s Opus through OpenRouter for now. GLM 5.1 and Kimi K2.6 are cheaper and fairly viable models from early scoping (as of mid-2026), but require more testing and caution. Could be for testing DAAF before committing to a subscription.

Cloud providers (Bedrock, Vertex AI)
Route through your organization’s existing cloud platform arrangement. Per your organization’s pricing -- best if your institution already has an enterprise agreement. Requires configuration via environment_settings.txt -- see Advanced Configuration below. Best for organizations with existing AWS or GCP contracts that include Anthropic access.

Not sure which to pick? Start with the lower Max subscription ($100/mo plan) to test things out and get a sense of how you might want to use DAAF. Then adjust methods or subscription levels as need arises.

How authentication works

For Max subscription and API key options, Claude Code will prompt you to authenticate interactively the first time you run it -- you don’t need to configure anything in advance. For OpenRouter and cloud provider setups, you’ll configure credentials via an environment_settings.txt file instead (see Advanced Configuration for step-by-step instructions). You can always switch between methods later (type /login inside Claude Code to change your interactive authentication, or update your settings file and restart the container).

Credentials security: Your Claude and API credentials only ever sit locally on your computer or go directly to the service provider. DAAF enforces safety checks to ensure Claude cannot accidentally share them.

Terminal access

You’ll interact with DAAF through a command-line terminal -- a text-based interface where you can type commands to navigate from folder-to-folder, run software, or open files more manually. It might feel a bit unfamiliar at first, but once Claude Code is running, it’s essentially like any other AI chatbot window. You’ll mostly be typing or pasting single commands.

macOS: Open the Terminal app (search for it in Spotlight with Cmd + Space).
Windows: Open PowerShell from the Start menu (strongly recommended over Command Prompt, which often lacks proper permissions).
Linux: Open your terminal emulator (usually Ctrl + Alt + T).

Here are the basic commands you'll probably want to keep handy:

What you want to do	Command
See where you are	`pwd`
List files here	`ls`
Move into a folder	`cd foldername`
Go up one folder level	`cd ..`
Clear the screen	`clear`
Cancel a running command	`Ctrl + C`
Recall previous commands	Up arrow
Auto-complete file/folder names	Tab
See past output that scrolled off screen	Scroll or `Shift + Page Up`

Copy and paste in terminal: On macOS, use Cmd + C / Cmd + V. In Windows PowerShell, use Ctrl + Shift + C / Ctrl + V (or right-click). Note: Ctrl + C in the terminal cancels a running command -- it does not copy text.

Password entry: Note that many terminal interfaces “hide” any password entry you’re asked to do -- if you don’t see your typing “working,” it is working but hiding it from view for your privacy.

Windows tip: If you experience graphical glitches in PowerShell, the free version of Warp ↗ provides a cleaner, more reliable terminal experience (you can skip creating an account and skip its AI features).

Docker Desktop

Docker is a program trusted across the software development industry that allows users to create a self-contained, isolated environment (called a “container”) on your computer that is strictly separated from everything else (protecting your personal files and software). Think of it like a lightweight virtual computer running inside your computer, created via a very specific and reproducible recipe every single time.

Download the appropriate Docker Desktop installer from docker.com/products/docker-desktop ↗ (available for Mac, Windows, and Linux). Install it and make sure it’s running before you proceed. If you run into any Docker-related errors during install, you may need to restart your computer to let the installation fully register.

What You’re Setting Up

How the pieces fit together

Before you run the installer, here’s what it does. The whole thing runs automatically in one line of code, but it’s valuable to understand what’s happening behind the scenes for future reference.

The installer downloads configuration files and uses Docker Desktop to build an isolated container where DAAF and Claude Code will run. This container serves three critical purposes:

Security isolation -- The container runs as a non-admin user with all system capabilities removed (cap_drop: ALL) and privilege escalation explicitly blocked (no-new-privileges). Claude Code cannot access or modify anything outside the DAAF workspace. Even if something goes catastrophically wrong, you can spin up a fresh environment in minutes with zero risk to your system.
Reproducibility -- Docker ensures that Python, all 50+ data science libraries, and Claude Code are installed in exactly the same configuration every time, on every machine. Everything runs out-of-the-box -- no version compatibility issues.
Consistency -- The predictable environment means we can set up all of DAAF’s reference materials, workflow processes, and helper features in equally predictable ways. DAAF works better when it knows exactly how everything is configured.

The diagram below charts out how everything fits together. Claude Code gets installed inside the Docker container, “wrapped” by DAAF’s instructions, workflows, and guardrails. It can only access files within the container and execute code using the bundled Python environment. Hover over any element to learn more.

If you’re worried about what gets installed, you can see exactly what is in the container by reading the Dockerfile in the repository -- feel free to ask your favorite LLM to help you interpret and inspect it.

You

Your Computer

Rest of Your
Personal Files 🔒 Isolated

Docker Container

Reproducible
Python Environment

Framework

Instructions, workflows & references

Claude Code

Docker-specific
Filesystem

Installation (~5 minutes, mostly waiting)

One command to install everything

Alright, now time to actually kick this off. Make sure Docker Desktop is running in the background, then open your terminal, navigate to the folder where you want DAAF installed, and paste the appropriate command for your operating system from the install code below. The installer will create a folder named daaf-docker/ in whatever directory your terminal is currently in (remember you can type pwd to see where you are, ls to list the files/folders where you are, and cd foldername to enter a folder in the current directory. Note that you may need to surround a folder name in double quotation marks if it has spaces in it, e.g., cd “foldername”).

# Install DAAF with one command
curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh | bash

# Install DAAF with one command
irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1 | iex

What you should see

The installer works through four numbered stages ([1/4] through [4/4]). Don’t worry about the large volume of scrolling output between them -- that’s normal Docker build activity. The first run takes 5--15 minutes. Here are the key milestones to watch for:

==========================================
  DAAF Installer
==========================================

Branch: v2.1.0

[1/4] Creating initial directory for installation files ...
[2/4] Downloading installation files ...
[3/4] Building Docker image
      (this may take a few minutes on first run since
       there are a lot of Python libraries to install)...

  ...lots of Docker build output scrolls by here
     as it installs Python, 50+ data science
     packages, and Claude Code...

✔ Claude Code successfully installed!
 daaf-docker  Built

Starting container...
 Container daaf-daaf-docker-1  Created
 Container daaf-daaf-docker-1  Started

[4/4] Cloning DAAF repository files into the
      Docker container ...

==========================================
  Installation complete!
==========================================

To start using DAAF:

  1. Navigate to the install directory
     and launch Claude Code:
     cd daaf-docker
     bash run_daaf.sh

If the build seems to hang during [3/4], give it a little extra time since installing the 50+ packages including geospatial libraries can take a minute here and there. As long as the output occasionally moves and updates every few minutes, let it finish. If anything goes wrong, you can close the terminal, delete the daaf-docker folder, and run the installer again; nothing is permanently changed on your computer.

First Launch (~2 minutes)

Start your first research session

Now that the installation is complete, we can run DAAF and Claude Code right away! In the same terminal window, navigate into the folder the install script created (cd daaf-docker) and run the appropriate helper script for your operating system to get the Docker container and Claude Code started in one simple line:

# Navigate into your DAAF folder and launch
cd daaf-docker
bash run_daaf.sh

# Navigate into your DAAF folder and launch
cd daaf-docker
.\run_daaf.ps1

Authenticate and configure

Two quick setup steps before you’re ready to go:

Authenticate

On first launch, Claude Code will prompt you to authenticate. For Max subscription users, this is a one-time browser-based login -- it opens in your web browser, you sign in with your Anthropic account, and then return to the terminal. You may need to copy and paste the link into your browser; be careful to check it for erroneous line-breaks in the URL if you run into issues!

Tip: Ctrl + C in the terminal cancels a running command, not copy. Use Ctrl + Shift + C (Windows/Linux) or Cmd + C (macOS) to copy text.

Configure

Type /config in Claude Code. Use arrow keys to navigate, left/right to change settings, and Enter to confirm. Set “Auto-compact” to False and “Verbose output” to True. Press Esc to return to the chat.

Why these settings?

Auto-compact off: DAAF manages its own context carefully through its multi-agent architecture. Auto-compaction can disrupt orchestration by removing context the orchestrator is still using.

Verbose on: Lets you see what DAAF’s agents are actually doing -- their tool calls, file reads, and reasoning. Much easier to spot shortcuts, missing references, or confused logic.

A note on selecting your Claude model with DAAF

DAAF’s installation sets your model to Opus 4.6 with 1 million token context by default -- no action needed on your part. You can check which model is active by looking at the indicator below the chat input line, and change it anytime by typing /model.

See Understanding DAAF -- Context Windows and Prompt Engineering 101 for a deeper explanation of why non-deterministic behavior happens and what to watch for.

If you’re interested in exploring more cost-efficient options: all development and testing of DAAF has been done exclusively on Opus 4.5 and Opus 4.6. I unfortunately think these models are required at this time. Other models (Sonnet, Haiku) are significantly cheaper but not nearly as capable, and they produce erratic, inconsistent results with DAAF’s workflows. The complexity of multi-agent orchestration -- agents spawning sub-agents, following multi-step protocols, managing context across long analytical workflows -- relies on the model’s ability to follow complex instructions reliably. This is also why the Max subscription is a practical prerequisite: Opus models are very resource-intensive, and it’s hard to complete DAAF workflows under the “Pro” or “Free” tiers.

Opus 4.6 also lets you adjust its thinking level by tapping left/right arrow keys while Opus 4.6 is selected in the /model selector. All of my testing uses the “High” setting -- this is a case where quality matters far more than speed, so I strongly recommend doing the same. That said, the thinking level does affect usage limits, so it’s reasonable to experiment with the tradeoffs yourself (inclusive of Sonnet 4.6). If you find anything useful about the quality-cost trade-off frontier, please share your findings with the community so we can refine this guidance!

Starting Small

Installation complete. Now explore.

On first run, DAAF will present a user acknowledgment and transparency statement explaining your responsibilities when using the framework: take a moment to read through it carefully.

This is a great moment to start engaging with DAAF on your own terms. Ask Claude about the transparency statement itself -- what it means, what your responsibilities are, what DAAF does and doesn’t guarantee. From there, try something like: “What data sources does DAAF know about?” or “Walk me through how a Full Pipeline analysis works.” or “What are the pros and cons of using DAAF for my research?” Talking conversationally with Claude is one of the easiest ways to get oriented.

DAAF will intelligently reference both the user documentation and the workflow documentation as relevant (but it never hurts to prompt it: “Based on a thorough read of the DAAF project documentation, can you tell me…?”). From here on, you can interact with Claude the same way you would with any AI assistant -- but DAAF will “kick in” its specialized workflows and skillsets whenever relevant to supercharge anything related to data analysis work, data documentation, data exploration, and so on.

If you want a gentle onboarding guide for actually using DAAF, head to Understanding and Working with DAAF next. The rest of this guide covers basic day-to-day workflows, file management, keeping DAAF updated, and advanced configuration options -- browse those at your own pace.

Quick tip: Now that you have Claude Code up and running with DAAF, you can start asking Claude for help! DAAF has a dedicated User Support mode for exactly this: ask it what DAAF is, how something works, or what to do when you’re stuck, and it will load its own documentation and walk you through it in plain language. This includes questions about the underlying tools too -- Docker, Git, Claude Code -- it can look up official documentation for those online when needed. Point it to any document, section, or sentence, and ask it to help you understand it better. It has visibility into the whole project documentation, so it should be able to help you out as you go. This kind of personalized assistance is invaluable for anyone getting onboarded.

Installation complete! Everything below covers day-to-day workflows, configuration, and troubleshooting -- reference material you can return to anytime.

Day-to-Day

Working with DAAF

Once DAAF is installed, your daily workflow runs through a handful of helper scripts in the daaf-docker/ folder. Here’s a quick reference of every command you’ll use -- the sections below walk through each workflow in detail, including where your files live, how to back up your work, how to review completed analyses, and how to keep DAAF updated.

Operation	macOS / Linux	Windows
Start session	`bash run_daaf.sh`	`.\run_daaf.ps1`
End session	`/exit` → `exit` → `docker compose down`	Same
Browse/edit files	`bash run_vscode.sh`	`.\run_vscode.ps1`
Backup data	`bash backup_daaf.sh`	`.\backup_daaf.ps1`
View notebooks	`bash view_notebooks.sh`	`.\view_notebooks.ps1`
View session logs	`bash view_logs.sh`	`.\view_logs.ps1`
Update DAAF	`bash update_daaf.sh`	`.\update_daaf.ps1`
Rebuild container	`bash rebuild_daaf.sh`	`.\rebuild_daaf.ps1`

Starting and ending sessions

Your daily workflow is simple: make sure Docker Desktop is running, open your terminal, navigate to the daaf-docker/ folder you set for the installation process, and run the helper script. It handles everything -- starts the container if it’s not already running, then launches Claude Code directly.

# Navigate to your DAAF folder and launch
cd daaf-docker
bash run_daaf.sh

# Navigate to your DAAF folder and launch
cd daaf-docker
.\run_daaf.ps1

To enter the container shell instead of Claude Code (for manual commands, setting API keys, or troubleshooting), pass bash as an argument: bash run_daaf.sh bash (macOS/Linux) or .\run_daaf.ps1 bash (Windows).

When you’re done working, exit in three steps: type /exit to leave Claude Code, then exit to leave the container, then docker compose down to shut down the container. Stopping the container does not delete any of your work -- everything in the Docker volume persists across restarts.

Manual alternative (individual commands)

If you prefer to run each step separately instead of using the helper script:

docker compose up -d starts the container in the background.

docker compose exec daaf-docker bash enters the container shell.

claude launches Claude Code from inside the container.

Managing your files

Your research files, data, and outputs live inside a Docker volume -- a storage area managed by Docker that’s separate from the daaf-docker/ folder on your computer. Think of the daaf-docker/ folder as the “recipe” that was used to set everything up, while the Docker volume is the actual “kitchen” where all the work happens.

This means your work persists across container restarts and rebuilds, but files created inside the container don’t automatically appear in your regular computer folders. Only the Docker volume is accessible to Claude -- your personal documents, photos, and everything else are completely isolated.

Browser-based file editor with Visual Studio Code

The easiest way to browse, edit, and manage your files is with DAAF’s built-in browser-based code editor (VS Code in the browser). Run this from your daaf-docker/ folder on your computer -- no need to enter the container:

bash run_vscode.sh

.\run_vscode.ps1

This opens a full VS Code editor at localhost:2720 (“localhost” means “this computer” -- open this address in your web browser like a regular website). The default access password is daaf (customizable in your environment_settings.txt file -- see Advanced Configuration).

Markdown preview: Right-click any .md file and select “Open Preview”, or press Shift+Ctrl+V, to see rendered Markdown with proper formatting -- the easiest way to read DAAF’s reports and plans.
File management: Use the file explorer sidebar to browse, create, rename, move, and delete files.
Importing files: Drag and drop files from your computer into the sidebar to import them into the Docker volume (e.g., a dataset you want DAAF to analyze). Right-click files to download them back out.
Search: Use Ctrl+Shift+F (or Cmd+Shift+F on Mac) to search across all files -- helpful for finding specific variables, scripts, or content across a project.
Git integration: The Source Control panel shows uncommitted changes, lets you view diffs, and browse commit history -- useful for reviewing what DAAF produced during a session.

You can also browse the Docker volume through Docker Desktop’s GUI by navigating to the Volumes panel and clicking the daaf_daaf-data volume, though this is much less streamlined.

Backing up your work

Since your research files live inside the Docker volume rather than your regular computer folders, regularly backing up your work is essential. If you want a GitHub backup for your work, ask Claude how to make your own repository and save to it accordingly. The included backup script also makes local backups easy:

cd daaf-docker
bash backup_daaf.sh

cd daaf-docker
.\backup_daaf.ps1

This creates a date-versioned folder (e.g., 2026-05-16_daaf_backup/) inside daaf-docker/ that you can move to external storage or share with colleagues. Multiple same-day backups auto-suffix with letters (a, b, c...). You can also back up manually through Docker Desktop’s GUI by downloading the whole daaf or research folder from the volume viewer.

Restoring from a backup

Run bash restore_from_backup.sh (macOS/Linux) or .\restore_from_backup.ps1 (Windows) from the daaf-docker/ folder. The script finds backup folders and prompts you to select one.

Important: Restoring completely replaces the current Docker volume contents and will overwrite changes; make sure you've identified the right version to restore from and that you don't have any crucial edits that will be overwritten. Make sure DAAF is not running first (docker compose down). The script checks for active containers and warns you.

Viewing notebooks and session logs

DAAF provides two browser-based tools for reviewing completed work, each launched with a convenience script from your daaf-docker/ folder:

Marimo notebooks localhost:2718

Run bash view_notebooks.sh (or .\view_notebooks.ps1) to open marimo’s notebook browser at localhost:2718. DAAF uses marimo to create streamlined Python code notebooks as part of its analysis, which you can view as interactive dashboards with code cells, outputs, and visualizations -- the primary way to review completed analyses. Since they’re written in regular Python code, you can also inspect them in any text editor.

Session logs localhost:2719

Run bash view_logs.sh (or .\view_logs.ps1) to start the DAAF Log Explorer at localhost:2719. Shows every tool call, subagent dispatch, and file reference organized chronologically -- useful for understanding what DAAF did during a session and debugging issues.

Sessions and context

Each DAAF session has a working memory (context window) that fills up as the conversation gets longer. When a session is interrupted or context fills up, DAAF writes a STATE.md file capturing current progress, decisions made, and what remains. To resume: open the STATE.md file (via the browser file manager at localhost:2720), copy the restart prompt it provides, type /clear in Claude Code, then paste the prompt. DAAF will pick up exactly where it left off using the state file.

During research sessions, DAAF’s agents also make local git commits inside the container to track every script version, data transformation, and plan update. This creates a detailed audit trail you can review with standard git tools or the VS Code Source Control panel. Nothing is ever pushed to a remote repository without your explicit instruction.

Keeping DAAF updated

DAAF is actively developed and updated. Run the update script from your daaf-docker/ folder to pull the latest fixes and improvements:

cd daaf-docker
bash update_daaf.sh

cd daaf-docker
.\update_daaf.ps1

The update script offers to back up first, checks for updates, detects any local framework customizations you’ve made, and handles merge safely. Your research files in research/ are never affected by updates.

What the update script does

The update script checks for available commits from the DAAF repository, shows you how many new commits are available, and detects any local edits you’ve made to framework files. If you’ve customized any framework files (CLAUDE.md, a skill, a template, etc.), it shows you exactly what you changed and presents options instead of overwriting anything. If you’ve committed your own changes, it offers to merge or rebase them with the update.

By default, the update script auto-detects the remote’s default branch (main or master). If you installed from a specific branch (e.g., dev), you can set the DAAF_BRANCH environment variable: DAAF_BRANCH=dev bash update_daaf.sh.

Migrating from v2.0.1 or earlier: If you installed DAAF before the v2.1.0 release, run the migration script to update your installation structure. See the repo documentation ↗ for full instructions.

Rebuilding the container

If an update changes the Dockerfile (e.g., new Python packages, updated Claude Code version), the update script will detect this automatically and prompt you to rebuild. You can also rebuild manually:

cd daaf-docker
bash rebuild_daaf.sh

cd daaf-docker
.\rebuild_daaf.ps1

The rebuild script copies the updated Dockerfile and docker-compose.yml from the container to the host, then rebuilds the image. Your research data in the Docker volume is not affected. Most updates don’t change the Dockerfile, so usually the update script alone is all you need.

Installing a specific version or branch

To install a specific release or branch, set the DAAF_BRANCH environment variable before running the installer. For example, to install a tagged release:

macOS / Linux: export DAAF_BRANCH=v2.1.0 then run the installer.

Windows: $env:DAAF_BRANCH=“v2.1.0” then run the installer.

Check the Releases page ↗ to see available versions. Note: the updater only accepts branch names, not tags. If you installed from a tag, the updater will automatically pull from main.

Advanced Configuration

Authentication and API keys

The sections below cover additional configuration for users with specific needs. If you completed the standard installation above and everything is working with a Max subscription, you can skip this section and come back later if and when you need it.

Configure authentication via environment_settings.txt

By default, Claude Code prompts you to log in interactively the first time you launch it (browser-based OAuth or pasting an API key). This works well for Max subscription and direct API key setups. However, if you’re using OpenRouter, a cloud provider (Bedrock/Vertex), or simply want your authentication to persist automatically without interactive login, you can configure it through the environment_settings.txt file in your daaf-docker/ folder.

Your daaf-docker/ folder includes an environment_settings_example.txt template that documents all five supported authentication methods with the exact environment variables needed for each. To set it up:

1. Copy the template (if you haven’t already):

cd daaf-docker
cp environment_settings_example.txt environment_settings.txt

cd daaf-docker
Copy-Item environment_settings_example.txt environment_settings.txt

2. Open environment_settings.txt in any text editor and uncomment the section matching your authentication method. For example, to use OpenRouter:

# --- Option C: OpenRouter (third-party model gateway) ---
ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=your_openrouter_api_key_here
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=your_openrouter_api_key_here

Replace your_openrouter_api_key_here with your actual OpenRouter API key (format: sk-or-v1-...). Get one at openrouter.ai/settings/keys ↗. Note that ANTHROPIC_API_KEY= must be set to an empty value (not removed entirely) -- if it’s unset, Claude Code falls back to Anthropic’s servers.

3. Restart the container to pick up the changes:

docker compose down
bash run_daaf.sh

docker compose down
.\run_daaf.ps1

If you previously logged in interactively with Anthropic, run /logout inside Claude Code before switching to an environment_settings.txt-based method -- cached credentials can take priority over environment variables.

Important: Only uncomment ONE authentication section. If multiple methods are set, Claude Code uses the highest-priority one (see the priority order documented in environment_settings_example.txt). This can lead to unexpected billing if, for example, you have both an API key and an OAuth token set.

Security note: The environment_settings.txt file lives on your host machine (in daaf-docker/), is gitignored by default, and is never visible to Claude inside the container. DAAF’s safety guardrails prevent Claude from reading or writing environment settings files by design -- your credentials stay strictly on your side of the boundary.

Set up data source API keys

Most DAAF data sources -- including all built-in education data from the Urban Institute -- are freely accessible with no authentication required. You can skip this step entirely if you’re only working with education data.

However, some data domains require API keys from their hosting platforms. The table below shows API keys for data sources that ship with DAAF. When you onboard a new data source from an API via Data Onboarding Mode, DAAF will guide you through setting up the appropriate environment variable using the same pattern shown here.

Data Source	Environment Variable	Where to Get a Key
County Presidential Election Returns	`HARVARD_DATAVERSE_API_KEY`	Harvard Dataverse ↗ → Log in → Account name (top-right) → API Token → Create Token

Add data source API keys to the same environment_settings.txt file used for authentication (see above). Uncomment and fill in the keys you need:

# Remove the leading # and replace the placeholder with your actual key
HARVARD_DATAVERSE_API_KEY=your_token_here

After editing, restart the container (docker compose down, then bash run_daaf.sh) to pick up the changes. You can set multiple API keys simultaneously -- each uses a unique environment variable name.

If you skip this step and later try to analyze data that requires it, DAAF will inform you that the API key is missing and point you back to these instructions.

Alternative: set keys manually in the container shell

If you prefer not to use environment_settings.txt, you can set environment variables directly inside the container before launching Claude Code:

Enter the container shell: bash run_daaf.sh bash (macOS/Linux) or .\run_daaf.ps1 bash (Windows).

Set the key for this session: export HARVARD_DATAVERSE_API_KEY="your_token_here"

Then launch Claude Code: claude

To make manual exports persist across container restarts, add the export line to ~/.bashrc inside the container: echo ‘export HARVARD_DATAVERSE_API_KEY="your_token_here"’ >> ~/.bashrc

The environment_settings.txt approach is simpler and recommended -- it persists automatically and you can edit it with your normal text editor without entering the container.

Re-installing DAAF

If you run the installer on a system where DAAF is already installed, it will detect the existing installation and stop with a warning. This is a safety feature -- re-running the installer would overwrite your framework files and local git history, though your research data in research/ would not be deleted.

To update DAAF (recommended -- preserves your local changes), use the update script described in the Day-to-Day section above.

To force a complete re-install (overwrites all framework files), set the DAAF_FORCE_REINSTALL environment variable and re-run the installer. Back up your Docker volume first.

macOS / Linux:

DAAF_FORCE_REINSTALL=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh)"

Windows (PowerShell):

$env:DAAF_FORCE_REINSTALL=1; iex (iwr -UseBasicParsing "https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1").Content

If the installer detects a previous attempt that didn't complete successfully (e.g., the Docker build failed partway through), it will note this and proceed automatically -- no override needed.

Troubleshooting

Common issues and fixes

Most setup issues have quick solutions. If you don’t find your answer here, check the Support page or ask DAAF directly -- User Support mode can troubleshoot Docker, Git, and Claude Code problems.

“docker: command not found” or “docker is not recognized”

Docker Desktop may not be installed, or your computer needs a restart after installation. Verify Docker Desktop is installed from docker.com/products/docker-desktop ↗. After installing, restart your computer, then verify by running docker --version in your terminal.

Make sure Docker Desktop is running -- look for the whale icon in your system tray or menu bar.

“unable to get image ’daaf-daaf-docker’”

The Docker image hasn’t been built yet. Open Docker Desktop and check the Images panel -- if you don’t see daaf-daaf-docker, the installer may not have completed. Re-run the installer:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh | bash

Windows:

irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1 | iex

“service ’daaf-docker’ is not running”

The container isn’t active. Start it with the convenience script from the daaf-docker/ folder:

macOS / Linux: bash run_daaf.sh
Windows: .\run_daaf.ps1

You can verify the container’s status in Docker Desktop under Containers -- it should show green “Running.” If the container isn’t listed at all, re-run the installer.

The first build is taking a very long time

This is normal. The first installation takes 5--15 minutes because it downloads and installs a base operating system image (~200MB), Python 3.12, 50+ data science packages (including geospatial libraries like GDAL, GEOS, and PROJ), and Claude Code.

This only happens once -- Docker caches everything, so future container starts take just seconds.

I can’t find my research files on my computer

Research files live inside a Docker volume -- managed storage that’s separate from your regular folders. You won’t see them in Finder or File Explorer. Three ways to access them:

Browser file manager: Run bash run_vscode.sh (or .\run_vscode.ps1 on Windows) to open a full file explorer at localhost:2720. You can browse, edit, and right-click to download any file.
Backup script: Run bash backup_daaf.sh (or .\backup_daaf.ps1) to create a date-versioned copy of everything in your daaf-docker/ folder.

Copy a specific file:

docker compose cp daaf-docker:/daaf/research/your-project/report.md ./

This copies a single file to your current folder.

Inside the container, your research is stored at /daaf/research/.

Port conflicts (2718, 2719, or 2720 already in use) Advanced

DAAF uses three ports: 2718 (Marimo notebooks), 2719 (Log Explorer), and 2720 (browser code editor). If one is already in use by another application:

Quick fix: Restart the container in Docker Desktop (stop, then start).

Persistent fix: Edit the docker-compose.yml file in your daaf-docker/ folder. Find the ports section and change the first number in the pair -- for example, change "127.0.0.1:2718:2718" to "127.0.0.1:3000:2718", then access notebooks at localhost:3000 instead.

Permission denied errors inside the container (especially on macOS) Advanced

This usually means file ownership doesn’t match the container user. The fix is usually simple: stop and restart the container.

docker compose down
docker compose up -d

DAAF’s docker-compose configuration includes an init service that automatically fixes file permissions on startup.

If that doesn’t resolve it, run this one-time fix:

docker run --rm -v "daaf_daaf-data:/daaf" busybox chown -R 1000:1000 /daaf

Claude Code asks for an API key every time I launch

The most reliable fix is to save your credentials in environment_settings.txt instead of relying on the interactive login cache (which can reset when the container is rebuilt).

From your daaf-docker/ folder:

Copy the template: cp environment_settings_example.txt environment_settings.txt
Open environment_settings.txt in any text editor
Add your API key: ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxx
Restart the container: docker compose down then bash run_daaf.sh

The environment_settings.txt file lives on your host machine, is gitignored, and is never visible to Claude.

Malformed authentication URL when trying to log in to Claude Code

When Claude Code prompts you to authenticate via a URL, the link can sometimes wrap across multiple lines in your terminal. If you copy a URL that contains a line break, the browser will fail to open it or show an error page.

Fix: Paste the copied URL into a plain text editor (Notepad, TextEdit, or any simple editor). Look for any unexpected line breaks in the middle of the URL and remove them so the entire address is on a single line. Then copy the cleaned-up URL and paste it into your browser.

OpenRouter: “model not found” or authentication errors Advanced

Three settings must be exactly right in your environment_settings.txt:

ANTHROPIC_BASE_URL=https://openrouter.ai/api -- must be exactly this, with no /v1 suffix (the /v1 variant is for OpenAI-compatible tools, not Claude Code)
ANTHROPIC_API_KEY= -- must be present and empty (not removed entirely). An unset key causes Claude Code to fall back to Anthropic authentication.
If you previously logged in with an Anthropic account, run /logout inside Claude Code to clear cached credentials.

After making changes, restart the container (docker compose down, then bash run_daaf.sh). Verify the connection with /status inside Claude Code, and check the OpenRouter Activity Dashboard ↗ to confirm requests are arriving.

How do I change the Claude model during a session?

Type /model in the Claude Code chat. Use arrow keys to select a model and press Enter. For Opus 4.6, use the left/right arrow keys to set the thinking level -- High is recommended for DAAF. The model selection appears below the chat input line.

The notebook won’t render in my browser

Use the convenience script from the daaf-docker/ folder:

macOS / Linux: bash view_notebooks.sh
Windows: .\view_notebooks.ps1

This handles container startup and port mapping automatically.

If it still doesn’t work: Is the container running? Is port 2718 mapped in docker-compose.yml? Try opening in an incognito/private browser window. Check the terminal output for error messages.

“Context utilization CRITICAL” and the session seems to stop

This isn’t an error -- it’s DAAF’s responsible context management. When a session’s context window fills up, DAAF writes a STATE.md file capturing current progress, decisions made, and what remains.

To resume: open the STATE.md file (via the browser file manager at localhost:2720), copy the restart prompt it provides, type /clear in Claude Code, then paste the prompt. DAAF will pick up exactly where it left off using the state file.

Claude seems to have forgotten earlier instructions or decisions

This is a known limitation of long LLM sessions. DAAF mitigates this with STATE.md (progress tracker) and Plan.md (methodology spec), which serve as persistent reference documents.

If you notice drift: prompt Claude to re-read STATE.md and Plan.md by saying something like “Please re-read the state file and plan before continuing.” Alternatively, start a fresh session with /clear -- DAAF will resume from the state file.

DAAF seems to be making things up about data variables or endpoints

“Hallucination” is when the AI makes up information that sounds plausible but isn’t accurate. It can happen if DAAF’s reference materials didn’t load properly for your topic.

Fixes:

Make sure Verbose output is set to True in /config so you can monitor whether skills are loading.
Ask DAAF to verify its claims against the skill documentation: “Can you check that variable name against the skill docs?”
Type /clear for a fresh context if the session seems confused.
Report persistent issues via GitHub.

Next Steps

Up and running in under 10 minutes