Skip to main content
Needs vio 1.0.0 or later. Check with vio --version.

​
Browse the connector catalogue

Lists the connectors a .vio bundle can declare — no sign-in needed. term filters by name; narrow further with --category <category>, --auth <dcr | pre-registered | none> or --verified. --json prints the machine-readable form. vio connectors <id> shows one connector’s detail, including the tool names it exposes — the first place to look when you need a tool’s exact name (see below).

​
Declare a connector in agent.vio

A connector is a requires[] entry:
connector is the MCP server URL, auth is oauth or api_key, and tools is the explicit list of tool names this dependency may call — never a wildcard. The moment the agent has any skill, requires[].tools stops being what grants a tool. Each skill’s own allowed-tools frontmatter becomes the only source of what that skill can call — a space-separated line, not a YAML list:
requires[].tools still has to list every tool the bundle uses (it is what vio validate checks connector reachability against), but for a 0-skill agent it is also the entire grant; for an agent with one or more skills, a tool absent from a skill’s allowed-tools is unavailable to it even if requires lists it. See Use vio with AI coding agents and the Space’s own VIO-AGENTS.md (vio docs agents) for the full worked example.

​
Where the real tool names come from

requires[].tools and allowed-tools both need a tool’s exact name — never a guess, and never the connector’s id. Work through these in order:
  1. vio connectors <id> — if it lists the connector’s tools, use them exactly as printed.
  2. Your own coding agent’s MCP session, if you have the same service connected there — it shows tools as mcp__<server>__<tool>; the part after the server prefix is the exact name.
  3. The provider’s own MCP server documentation.
  4. Ask a human. Never invent one.
A name the runner can’t match is silently skipped at run time — no error anywhere — so after the first deploy and vio connect, run the agent once and check its output or vio logs to confirm the tool was actually called. allowed-tools also only ever takes individual tool names: a connector-level reference like atlassian or atlassian__* does not resolve.

​
vio connect

If the agent uses connectors that need sign-in (for example Notion or Google Workspace), authorise them after deploying. vio connect is subcommand-only — there is no /connect in the shell:
Run it from the Space, or pass the bundle as a second argument: vio connect <deployment id> ./agent.vio. The id can be the full id, a unique prefix of at least six characters, or the deployment’s exact name. vio runs each connector’s consent in your browser, one at a time, then pushes all of the agent’s credentials — connector tokens, the provider key or Tavily key, whichever apply — to it in one write. Run the same command again to re-authorise. --no-browser prints each authorisation URL instead of opening it.
vio connect needs something to push. On a bundle with no OAuth connector it refuses with “This bundle declares no OAuth connectors, so there is nothing to authorise” — unless the bundle uses web_search, in which case (vio 1.0.1 or later) it skips consent and pushes the Tavily key on its own.

​
Connectors that need your own OAuth app

Most connectors register themselves. Some — Google Workspace, GitHub, Slack, HubSpot and Asana among them — need an OAuth application you create with the provider. For those, vio connect:
  1. Shows the redirect URI first, before it asks for anything:
    Add it to your OAuth app, and save the app.
  2. Asks for the app’s client id and secret. The secret is not echoed. Leave it empty for a public client.
  3. Offers to save them, once the authorisation has succeeded: Save to .vio/.env.connectors? [Y/n]. Saved credentials are read from there on every later run, so you enter them once.
They are stored as two lines in .vio/.env.connectors, named for the app:
.vio/.env.connectors
Every Google Workspace connector shares the GOOGLE_ pair. The others use GITHUB_, SLACK_, HUBSPOT_ or ASANA_, and any other host is named after the host itself — mcp.example.com reads MCP_EXAMPLE_COM_OAUTH_CLIENT_ID. You can also write the lines yourself before running vio connect. Without a terminal to ask on, vio connect can’t prompt: it prints the redirect URI and stops. Add the two lines to .vio/.env.connectors, then run it again.
OAuth app credentials belong in .vio/.env.connectors only. Never put a client id or secret in agent.vio — the bundle travels with the agent.

​
Is the agent ready?

vio connect reports what the agent says after the push, not what it hopes:
  • ✔ Connectors authorised — the agent is ready — the agent is serving with nothing pending.
  • ✔ Credentials pushed. The agent still reports <state> — the push worked and the agent hasn’t picked the credentials up yet. It lists what is still pending, and reloads them on its next run or within about a minute. Check with vio show <id>.

​
Before you run it

  • For a BYOK agent, have the same provider key you deployed with — in the Space, or the same --env-file. The push replaces every credential the agent holds, including its provider key, and a key of the wrong kind is refused before any consent.
  • A credits agent needs no provider key for vio connect either, and vio connect never pushes one to it — even if a key is set in the Space or the --env-file.
  • The bundle must be the one you deployed. If its digest differs, nothing happens.
  • Cancelling any consent pushes nothing; the agent keeps what it had.
  • Port 47219 on 127.0.0.1 must be free while it runs.

​
Built-in tools on a deployed agent

Three tools need no connector — they need no external MCP server, so nothing goes in requires[]. They’re granted the same way a connector tool is: by exact name, in a skill’s allowed-tools. Unlike a connector’s tools, these three names are fixed — there is nothing to look up in vio connectors or an MCP session for them. Use web_fetch, current_time and web_search exactly as written. web_search is powered by Tavily, and it always needs your own Tavily key — on Viorant credits too. Viorant credits pay for the model; they do not pay for search.
1

Get a key

Sign up at tavily.com and copy your API key — it starts with tvly-.
2

Add it to the Space

Put it in .vio/.env.connectors:
.vio/.env.connectors
3

Deploy

vio deploy reads it and sends it to the agent as a sealed secret — it is never written into the bundle, and no .vio file ever carries it.
Tavily bills you directly for usage; it is not metered through your Viorant wallet. Adding or rotating the key on an already-deployed agent depends on what else the agent declares:
  • The agent also has an OAuth connector. vio connect <deployment id> pushes the whole credentials document on every run, Tavily key included — update .vio/.env.connectors and run vio connect <deployment id> again.
  • Tavily is the agent’s only external dependency. With vio 1.0.1 or later, the same command works: update .vio/.env.connectors and run vio connect <deployment id>. There is no consent step — it pushes the key and reports whether the agent is ready. If no key is set, it refuses and pushes nothing. On vio 1.0.0, vio connect refuses a bundle with no OAuth connector, so the only way to add the key there is to stop the agent and deploy again (a new id, URL and run key) — or run vio update first.
vio redeploy never sets or rotates a key: it replaces the running bundle only and does not read .vio/.env.connectors. Without a key, every call to web_search fails — the run itself still starts and the agent still reports ready; only that one tool is unavailable. vio show does not flag the missing key, so if a search-using agent’s answers show no web results, check .vio/.env.connectors first.

​
Next