SETUP GUIDE / MACOS

Paste once.Or inspect every command.

The fastest path is the agent setup prompt below. It handles prerequisites and protected GCS setup, then shows one exact new-only plan for approval. The manual terminal path remains available underneath.

THE 60-SECOND HANDOFF

Give the setup to the agent already on your Mac.

No bucket form. No command assembly. Your coding agent installs the pinned release, creates or verifies your private GCS bucket, and proves automatic sync is running.

  1. 01Copy this setup
  2. 02Paste into Codex or Claude Code
  3. 03Approve the exact sources and bucket once

It shows the plan before it reads an eligible session.

  • Pinned release
  • Private user-owned GCS
  • New-only baseline
  • Verified background sync
Read the exact prompt
Install Datafooding on this Mac and finish setup so every next session from the AI agents I choose is automatically backed up to my dedicated GCS bucket.

The outcome I want
- Local session files remain the source of truth and are never deleted.
- Eligible bytes are encrypted on this Mac before upload.
- Only ciphertext is stored in a dedicated bucket in my Google Cloud project.
- Existing history is excluded. Only files created or changed after the new-only baseline may be captured.
- A macOS LaunchAgent keeps capture and sync running every 15 minutes.

Exact release contract
- Version: 0.2.1
- Wheel: https://datafooding.ai/releases/datafooding_agent_vault-0.2.1-py3-none-any.whl
- SHA-256: ba21b23f23a25850adc649a3e48d78c0a8a346193546c8cfbaf63c35dae6247b
- PEP 508 target: datafooding-agent-vault @ https://datafooding.ai/releases/datafooding_agent_vault-0.2.1-py3-none-any.whl#sha256=ba21b23f23a25850adc649a3e48d78c0a8a346193546c8cfbaf63c35dae6247b

Run this workflow

1. Preflight this Mac without reading session content.
   - Confirm the OS is macOS.
   - Detect only the existence and filesystem metadata of supported stores: Codex, archived Codex, Claude Code, Hermes, Kimi Code, OpenCode, and Gemini CLI.
   - Do not open or print prompts, messages, tool results, credentials, tokens, request dumps, hidden reasoning, or session payloads.

2. Install only missing prerequisites from their official distribution.
   - Homebrew is the package manager. If it is missing, use the official brew.sh installer and no third-party mirror.
   - Install uv with Homebrew when missing.
   - Install Google Cloud CLI with the current Homebrew cask: `brew install --cask gcloud-cli`.
   - Resolve gcloud with `command -v gcloud`; if the cask is installed but PATH has not refreshed, use `$(brew --prefix)/share/google-cloud-sdk/bin/gcloud` after checking that it is executable.
   - Never use a service account, create broad IAM grants, write credentials to the repository, or put secrets in command arguments or chat.

3. Establish the Google Cloud identity interactively.
   - Check the active account and project without printing tokens. If login is required, use `gcloud auth login`.
   - Never guess a project. If none is active, ask me for the exact project ID.
   - Resolve its numeric project number with `gcloud projects describe PROJECT_ID --format='value(projectNumber)'`.
   - Propose the dedicated bucket `datafooding-PROJECT_NUMBER`.

4. Ask for one compact approval before creating cloud resources or enabling capture.
   Show one block containing:
   - the detected agent names, with nothing selected by default;
   - the exact account and project ID, redacted where appropriate;
   - the proposed bucket;
   - for a new bucket, the GCS location I must choose because it is immutable;
   - for an existing bucket, its current location and any protection change needed;
   - every local prerequisite you installed.
   Ask me to reply with the exact sources and `APPROVE`. Treat that answer as consent only for those sources, that project, that bucket, and that location.

5. Create or verify the dedicated bucket, fail closed, and never delete it.
   - First run describe. Only an explicit not-found result permits creation. A permission error, timeout, disabled API, billing problem, or ambiguous result must stop with a concrete remediation.
   - Create a missing bucket with this exact protection shape:
     `gcloud storage buckets create gs://BUCKET --project=PROJECT_ID --location=LOCATION --uniform-bucket-level-access --public-access-prevention --soft-delete-duration=7d --quiet`
   - Never set or lock an irreversible retention policy.
   - Reuse an existing bucket only when describe proves that its project number matches the selected project and its location matches the approved plan.
   - Before continuing, re-describe and verify: exact name, project number, location, uniform bucket-level access enabled, public access prevention enforced, and soft-delete retention greater than zero. If an existing bucket needs a protection update, the approval block must name it before running any update.

6. Install the exact hash-pinned Datafooding release.
   Run:
   `uv tool install --force 'datafooding-agent-vault @ https://datafooding.ai/releases/datafooding_agent_vault-0.2.1-py3-none-any.whl#sha256=ba21b23f23a25850adc649a3e48d78c0a8a346193546c8cfbaf63c35dae6247b'`
   Then require `datafooding --version` to report 0.2.1.

7. Bind only the approved sources from now.
   - Run `datafooding quickstart --plan --bucket gs://BUCKET --source SOURCE ...`.
   - Verify the content-free plan exactly matches the approved bucket and source list, says `capture_policy: new-only`, `existing_sessions_included: false`, and enables automatic capture.
   - Never use `--include-existing`, `archive-home`, or a history migration in this workflow.
   - If the plan matches, run the same quickstart command with `--yes`.

8. Trigger and verify local-to-remote sync.
   - Run `datafooding sync --capture-enabled`, then `datafooding doctor` and `datafooding status`.
   - If the active setup session changes after the baseline, it may become eligible. Let the daemon retry a file that is still changing; do not weaken the stability checks.
   - Open `datafooding admin --language en` in a separate terminal because the local admin intentionally stays in the foreground.

9. Call setup complete only when all of these are true.
   - Doctor passes.
   - Every approved source is enabled with the new-only policy.
   - The LaunchAgent is installed, loaded, and bound to the current CLI.
   - GCS access and recoverability checks pass.
   - Queued ciphertext is zero.
   If no post-baseline file has changed yet, report `READY — waiting for the first new session`; do not claim that a session was uploaded.

Failure and rollback rules
- Stop on any identity, project, billing, ownership, location, policy, hash, or health ambiguity. Never retry with wider permissions.
- If quickstart fails after enabling a source that was off before this workflow, disable only that newly enabled source and stop the LaunchAgent started by this workflow. Preserve any pre-existing enabled source and daemon.
- Keep the local vault, Keychain entry, and protected bucket as resumable state. Do not delete source files, vault data, recovery material, or cloud objects.
- Return a short content-free receipt: version, selected source names, bucket protection status, capture policy, LaunchAgent state, queue count, and the exact next remediation if anything is incomplete.

Pasting authorizes the pinned local tools. Session capture starts only after you approve the exact new-only plan. Existing history stays out.

Prefer the terminal? Open manual setup

ONE-COMMAND OWNER BETA

Choose what starts now. Then copy one command.

Installation is not blanket consent. Pick exact agent stores below. Quickstart records a new-only baseline, skips every existing session, verifies your dedicated GCS bucket, starts the 15-minute background service, and opens the private local admin.

Start saving new sessions from
(command -v uv >/dev/null || brew install uv) && uv tool install --force 'datafooding-agent-vault @ https://datafooding.ai/releases/datafooding_agent_vault-0.2.1-py3-none-any.whl#sha256=ba21b23f23a25850adc649a3e48d78c0a8a346193546c8cfbaf63c35dae6247b' && datafooding quickstart --bucket 'gs://YOUR_BUCKET' --source CHOOSE_ONE --yes && datafooding admin --language en

Enter a bucket and choose at least one source.

Requires macOS, Homebrew and an authenticated Google Cloud CLI. If uv is missing, the command installs it from Homebrew. Source files are never deleted.

The public release will be a Developer ID-signed, notarized Mac installer you can open directly. Today, this pinned command is the owner-beta install path.

WHEN SETUP FINISHES

01

New sessions only

Existing history in selected agents becomes a baseline and is never uploaded automatically.

02

Encrypted on your Mac

Session bytes are encrypted locally. Only ciphertext is sent to your dedicated GCS bucket.

03

A visible done state

Local admin shows automatic capture, enabled sources, uploads, and queue health in one place.

Advanced: history review, restore, replay, and review
01

Review the exact plan

The plan is read-only. It names the bucket, exact sources, new-only policy, schedule, and permissions without creating a vault or reading session content.

datafooding quickstart --plan --bucket gs://BUCKET --source codex
02

Check current health

Use this after installation whenever automatic capture or storage needs attention.

datafooding doctor && datafooding status
03

Review existing history separately

Count discoverable files without reading their content. Existing sessions never join the quickstart consent.

datafooding discover
04

Include history only after review

This is a separate, explicit decision. It is never generated by the one-command installer.

datafooding source enable opencode --include-existing --yes
05

Preview an agent home

Inspect every included file and exclusion before a safe Codex, Claude, Hermes, Kimi, OpenCode, Gemini CLI, or custom archive.

datafooding archive-home opencode --dry-run
06

Archive and sync reviewed history

Capture the stable safe tree, encrypt locally, and upload ciphertext only. Credential stores remain excluded.

datafooding archive-home opencode --sync
07

Open local admin

Browse redacted projections, source policy, rights, replay jobs, and review receipts on 127.0.0.1.

datafooding admin
08

Connect a model rail

Store the key in Keychain, then declare a conservative local per-request cost upper bound. A key alone never enables a paid call.

datafooding provider-connect openrouter && datafooding provider-cost set openrouter MODEL --max-request-cost-microusd UPPER_BOUND --contract-id PRICE_RECEIPT
09

Freeze and authorize

Register a clean Git project, capture an immutable environment, pass the disclosure scan, and explicitly allow provider processing.

datafooding environment-capture PROJECT_ID --image IMAGE@sha256:DIGEST --prospective --allow-provider-processing --sync
10

Create a replay

Create a bounded comparison spec with one instruction file, one fixed environment, an executable verifier, and two or more model targets. This is not a reconstruction of the original product stack.

datafooding replay-create ENVIRONMENT_ID --instruction-file ./instruction.txt --verifier-command "python -m pytest -q" --target openrouter:MODEL_A --target upstage:MODEL_B --runs 3
11

Plan the attempts

Freeze the model matrix, seeds, budgets, and attempt identities before any provider request. Planning does not send the local trace or project files.

datafooding replay-plan SPEC_ID
12

Queue, run, and verify

Queue the attempts, then let the local worker execute only when a valid cost contract exists. Docker runs the verifier. Traces and artifacts remain on this Mac. A run is a bounded counterfactual, not an exact historical replay.

datafooding replay-run JOB_ID && datafooding replay-worker --once
13

Pair, then submit

Sign in to the owner-only review page, copy the origin-bound pairing bundle, and run review-connect once. The live probe must pass before Keychain changes. Then build and inspect a comparison pack and explicitly upload its exact manifest plus an allowlisted review projection. Accepted remains internal review; it is not a sale or payout.

datafooding review-connect && datafooding pack-build JOB_ID && datafooding pack-submit PACK_ID

ACCEPTANCE GATE

The five checks that matter

  1. Doctor reports every prerequisite as passed.
  2. Status shows uploaded sessions and zero queued ciphertext objects.
  3. A remote-only restore matches the captured SHA-256.
  4. Deleting a test snapshot removes its ciphertext but never the source file.
  5. Training, derivative, export, and resale rights remain off until explicitly granted.