Sandbase

SandBase

<!-- sandbase-cli-managed: sandbase -->

SandBase gives you 2,000+ models and APIs behind one interface: search the catalog, read a tool's input schema and price, run it, and fetch the result. One balance covers everything; the user never manages provider keys.

There are two transports with the same capabilities. Pick one before doing anything else.

1. Pick your transport

Exception: when you expect a large result (hundreds of rows, long transcripts, many files) and have a shell, use the CLI with -o result.json even if MCP is connected. MCP results land in your context; -o writes them to disk. Discovery and inspection are small, so use MCP for those regardless.

1.1 If neither transport is available

Tell the user to run this once in a terminal, approve the browser sign-in, and restart their AI client:

npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz connect

It configures the local MCP bridge and this Skill for every supported client it finds. No API key to paste. For checksum-verified installs, use the immutable assets on the GitHub Releases page.

2. Transport A — MCP tools (preferred)

Discovery, inspection, run status, and balance are free; only sandbase_run spends the user's balance.

MCP workflow

1. sandbase_discover({"q": "twitter posts"}) → pick a tool_name from data (each result carries description, pricing, vendor, run_count).
2. sandbase_inspect({"name": "sandbase_twitter_web_search_timeline"}) → read inputSchema and pricing; copy execute_as.
3. sandbase_run({"name": "sandbase_twitter_web_search_timeline", "arguments": {"keyword": "AI agents"}}).
   • Fast tools return status: "completed" with output directly.
   • Slow tools (video, music, large scrapes) return status: "running" plus prediction_id / taskId after up to ~20 s.
4. If still running, call sandbase_run_get({"run_id": "<prediction_id>"}) every 5–10 seconds until status is completed or failed. The finished output is in the response. If a completed run shows no output, fetch it with the CLI: sandbase runs get -r <run_id> -o result.json.

Agent Services (svc_… names from type: "service"): pass arguments: {"idempotency_key": "<unique>", "input": "..."}; reuse the same key and input on retries. Poll with sandbase_run_get({"run_id": ..., "service_id": "svc_…"}); succeeded, failed, and cancelled are terminal.

3. Transport B — CLI (fallback)

sandbase --version || npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz --version

If sandbase is not installed, prefix every command with npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz (or install it: npm install -g https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz). If the CLI prints "Update available", run npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz setup — it refreshes the CLI's MCP bridge and this Skill.

Authentication is automatic once the user has run connect (it reuses that browser sign-in). Otherwise the CLI reports AUTH_REQUIRED with the exact fix; an API key also works via SANDBASE_API_KEY or sandbase keys add -k <key>. Never ask the user to paste a key into the chat.

• Add -j for JSON output. Errors then look like {"error": {"code", "message", "hint"}}; follow hint.
• -w waits with backoff (default --timeout 300 seconds). If the run is still going when the timeout elapses, the CLI prints the runs get command to resume — use it rather than re-running (re-running is billed again).
• -o writes only the tool's output (no envelope). Files/URLs in the output are also listed in text mode.
• Exit code is 0 on success or still-running, 1 on failure (including a failed run), 2 on bad usage.
• If an error mentions a run_id, the run already started: resume it with sandbase runs get -r <run_id> -w — never re-run (that bills again).
• To store an API key without exposing it: printf %s "$KEY" | sandbase keys add -k -.

4. When to use SandBase — and when not

Check the catalog before building from scratch. Before writing a scraper, falling back to a generic web fetch for structured data, or telling the user you cannot access something, run a discover. The catalog grows continuously; you don't know what is there until you search.

Fill gaps, don't replace the user's stack. Precedence:

1. An explicit user instruction for this task.
2. The user's own dedicated tools: their MCP servers, API keys, CLIs, workflows.
3. Your built-in web search / fetch, when plain pages or snippets are enough.
4. SandBase, for whatever the above don't cover: structured data (posts, profiles, reviews, products), media generation, specific models, or when built-in tools are blocked or return unusable pages.

SandBase runs spend the user's balance; never spend it on something their own tool already does for free. When both could work and the user hasn't chosen, use theirs and mention SandBase only if it adds something.

Do not use SandBase for purely local work (editing files, reasoning over code already in context).