Up and running in under 10 minutes

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 open the DAAF Control Panel. Then choose option 1, “Start Claude Code.” It handles everything -- starts the container if it’s not already running, then launches Claude Code directly.

Prefer to skip the menu and launch Claude Code directly? Run bash run_daaf.sh (.\run_daaf.ps1 on Windows) instead. 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.

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.

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). The simplest way to open it is from the DAAF Control Panel -- run bash daaf.sh (.\daaf.ps1 on Windows) and choose option 2, “Browse Files (VS Code).” If you prefer the direct command, run this from your daaf-docker/ folder -- no need to enter the container:

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). It comes pre-loaded with ten extensions for Python and R syntax highlighting, Markdown preview, Git history, CSV viewing, and folder compression. 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.
• Getting files IN: Drag and drop files from your computer onto the file explorer sidebar to import them into the Docker volume (e.g., a dataset you want DAAF to analyze). This works for single files and whole folders, in Chrome, Edge, and Firefox.
• Getting files OUT: To export a single file, right-click it and choose Download (works in every browser). To export a whole folder in any browser, right-click the folder and choose Compress → zip (provided by the built-in vscode-archive extension, ready to use with no setup), then right-click the new .zip and choose Download -- you get one tidy archive on your computer. Stick to the zip, tar, or tgz options when compressing. (In Chrome or Edge you can also right-click a folder and choose Download directly, which copies the files individually.)
• 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 and lets you view diffs -- the most direct way to review exactly what DAAF produced during a session (and, if you’ve enabled the optional “Git commit management” preference, browse commit history too).

For getting a large research folder out wholesale, taking a full backup (Control Panel option 7) copies everything out to your computer in one step -- see below. 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.

Since your research files live inside the Docker volume rather than your regular computer folders, regularly backing up your work is essential. The easiest way is from the DAAF Control Panel -- run bash daaf.sh (.\daaf.ps1 on Windows) and choose option 7, “Create Backup.” If you want a GitHub backup for your work, ask Claude how to make your own repository and save to it accordingly. If you’d rather call the backup script directly, that works too:

This creates a date-versioned folder (e.g., 2026-07-17_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...). The backup checks itself as it goes: it verifies there’s enough free disk space before it starts, and after copying it compares the backup against the original -- checking both the number of files and their total size -- so a truncated or incomplete backup gets flagged with a warning rather than passing silently. You can also back up manually through Docker Desktop’s GUI by downloading the whole daaf or research folder from the volume viewer.

DAAF provides browser-based tools for reviewing completed work. The quickest way to open any of them is from the DAAF Control Panel (options 3, 4, and 5), but each also has its own convenience script you can run directly from your daaf-docker/ folder:

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.

By default, DAAF does not make git commits during your research sessions -- and it doesn’t need to. Every script version is preserved right in your project folder, including failed attempts (DAAF saves fixes as new numbered versions rather than overwriting the original), so the project folder itself is a complete, human-readable audit trail you can review with the VS Code Source Control panel. If you’d like git-based version tracking on top of that, you can turn on the optional “Git commit management” preference; once enabled, DAAF suggests commits at natural milestones and always asks before committing anything. Either way, nothing is ever pushed to a remote repository without your explicit instruction.

DAAF is actively developed and updated. The simplest way to update is from the DAAF Control Panel -- run bash daaf.sh (.\daaf.ps1 on Windows) and choose option 9, “Check for Updates.” Before updating, it’s a good idea to back up your research folder first (the updater offers to do this for you). You can also run the update script directly from your daaf-docker/ folder:

The update script handles everything for you: it offers to back up first, checks the GitHub remote, shows you how many new commits are available, and detects any local framework customizations you’ve made -- showing you exactly what changed and presenting options instead of overwriting anything. It is also self-healing: host tool files a previous update missed are delivered automatically, and if a host script on your machine has drifted from the repository version the updater heals it (saving your previous copy as <name>.pre-update first, and never overwriting if that backup can’t be written). If the Dockerfile or docker-compose.yml changed, it offers to rebuild the image for you automatically. Your research files in research/ are never affected by updates.

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:

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.

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. It is organized into six numbered, lifecycle-tagged sections and documents the supported authentication methods -- Options A through E for direct authentication (plus interactive browser login, which needs no variables), and Option F for the OpenAI/ChatGPT provider shim (covered further below) -- with the exact environment variables needed for each. The installer now seeds this file for you automatically from the template on a fresh install, carrying forward any install-time values you provided; it never overwrites an existing environment_settings.txt, so your real keys are always safe. To set it up:

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

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

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:

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.

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.

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:

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.

DAAF can run on OpenAI’s GPT models with no Anthropic account, through a lightweight translation shim that ships built into DAAF (it presents an Anthropic-compatible endpoint on your own machine, quietly forwards requests to OpenAI, and starts automatically inside the container). These are supported pathways under active, extensive testing -- they work, and user reports are welcome. There are two lanes:

Option F -- OpenAI API key. For researchers who have an OpenAI API key (pay-per-use) and want to talk to OpenAI directly. Add your key and the shim settings to environment_settings.txt, then do a one-time rebuild (this lane needs a rebuild because the shim’s auto-launch is baked into the container). After that, start Claude Code and switch to your GPT model with /model. Note: an OpenAI API key needs prepaid API credits, which are billed separately from any ChatGPT subscription.

ChatGPT-subscription lane. For researchers who already pay for ChatGPT Plus/Pro and would rather use it than buy API credits. It uses the same shim pointed at your ChatGPT subscription’s backend: first enable device-code login in your ChatGPT security settings, then run codex login --device-auth inside the container (it prints a URL and a one-time code you enter from any device), set SHIM_BACKEND_MODE=chatgpt in environment_settings.txt, and recreate the container. Your login is stored in a persisted, backed-up location, so you only do it once.

One thing to know about the ChatGPT lane: its backend enforces a lower working-context ceiling -- measured at about 370,000 tokens -- than the API routes (which serve the model’s full ~1M window). This is a backend limit no client setting can raise, so on that lane you set CLAUDE_CODE_MAX_CONTEXT_TOKENS=370000 and DAAF accounts against that ceiling for its context-management guidance. It also works through a backend interface OpenAI doesn’t officially offer for third-party tools, so OpenAI could change it, and you are responsible for compliance with OpenAI’s terms of service. Full step-by-step instructions for both lanes live in the Installation & Quickstart guide ↗.

Most people run a single DAAF installation and never need this. But you can run two or more independent installs on the same machine -- for example, one for work and one for personal projects, or one on Claude and another on GPT -- each with its own Docker volume, research history, and even its own DAAF version. Two things must be unique per install so they don’t collide: the Compose project name (which determines the container and data volume) and the three published localhost ports (2718 notebooks, 2719 log viewer, 2720 code editor).

To set up a second instance, choose a distinct project name and three free ports, set them as environment variables first, then run the installer into a second, separate folder:

The installer seeds these values into that folder’s environment_settings.txt, so they persist for every later launch and update with nothing more to do -- and the Control Panel and helper scripts read them automatically, always talking to the right container and ports. (On Windows, use $env:DAAF_PROJECT_NAME = "daaf-personal" and the matching $env:DAAF_PORT_* lines instead.) Your data volume moves with the project name, so choose the name once, up front.