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:

   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

Skill	Use for
image	one image, edits, cast characters, batch image runs
video	one clip, image-to-video, first/last frame, batch video runs, MiniMax H3 with sound
music-video	a song in, a beat-cut music video out, with the approval gate
film-crew	screenplay to finished short: writer, casting, storyboards, render, edit
voice	narration, TTS, consent-gated voice cloning
music	full songs with lyrics, instrumentals, sound effects
upscale	2x to 8K upscaling of images and video
cast	Cast Library subjects and LoRA training for consistent characters
models	add any Hugging Face model or LoRA from a URL
swarm	parallel coding agents in git worktrees from a plan file
knowledge	the user's indexed documents, memory, web fetch
code	code search, repository map, self-improvement status
outreach	supervised social drafts (never posts)
ops	GPU, logs, Celery, plugins, Interconnector sync, autoresearch, infographics