Document storage bucket setup for template duplicates

README.md

@@ -28,31 +28,79 @@ tmux-backed, so they survive disconnects. A **Skills** page distributes reusable
 ## Run your own (private) instance
 
 **Option A — one click:** press **⋮ → Duplicate this Space** at the top of this
-page. Keep visibility **Private**. That's it.
+page. Keep visibility **Private**. Then create a private Storage Bucket and mount
+it at `/data` before logging in:
 
-**Option B — one command** (needs `pip install huggingface_hub` and `hf auth login`):
+```python
+from huggingface_hub import HfApi, Volume, create_bucket
+
+api = HfApi()
+space_id = "your-username/agent-manager"
+bucket_id = "your-username/agent-manager-data"
+
+create_bucket(bucket_id, private=True, exist_ok=True)
+api.set_space_volumes(
+    space_id,
+    volumes=[
+        Volume(type="bucket", source=bucket_id, mount_path="/data"),
+    ],
+)
+api.restart_space(space_id)
+```
+
+**Option B — one script** (needs `pip install -U huggingface_hub` and
+`hf auth login`):
 
 ```python
-from huggingface_hub import duplicate_space
-duplicate_space("lvwerra/agent-manager-template", private=True)
+from huggingface_hub import HfApi, Volume, create_bucket
+
+api = HfApi()
+space_id = "your-username/agent-manager"
+bucket_id = "your-username/agent-manager-data"
+
+create_bucket(bucket_id, private=True, exist_ok=True)
+api.duplicate_repo(
+    from_id="lvwerra/agent-manager-template",
+    to_id=space_id,
+    repo_type="space",
+    private=True,
+    space_volumes=[
+        Volume(type="bucket", source=bucket_id, mount_path="/data"),
+    ],
+)
 ```
 
 Then open your new private Space and **log in to each agent inside its terminal**
-(run `claude`, `codex`, etc. and follow the prompt) — credentials persist (see
-below). You can also set provider keys as Space **secrets** (`ANTHROPIC_API_KEY`,
-`OPENAI_API_KEY`, …) instead of logging in interactively.
+(run `claude`, `codex`, etc. and follow the prompt). You can also set provider
+keys as Space **secrets** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) instead of
+logging in interactively.
 
-## Persistence (optional — no bucket required)
+## Storage bucket (required for real use)
 
-The Space runs fine with **no storage at all**: it falls back to ephemeral disk,
-so you can try it immediately — but sessions, logins, and history reset whenever
-the Space sleeps or rebuilds.
+Agent Manager expects a private Storage Bucket mounted read-write at `/data`.
+That bucket stores your sessions, workspaces, skills, CLI credentials, and
+history. Without the bucket mount, the Space can still boot for preview, but it
+falls back to ephemeral disk: sessions, logins, and history reset whenever the
+Space sleeps or rebuilds.
 
-For durability, pick one (the app uses `/data` automatically either way):
+If you duplicated first, you can add or replace the mount later:
 
-- **Persistent Storage** *(easiest)* — Space **Settings → Persistent Storage**,
-  pick a tier. It mounts a real disk at `/data`. Done.
-- **Private bucket** — attach a private data source mounted at `/data`.
+```python
+from huggingface_hub import HfApi, Volume, create_bucket
+
+api = HfApi()
+space_id = "your-username/agent-manager"
+bucket_id = "your-username/agent-manager-data"
+
+create_bucket(bucket_id, private=True, exist_ok=True)
+api.set_space_volumes(
+    space_id,
+    volumes=[
+        Volume(type="bucket", source=bucket_id, mount_path="/data"),
+    ],
+)
+api.restart_space(space_id)
+```
 
 Everything durable lives under `/data`: `sessions.json`, `groups.json`,
 `workspaces/<folder>/` (per-agent working dirs + shared `skills/`), and each
@@ -80,7 +128,7 @@ sessions are pinned to a stable per-session id so grouped agents don't collide).
 | Var | Default | Purpose |
 |---|---|---|
 | `PORT` | `7860` | HTTP + WS port (HF `app_port`) |
-| `DATA_DIR` | `/data` | Durable root (Persistent Storage or bucket mount) |
+| `DATA_DIR` | `/data` | Durable root (mounted private Storage Bucket) |
 | `USE_TMUX` | auto | `1`/`0` to force tmux on/off (off = direct PTY, no persistence) |
 | `ANTHROPIC_API_KEY` | — | Claude Code / opencode / Hermes (Space **secret**) |
 | `OPENAI_API_KEY` / `CODEX_API_KEY` | — | Codex (Space secret) |

entrypoint.sh

@@ -4,8 +4,7 @@
 DATA_DIR="${DATA_DIR:-/data}"
 if ! mkdir -p "$DATA_DIR/workspaces" 2>/dev/null; then
   echo "WARN: $DATA_DIR is not writable — running EPHEMERAL (sessions/logins reset on restart)."
-  echo "      For durability, enable Persistent Storage in the Space settings (mounts at /data),"
-  echo "      or attach a private bucket at /data."
+  echo "      For durability, attach a private Storage Bucket mounted read-write at /data."
   DATA_DIR="$HOME/data"
   mkdir -p "$DATA_DIR/workspaces"
 fi

setup.py

@@ -1,22 +1,40 @@
 #!/usr/bin/env python3
-"""Spin up your own PRIVATE Agent Manager Space by duplicating the public template.
+"""Spin up your own PRIVATE Agent Manager Space from the public template.
 
-    pip install huggingface_hub
+    pip install -U huggingface_hub
     hf auth login          # or: huggingface-cli login
-    python setup.py
+    python setup.py [your-username/agent-manager] [your-username/agent-manager-data]
 
-The new Space is private by default. Open it, then log in to each agent inside
-its terminal (run `claude`, `codex`, ...). Enable Persistent Storage in the
-Space settings if you want sessions/logins to survive restarts.
+The script creates a private Storage Bucket and mounts it read-write at /data
+while duplicating the Space. Open the new private Space only after that, then
+log in to each agent inside its terminal (run `claude`, `codex`, ...).
 """
 import sys
-from huggingface_hub import duplicate_space
+from huggingface_hub import HfApi, Volume, create_bucket
 
 TEMPLATE = "lvwerra/agent-manager-template"
 
 if __name__ == "__main__":
     target = sys.argv[1] if len(sys.argv) > 1 else None  # optional "you/your-space"
-    res = duplicate_space(TEMPLATE, to_id=target, private=True)
+    api = HfApi()
+    if target and "/" in target:
+        namespace, space_name = target.split("/", 1)
+    else:
+        namespace = api.whoami()["name"]
+        space_name = target or TEMPLATE.rsplit("/", 1)[1]
+    bucket_id = sys.argv[2] if len(sys.argv) > 2 else f"{namespace}/{space_name}-data"
+
+    create_bucket(bucket_id, private=True, exist_ok=True)
+    res = api.duplicate_repo(
+        from_id=TEMPLATE,
+        to_id=target,
+        repo_type="space",
+        private=True,
+        space_volumes=[
+            Volume(type="bucket", source=bucket_id, mount_path="/data"),
+        ],
+    )
     url = getattr(res, "url", res)
     print(f"\n✅ Created your private Space: {url}")
+    print(f"   Mounted private bucket at /data: {bucket_id}")
     print("   Keep it PRIVATE — this app has no authentication.")

web/src/components/Locked.tsx

@@ -4,7 +4,22 @@ import { useState } from 'react';
 // disabled server-side; this explains how to run a private copy or relock.
 export default function Locked({ spaceId }: { spaceId?: string | null }) {
   const id = spaceId || 'owner/space-name';
-  const cmd = `from huggingface_hub import duplicate_space\nduplicate_space("${id}", private=True)`;
+  const cmd = `from huggingface_hub import HfApi, Volume, create_bucket
+
+api = HfApi()
+space_id = "your-username/agent-manager"
+bucket_id = "your-username/agent-manager-data"
+
+create_bucket(bucket_id, private=True, exist_ok=True)
+api.duplicate_repo(
+    from_id="${id}",
+    to_id=space_id,
+    repo_type="space",
+    private=True,
+    space_volumes=[
+        Volume(type="bucket", source=bucket_id, mount_path="/data"),
+    ],
+)`;
   const [copied, setCopied] = useState(false);
   const copy = () => {
     navigator.clipboard?.writeText(cmd).then(() => { setCopied(true); setTimeout(() => setCopied(false), 1500); }).catch(() => {});
@@ -22,7 +37,7 @@ export default function Locked({ spaceId }: { spaceId?: string | null }) {
 
         <h3>Run your own private copy</h3>
         <p className="locked-sub">
-          Press <b>⋮ → Duplicate this Space</b> above and keep it <b>Private</b>, or run:
+          Create a private Storage Bucket mounted at <b>/data</b>, then duplicate this Space:
         </p>
         <div className="locked-cmd">
           <pre><code>{cmd}</code></pre>