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 chat, RAG, memory, code intelligence, file processing, web fetch, image/video/animation/music-video/film-crew generation, get_generation_status for any queued batch, 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:

   python -m backend.mcp install      # writes the server entry into Claude Code, Cursor, Claude Desktop, Codex, 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, music, 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