Agent powerkit

VC Tools

VC Tools gives agents a hosted, metered, account-scoped way to inspect the web, run bounded diagnostics, store evidence, and track jobs without borrowing the user's local machine or raw provider credentials.

VC Tools beta agent powerkit guide for Vibecodr browser QA, sandbox diagnostics, artifacts, jobs, and API-key setup.

Implementation focus

Use this when installing `@vibecodr/vc-tools`, creating an API key, connecting an MCP-compatible agent, reading usage, or deciding whether browser QA, sandbox diagnostics, artifacts, jobs, and retention belong in the hosted tool service.

Expected outcomes

What vc-tools is

Vibecodr Tools is the beta agent powerkit for web-aware diagnosis. The local `vc-tools` command helps a human or agent connect to hosted browser checks, sandboxed diagnostics, artifacts, durable jobs, usage, grants, retention, plans, dashboard links, inspect output, and doctor checks without turning the user's machine into the execution boundary.

The product is separate from the Vibecodr CLI. Use the Vibecodr CLI for ordinary Vibecodr terminal workflows, and use `vc-tools` when an agent needs controlled browser QA, runtime diagnosis, sandbox command checks, or durable evidence around a tool run.

  • Browser tools render public HTTPS pages, capture screenshots, extract page text, and produce PDFs.
  • Sandbox tools submit bounded command or test diagnostics to the hosted service instead of running locally.
  • Artifacts store screenshots, reports, logs, files, and long outputs so agents can reference evidence after a run.
  • Jobs let users list, inspect, and cancel longer work without losing status once a request starts.

How plans and limits work

VC Tools is included with Vibecodr plans as its own allowance. Build minutes and VC Tool credits are separate buckets inside the same subscription, so a busy build does not consume browser QA credits and a browser-heavy agent run does not consume build minutes.

Free keeps a small beta floor for evaluation. Creator and Pro are the paid-plan lanes meant for regular use. Current plan packaging is visible in pricing, `vc-tools plans`, and the usage screen; hosted enforcement is the final authority when a request would exceed the account's current allowance.

  • Free: 30 VC Tool credits per month, 10 per day, 1 concurrent run, Quick Actions only, 10 crawl pages per run, 25 crawl pages per month, depth 1, no scheduled QA.
  • Creator: 600 VC Tool credits per month, 90 per day, 2 concurrent runs, Quick Actions only, 50 crawl pages per run, 500 crawl pages per month, depth 2, 30 scheduled QA runs per month with a 12 hour minimum interval.
  • Pro: 3,000 VC Tool credits per month, 400 per day, 5 concurrent runs, capped Browser Sessions, 250 crawl pages per run, 5,000 crawl pages per month, depth 4, 300 scheduled QA runs per month with a 1 hour minimum interval.
  • Build limits stay separate: Free includes 30 build minutes per month, Creator includes 750, and Pro includes 4,000, with daily, job, concurrency, output size, and output file caps shown on the pricing and limits surfaces.

Set up access safely

Create an API key from account settings, put it in a local file or pipe it through stdin, and let `vc-tools login` exchange it for a scoped Vibecodr Tools grant. The CLI stores the grant in the local credential store; the raw API key is not the long-lived stored credential.

Compatible clients that already hold a signed-in access token can use the OAuth-token login path, but API keys are the normal human setup path. Both paths should lead to scoped grants that carry the account, plan, workspace, and tool permissions needed by the hosted service.

  • Prefer `vc-tools login --api-key-file vc-tools-api-key.txt` or `vc-tools login --api-key-stdin` over command-line secret arguments.
  • Use `vc-tools status` to confirm the active profile without printing secrets.
  • Use `vc-tools connect` to get Streamable HTTP MCP connection metadata for compatible agents.
  • Use `vc-tools grants list` and `vc-tools usage` to understand what the current account can run.
Secure first setup powershell
npm install -g @vibecodr/vc-tools
vc-tools login --api-key-file .\vc-tools-api-key.txt
vc-tools status
vc-tools connect --client generic
vc-tools tools list

Artifacts, storage, and isolation

Artifacts live in the hosted Vibecodr Tools artifact store by default, not in a creator's editable source capsule or normal project storage. They are meant for run evidence: screenshots, PDFs, logs, reports, command output, and other files an agent may need to inspect or pull down after a job.

Artifact list, metadata, and download requests are checked against the authenticated account before bytes are returned. Knowing an artifact id is not enough to fetch another user's output. Retention settings decide how long artifacts remain available, and expired artifacts should be treated as unavailable even if a job record still exists.

  • Artifacts count against VC Tools and artifact policies, not against build minutes.
  • Pull artifacts locally when a user wants to move evidence into their own workspace.
  • Do not use VC Tools artifacts as permanent app storage, source storage, or a public file bucket.
  • Use retention controls when evidence should expire sooner than the plan default.

What agents should use it for

VC Tools is strongest when an agent needs to interact with the web like a careful QA assistant: render a public page, compare mobile and desktop output, capture console or network evidence, produce a PDF, check metadata, run a bounded diagnostic command, and return durable proof instead of a vague guess.

It is not sold as unlimited scraping infrastructure or a long-lived browser farm. Browser Sessions are capped and Pro-only while the product is in beta. Quick Actions are the default path for screenshots, rendered-page inspection, markdown extraction, PDFs, visual checks, and most scheduled QA.

  • Good fit: render checks, runtime diagnosis, screenshot proof, accessibility quick scans, SEO metadata checks, visual diffs, PDFs, and sandboxed test diagnostics.
  • Poor fit: bulk crawling the open internet, arbitrary web automation, long-lived browser agents, user-controlled scraping infrastructure, or platform-funded repair loops without clear user action.
  • Agents should reserve a run only when they have a concrete target and expected output.
  • When a request is denied by quota, concurrency, auth, or URL safety policy, slow down or ask the user for a safer target instead of retrying blindly.

Beta support expectations

VC Tools is available as a beta surface. Commands, quotas, and tool availability may change while the product is hardened, but the public contract should remain straightforward: account-scoped auth, hosted execution, separate usage accounting, public-safe diagnostics, and durable evidence.

When something fails, classify it before retrying: credential setup, plan limit, unsafe URL, unsupported tool, hosted job failure, artifact expiry, or service health. Include command name, job id, artifact id, status, and public error fields in support reports, but never include raw API keys, grant tokens, private source bundles, or credential-bearing URLs.

  • Use `vc-tools doctor` for local and hosted health checks.
  • Use `vc-tools inspect` for release-readiness and goal-coverage evidence.
  • Use `vc-tools help <command>` for focused command help.
  • Use support diagnostics when a public error includes an `errorKey`, request id, or retry hint.

Example and read next

Example: an agent needs proof that a public launch page renders correctly on desktop and mobile. Use `vc-tools` for hosted render checks, screenshots, artifact evidence, and usage visibility instead of giving the agent local browser control or raw provider credentials.

Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system.

Related documentation

  • /vc-tools
  • /plans
  • /docs/mcp-cli
  • /docs/support-diagnostics
  • /docs/account-safety-controls