guaardvark / setup

Guaardvark: connect and check

Guaardvark runs on the user's own machine. Everything below is local; nothing leaves the box.

Where it is

• Backend URL: ${GUAARDVARK_URL:-http://localhost:5000}. The macOS default port is 5055
  (AirPlay owns 5000). The web UI is on port 5173 in dev, or the same port as the backend in Docker.

• Health: !curl -sf ${GUAARDVARK_URL:-http://localhost:5000}/api/health || curl -sf http://localhost:5055/api/health || echo "backend not reachable on 5000 or 5055"
• Plugins: !curl -sf ${GUAARDVARK_URL:-http://localhost:5000}/api/plugins/status || echo "plugin status unavailable"

If the backend is not reachable, tell the user to start it from the Guaardvark checkout
(./start.sh, or docker compose up), then retry. Do not try to start it yourself.

Two ways to drive it

1. MCP tools (preferred when present): the guaardvark MCP server exposes RAG, memory,
   code intelligence, file processing, web fetch, image/video/animation/music-video/film-crew
   generation, songs and speech (generate_music, generate_speech),
   get_generation_status for any queued batch or song, outreach drafting and GPU/log
   inspection. Generation tools queue by default over MCP and return a batch id. In Claude Code they appear as
   mcp__guaardvark__<tool> after python -m backend.mcp install, or as
   mcp__plugin_guaardvark_guaardvark__<tool> when the plugin was installed from the marketplace. Install once from the checkout:
   `bash
   python -m backend.mcp install # writes the server entry into every detected client: Claude Code, Codex,
   # Cursor, Grok, Antigravity, opencode, Claude Desktop, Zed, Gemini
   python -m backend.mcp doctor # self-test + stale-config scan
   python -m backend.mcp list-tools # what is exposed right now
   `
   Restart the client after installing so it re-reads its MCP config.

2. REST for everything the MCP policy does not expose (voice cloning, sound effects, upscaling, batches,
   cast/LoRA training, swarm launch, interconnector, plugins). Use curl against the backend URL.
   Responses are wrapped as {"success": bool, "data": {...}, "message": str} on most routes; a few
   older routes return the bare object. Read data when it is present.

Before generating anything

• GPU services are plugins. Check GET /api/plugins/status; a generation route answers 503 when
  its plugin is not running. Start one with POST /api/plugins/<id>/start where <id> is
  comfyui (image + video), audio_foundry (voice, music, FX), upscaling, lora_trainer,
  swarm. Only one heavy model owns the GPU at a time; the orchestrator evicts Ollama for video
  and vice versa, so a first call after a switch is slow. inspect_gpu (MCP) shows who holds it.

• Installed models: GET /api/batch-video/models and GET /api/batch-image/models list every
  registry entry with capabilities; check is_ready before naming a model. Nothing downloads
  without an explicit Install, so if a model is missing say so and offer
  POST /api/batch-video/models/download {"model_id": "..."} (or the image route with
  {"model_path": "..."}).

• Outputs land under data/outputs/ in the checkout and are also served read-only over MCP as
  guaardvark://outputs/... resources.

Skills in this pack