Update to Metabase

{
  "name": "setup-metabase-instance",
  "description": "Set up and run a local Metabase instance. Downloads the JAR (if Java 21+ is available) or runs via Docker. Also handles stopping running instances.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 207
    }
  ],
  "skill_md_contents": "---\nname: setup-metabase-instance\ndescription: Set up and run a local Metabase instance. Downloads the JAR (if Java 21+ is available) or runs via Docker. Also handles stopping running instances.\n---\n\n# Set Up a Local Metabase Instance\n\n**Read this entire skill file end-to-end before taking any action.** Do not skim, do not stop at the first matching step, do not act on the summary alone. Prerequisite checks, launch sections, init gates, and post-setup handoff rules are scattered through the document; skipping ahead has repeatedly produced broken flows. Load the full text into context first, then start executing.\n\n**Follow these instructions exactly as written.** Do not make assumptions, do not \"be helpful\" by overstepping, do not silently substitute \"equivalent\" actions for the ones specified. Every step, every verbatim message, every gate, and every prohibition is here because skipping or improvising on it has produced a known regression. If a step says \"send this verbatim\", send exactly that. If a step says \"stop and wait\", stop and wait. If a step says \"do not call endpoint X\", do not call X — even if the user asks you to. When in doubt, do less, not more.\n\n---\n\nThis skill helps users run a local Metabase instance for development, testing, or exploration.\n\n## Important: Network Access Required\n\nThis skill requires network access. All `curl`, `java`, and `docker` commands must be run outside the Codex sandbox. Request full network access or run outside the sandbox before attempting these commands. Do not run them inside the sandbox as they will fail.\n\n## Prerequisites Check\n\nRun these checks in order. Stop at the first successful path.\n\n### 1. Check for Java 21+\n\nExpand PATH first to avoid the macOS stub at `/usr/bin/java`:\n\n```bash\nexport PATH=\"/opt/homebrew/opt/openjdk/bin:/opt/homebrew/opt/openjdk@21/bin:/opt/homebrew/bin:/usr/local/opt/openjdk/bin:/usr/local/opt/openjdk@21/bin:/usr/local/bin:$PATH\"\njava -version 2>&1 | head -1\n```\n\nIf the output shows Java 21 or higher → use Section A (JAR). Keep this `PATH` export for all subsequent commands.\nIf not found or version < 21 → check Docker (step 2).\n\n### 2. Check for Docker\n\n```bash\ndocker --version 2>&1\n```\n\n**If Docker is available**: Use the Docker method (Section B).\n\n**If neither Java 21+ nor Docker is available**: Direct the user to install Docker:\n\n- macOS/Windows: [Docker Desktop](https://www.docker.com/products/docker-desktop/)\n- Linux: [Docker Engine](https://docs.docker.com/engine/install/)\n\nTell them to re-run this skill after installing Docker.\n\n---\n\n## Section A: JAR Method (Java 21+)\n\n### A1. Check for existing Metabase directory\n\n```bash\nls -la ./metabase 2>/dev/null\n```\n\nIf `./metabase` exists and contains files, ask the user:\n\n- \"A `./metabase` directory already exists. Should I use it (preserving existing data) or remove it and start fresh?\"\n\nIf the user wants to start fresh:\n\n```bash\nrm -rf ./metabase\n```\n\n### A2. Create directory and download JAR\n\n```bash\nmkdir -p ./metabase\n```\n\nGet the latest OSS release URL and download:\n\n```bash\ncurl -sL -o ./metabase/metabase.jar https://downloads.metabase.com/latest/metabase.jar\n```\n\nTell the user this may take a minute (the JAR is ~400MB).\n\n### A3. Check if port 3000 is in use\n\n```bash\nlsof -i :3000 2>/dev/null | grep LISTEN\n```\n\nIf the port is in use, ask the user:\n\n- \"Port 3000 is already in use. Would you like to use a different port?\"\n- Suggest port 3001, 3002, etc.\n\nStore the chosen port as `$PORT` (default: 3000).\n\n### A4. Start Metabase in the background\n\nUse the same `PATH` as in the Java prerequisite step when the agent uses a fresh shell (prepend the macOS Homebrew line again if unsure). Set `JAVA_CMD=$(command -v java)` after that export so you invoke the same binary you version-checked.\n\nPrefer `tmux` for the JAR method when available. It is more reliable in Codex Desktop than plain `nohup` because it keeps the long-running Java process attached to a durable local session instead of depending on shell job-control behavior.\n\n```bash\nexport PATH=\"/opt/homebrew/opt/openjdk/bin:/opt/homebrew/opt/openjdk@21/bin:/opt/homebrew/bin:/usr/local/opt/openjdk/bin:/usr/local/opt/openjdk@21/bin:/usr/local/bin:$PATH\"\nJAVA_CMD=$(command -v java)\nPORT=${PORT:-3000}\n\nif command -v tmux >/dev/null 2>&1; then\n  tmux kill-session -t metabase-local 2>/dev/null || true\n  tmux new-session -d -s metabase-local -c \"$(pwd)/metabase\" \\\n    \"MB_DB_FILE=./metabase.db MB_JETTY_PORT=$PORT '$JAVA_CMD' -jar metabase.jar >> metabase.log 2>&1\"\n  echo \"tmux:metabase-local\" > ./metabase/metabase.pid\nelse\n  (\n    cd ./metabase\n    MB_DB_FILE=./metabase.db MB_JETTY_PORT=$PORT \\\n      \"$JAVA_CMD\" -jar metabase.jar > metabase.log 2>&1 < /dev/null &\n    echo $! > metabase.pid\n  )\nfi\n```\n\nTell the user: \"Metabase is starting in the background. I'll check when it's ready...\"\n\nAlso mention:\n\n- \"View logs: `tail -f ./metabase/metabase.log`\"\n- If using `tmux`: \"Attach to the session with `tmux attach -t metabase-local`\"\n- If using the direct background fallback: \"The process ID is saved in `./metabase/metabase.pid`\"\n\nBefore polling for up to 2 minutes, do a quick launch check. If the process/session already exited, inspect logs immediately and switch to Docker if the JAR launch is not recoverable:\n\n```bash\nsleep 2\nif [ \"$(cat ./metabase/metabase.pid 2>/dev/null)\" = \"tmux:metabase-local\" ]; then\n  tmux has-session -t metabase-local 2>/dev/null || {\n    echo \"Metabase tmux session exited early\"\n    tail -80 ./metabase/metabase.log\n    exit 1\n  }\nelse\n  ps -p \"$(cat ./metabase/metabase.pid 2>/dev/null)\" >/dev/null 2>&1 || {\n    echo \"Metabase process exited early\"\n    tail -80 ./metabase/metabase.log\n    exit 1\n  }\nfi\n```\n\n### A5. Wait for Metabase to be ready\n\nPoll the health endpoint every 5 seconds until it returns `{\"status\":\"ok\"}`:\n\n```bash\ncurl -s http://localhost:$PORT/api/health\n```\n\nKeep polling until the response is `{\"status\":\"ok\"}`. Metabase usually starts within 30-60 seconds.\n\nIf the health check keeps failing after 2 minutes, check if the process is still running:\n\n```bash\nif [ \"$(cat ./metabase/metabase.pid 2>/dev/null)\" = \"tmux:metabase-local\" ]; then\n  tmux has-session -t metabase-local 2>/dev/null && echo \"Running in tmux\" || echo \"Not running\"\nelse\n  ps -p \"$(cat ./metabase/metabase.pid 2>/dev/null)\" >/dev/null 2>&1 && echo \"Running\" || echo \"Not running\"\nfi\ntail -50 ./metabase/metabase.log\n```\n\nOnce healthy, tell the user: \"Metabase is ready at `http://localhost:$PORT`\"\n\n---\n\n## Section B: Docker Method\n\n### B1. Check for existing Metabase directory\n\n```bash\nls -la ./metabase 2>/dev/null\n```\n\nIf `./metabase` exists and contains files, ask the user:\n\n- \"A `./metabase` directory already exists. Should I use it (preserving existing data) or remove it and start fresh?\"\n\nIf the user wants to start fresh:\n\n```bash\nrm -rf ./metabase\n```\n\n### B2. Create directory for data persistence\n\n```bash\nmkdir -p ./metabase\n```\n\n### B3. Check if port 3000 is in use\n\n```bash\nlsof -i :3000 2>/dev/null | grep LISTEN\n```\n\nIf the port is in use, ask the user for an alternative port. Store as `$PORT` (default: 3000).\n\n### B4. Check for existing Metabase container\n\n```bash\ndocker ps -a --filter \"name=metabase-local\" --format \"{{.Names}} {{.Status}}\"\n```\n\nIf a container named `metabase-local` exists:\n\n- If running: Ask if they want to stop it and start fresh, or keep using it\n- If stopped: Ask if they want to remove it and start fresh, or restart it\n\nTo remove an existing container:\n\n```bash\ndocker rm -f metabase-local 2>/dev/null\n```\n\n### B5. Get the latest Metabase version\n\nThe `latest` tag on Docker Hub is often outdated. Get the actual latest version from GitHub:\n\n```bash\ncurl -s https://api.github.com/repos/metabase/metabase/releases/latest | grep '\"tag_name\"' | head -1\n```\n\nThis returns something like `\"tag_name\": \"v0.52.5\"`. Extract the version (e.g., `v0.52.5`).\n\nVerify the Docker image exists:\n\n```bash\ndocker manifest inspect metabase/metabase:$VERSION 2>&1 | head -5\n```\n\nIf it doesn't exist, fall back to `latest`.\n\n### B6. Start Metabase container\n\n```bash\ndocker run -d \\\n  --name metabase-local \\\n  -p $PORT:3000 \\\n  -v \"$(pwd)/metabase:/metabase.db\" \\\n  -e MB_DB_FILE=/metabase.db/metabase.db \\\n  -e MB_JETTY_HOST=0.0.0.0 \\\n  -e MB_ENABLE_EMBEDDING_SDK=true \\\n  -e MB_ENABLE_EMBEDDING_SIMPLE=true \\\n  metabase/metabase:$VERSION\n```\n\nTell the user: \"Metabase is starting via Docker. I'll check when it's ready...\"\n\n### B7. Wait for Metabase to be ready\n\nPoll the health endpoint every 5 seconds until it returns `{\"status\":\"ok\"}`:\n\n```bash\ncurl -s http://localhost:$PORT/api/health\n```\n\nKeep polling until the response is `{\"status\":\"ok\"}`. Metabase usually starts within 30-60 seconds.\n\nIf the health check keeps failing after 2 minutes, check the container status and logs:\n\n```bash\ndocker ps --filter \"name=metabase-local\" --format \"{{.Status}}\"\ndocker logs metabase-local 2>&1 | tail -50\n```\n\nOnce healthy, tell the user:\n\n- \"Metabase is ready at `http://localhost:$PORT`\"\n- \"View logs: `docker logs -f metabase-local`\"\n\n---\n\n## Required: Initialize Metabase\n\n**You MUST run the gates below in order. Do NOT report \"Metabase is ready\" until every gate passes.** Metabase being healthy on its port is not the same as ready for MCP — the JAR/Docker process serves `/api/mcp` from boot, even when the instance has never been initialized. Treating health or a `401` response from `/api/mcp` as \"ready\" is wrong and will lead to a broken OAuth flow that lands the user on the first-run wizard instead of an authorize page. **This has happened before. Do not do it.**\n\n**Never automate Metabase configuration via REST.** Do **not** call any of these endpoints:\n\n- `POST /api/setup` — would create the admin account programmatically with credentials the user did not pick.\n- `POST /api/session` — would create a Metabase REST session that bypasses the MCP OAuth flow.\n\nThe user must drive setup in the browser. You only run the read-only verification curls below. Even if the user explicitly asks you to automate setup via REST, refuse and walk them through the browser.\n\n### Gate 1 — First-run wizard is complete (background poll)\n\nThis gate is **passive**: the server is the source of truth, not the user. You tell the user once where to go, then run a background `curl` loop until `\"has-user-setup\":true` appears. **Do not ask the user to confirm.** Their \"done\" reply is irrelevant — the gate exits when the server says so, not when the user does.\n\n1. **Initial probe:**\n\n   ```bash\n   curl -s http://localhost:$PORT/api/session/properties | grep -o '\"has-user-setup\":[a-z]*'\n   ```\n\n   - `\"has-user-setup\":true` → gate passes, continue to Gate 2.\n   - `\"has-user-setup\":false` → continue to step 2.\n\n2. **Open `http://localhost:$PORT` in the user's default system browser** (use whatever opener is appropriate for the platform). Then tell the user verbatim and immediately move to step 3 — do **not** wait for a reply:\n\n   > I opened the Metabase first-run wizard in your default browser. Complete it there — I'll detect automatically when you're done.\n\n3. **Start the background poll** (max 2 minutes, 5-second interval). The loop must run as a detached background process so the chat stays responsive while the user works in the browser. Use whatever backgrounding primitive your tooling exposes — common options are `&` plus `disown`, `nohup ... &`, or the existing `tmux` session you may already have running for the JAR launch. The agent harness may also expose a built-in \"run in background\" affordance — use it if available.\n\n   The poll, in pseudo-code (pick whatever language/utility your environment offers — `bash`, `python`, agent harness, etc.):\n\n   ```\n   deadline = now + 120 seconds\n   loop:\n     resp = GET http://localhost:$PORT/api/session/properties\n     if resp contains '\"has-user-setup\":true':\n       report success and exit\n     if now >= deadline:\n       report timeout and exit\n     sleep 5 seconds\n   ```\n\n   Surface two distinct outcomes to step 4 (e.g. exit code `0` vs `1`, return value, or a status flag — whatever your runner uses).\n\n4. **Wait for the loop to exit:**\n\n   - **Exit code 0** (server flipped to `true`) → gate passes. Advance to Gate 2.\n   - **Exit code 1** (2-minute timeout) → fall through to step 5 (user-driven mode).\n\n5. **Timeout fallback — user-driven re-check.** Once 2 minutes have passed without the server flipping, stop polling automatically. Send the user verbatim:\n\n   > It's been 2 minutes and I haven't seen the wizard complete on the Metabase side. Take your time — just tell me once you've finished setup and I'll verify.\n\n   Then wait for any user reply. When they reply, run one explicit `curl`:\n\n   ```bash\n   curl -s http://localhost:$PORT/api/session/properties | grep -o '\"has-user-setup\":[a-z]*'\n   ```\n\n   - `true` → gate passes, advance to Gate 2.\n   - `false` → tell the user the server still doesn't see it complete, ask them to double-check, then wait for their next reply and re-probe.\n\nWhile the background loop (step 3) is running:\n\n- If the user asks you a question, answer it — but **do not** stop the loop and **do not** advance to Gate 2 on their word alone.\n- If the user says \"done\" / \"ready\" / \"I finished\", respect them and **run an explicit probe right away** (don't wait for the next 5-second tick):\n\n   ```bash\n   curl -s http://localhost:$PORT/api/session/properties | grep -o '\"has-user-setup\":[a-z]*'\n   ```\n\n   - `true` → great, kill the background loop and advance to Gate 2.\n   - `false` → reply briefly: \"The server doesn't show the wizard complete yet — double-check the last step in the browser.\" Keep the background loop running; it will pick up the flip on its own once the wizard really completes.\n\n### Gate 2 — Offer the user a chance to connect their own database (mandatory ask)\n\n**You MUST ask the user this question and wait for their explicit reply before advancing to Gate 3.** Do not skip this gate \"to be helpful\". Do not infer the answer from prior context. Do not proceed on silence. A fresh Metabase only has the Sample Database; the user almost always wants their own data, and not asking is one of the most common UX regressions in this skill.\n\n1. **Send the user this message verbatim** (do not paraphrase, do not summarise, do not assume the user already wants to skip):\n\n   > Metabase is set up. By default it only knows about its Sample Database. Want to connect your own database now so you can ask Codex questions about your data? Reply **yes** to open the \"Add database\" page in Metabase, or **no** / **skip** to continue with just the Sample Database (you can always add one later from Admin → Databases).\n\n2. **Stop generating and wait for a reply.** Do not advance to step 3 or to Gate 3 until you have an explicit user message addressing this question.\n\n3. **Branch on the reply:**\n\n   - User says **yes** (or equivalent like \"sure\", \"add it\", \"let's do it\") → continue to the \"If the user says yes\" sub-section below.\n   - User says **no** / **skip** (or equivalent like \"later\", \"not now\", \"just the sample\") → continue to Gate 3.\n   - User replies with something unrelated → re-send the verbatim message and wait again. Do not abandon the gate.\n\n#### If the user says yes\n\nOpen `http://localhost:$PORT/admin/databases/create` in the user's default system browser, then send them verbatim:\n\n> I opened the \"Add database\" page in your browser. Fill in the connection details for your database (host, port, credentials, etc.), test the connection, and save it. Tell me once you've saved it successfully.\n\nDo **not** automate the form submission — connection credentials must come from the user via Metabase's UI, never via chat. Opening the URL is fine; entering the credentials for them is not.\n\nThis gate completes on the user's confirmation when they reply \"done\" / \"added\" / \"saved\".\n\n#### If the user says no / skip\n\nContinue immediately to Gate 3.\n\n### Gate 3 — Confirm and stop\n\nOnly after Gates 1 and 2 are both resolved, confirm to the user that Metabase is ready at `http://localhost:$PORT` (substitute the actual port) and stop.\n\n---\n\n## Stopping Metabase\n\nWhen the user asks to stop Metabase, determine which method was used.\n\n### Stop JAR-based Metabase\n\n```bash\nif [ -f ./metabase/metabase.pid ]; then\n  if [ \"$(cat ./metabase/metabase.pid)\" = \"tmux:metabase-local\" ]; then\n    tmux kill-session -t metabase-local 2>/dev/null && rm ./metabase/metabase.pid && echo \"Metabase stopped\"\n  else\n    kill \"$(cat ./metabase/metabase.pid)\" 2>/dev/null && rm ./metabase/metabase.pid && echo \"Metabase stopped\"\n  fi\nelse\n  # Fallback: find by process\n  pkill -f \"metabase.jar\" && echo \"Metabase stopped\"\nfi\n```\n\n### Stop Docker-based Metabase\n\n```bash\ndocker stop metabase-local && echo \"Metabase stopped\"\n```\n\nTo also remove the container (but keep data):\n\n```bash\ndocker rm metabase-local\n```\n\n---\n\n## Checking Metabase Status\n\n### Check JAR status\n\n```bash\nif [ -f ./metabase/metabase.pid ] && [ \"$(cat ./metabase/metabase.pid)\" = \"tmux:metabase-local\" ]; then\n  if tmux has-session -t metabase-local 2>/dev/null; then\n    echo \"Metabase (JAR) is running in tmux session metabase-local\"\n  else\n    echo \"Metabase (JAR) is not running\"\n  fi\nelif [ -f ./metabase/metabase.pid ] && ps -p \"$(cat ./metabase/metabase.pid)\" > /dev/null 2>&1; then\n  echo \"Metabase (JAR) is running with PID $(cat ./metabase/metabase.pid)\"\nelse\n  echo \"Metabase (JAR) is not running\"\nfi\n```\n\n### Check Docker status\n\n```bash\ndocker ps --filter \"name=metabase-local\" --format \"{{.Names}}: {{.Status}}\"\n```\n\n---\n\n## Environment Variables Reference\n\nThese can be customized when starting Metabase:\n\n| Variable        | Default         | Description                                  |\n| --------------- | --------------- | -------------------------------------------- |\n| `MB_DB_FILE`    | `./metabase.db` | H2 database file location                    |\n| `MB_JETTY_PORT` | `3000`          | Port Metabase listens on                     |\n| `MB_JETTY_HOST` | `localhost`     | Network interface (use `0.0.0.0` for Docker) |\n\nFor all options, see the [Metabase Environment Variables documentation](https://www.metabase.com/docs/latest/configuring-metabase/environment-variables).\n\n---\n\n## Troubleshooting\n\n### \"Address already in use\"\n\nAnother process is using the port. Either stop that process or choose a different port.\n\n### \"Java version too old\"\n\nInstall Java 21+ or use the Docker method instead.\n\n### \"Unable to locate a Java Runtime\" on macOS\n\nYou are likely hitting `/usr/bin/java` (stub). Prepend Homebrew OpenJDK to `PATH` as in **Check for Java 21+**, or call the real binary explicitly, e.g. `/opt/homebrew/bin/java -version`.\n\n### Metabase starts but is slow\n\nFirst startup takes longer as it initializes the database. Subsequent starts are faster.\n\n### \"Cannot connect to Docker daemon\"\n\nMake sure Docker Desktop is running (macOS/Windows) or the Docker service is started (Linux).\n"
}