Skip to main content
Needs vio 1.0.0 or later. Connecting before you deploy needs 1.0.4, and --deployment, --scopes, the kept stage and vio connectors tools need 1.0.6. 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 catalogue entry. In vio 1.0.6 it does not list the connector’s tools. For those, authorise the connector and run vio connectors tools.

List a connector’s tools

Prints the exact tool names a connector offers, so you copy them into requires[].tools instead of guessing. <connector> is a catalogue id or an MCP server URL. It needs a Space and an authorisation that vio connect <connector> already staged, and it reads the tools with that authorisation. Nothing is written except a token that had to be refreshed, and no token is ever printed. --json prints {connector, serverUrl, tools}. If the provider refuses with insufficient_scope, the message names the connector and the scope it says is missing, and gives the vio connect <connector> --scopes … command that fixes it.

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. connector must be an https:// URL. A catalogue id such as github works on the command line, where vio connect github resolves it to the connector’s MCP URL, but it is refused in requires[].connector: vio validate fails the bundle and prints the URL to use instead. 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 tools <connector> — after vio connect <connector>, it prints the connector’s tools. Use them exactly as printed. (vio connect <connector> --json also carries them, as toolNames.)
  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. vio checks for this before you get that far. vio deploy asks each staged connector, before it creates anything, whether the tool names your bundle declares (in requires[].tools and in each skill’s allowed-tools) are on it. A name the server does not offer stops the deploy and names the closest real tools. A connector that is unreachable, or that refuses the check, is only a warning. vio validate --check-tools runs the same check without deploying. After the first deploy, still 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

vio connect has three forms. You can connect before you deploy, which is the order a coding agent follows. You can finish or re-authorise all of a deployed agent’s connectors. Or you can authorise one connector on a deployed agent and leave the rest as they are. In the shell it is /connect, with the same options. Connect before you deploy. Name the connectors — catalogue ids from vio connectors, or MCP server URLs — and vio connect authorises them with no deployment at all:
Run it from a Space (vio init first), signed in. Each connector’s consent runs in your browser, one at a time, and each token is saved as soon as it succeeds, so a later connector failing never loses an earlier one. A connector that fails is reported and the rest still run. Tokens are staged in .vio/connector-tokens.json, a file only you can read (mode 0600), inside the git-ignored .vio/. vio connect refuses to stage anything where git could commit it: if the Space is a git repository and .vio/ is not ignored, it stops before any consent and tells you to add .vio/ to .gitignore. Then vio deploy pushes the staged set in the same request as the deploy, so the agent comes up connected. The deploy report says which connectors were pushed from the staged set and which are still not connected; for those, run vio connect <deployment id>. Running vio connect again for a connector that is already staged reuses it, refreshing an expired token where it can, instead of asking you to consent again.
  • --no-browser prints every authorisation URL together, numbered, so you can approve them in any order. Without it, connectors are authorised one at a time. Either way the authorisation URL is printed to stderr before vio tries to open a browser, so it is there if no browser opens.
  • --scopes sets the OAuth scopes, comma-separated, in the provider’s own names. It takes exactly one connector. See Scopes.
  • --forget removes staged and kept tokens: the connectors you name, or every one with none named. It deletes the file once nothing is left. vio logout also deletes the tokens in the Space you run it from.
  • --json prints one JSON object. For each connector it carries the tools count and the tool names as toolNames, and the scopes requested and granted.
  • If a provider refuses, vio connect explains the refusal in plain words and what to change, rather than printing the provider’s raw response.
Connectors that need your own OAuth app work the same way before a deploy. See Connectors that need your own OAuth app.

A push keeps the stage

A push does not delete what it pushed. After vio deploy or vio connect pushes a connector, .vio/connector-tokens.json keeps that connector’s entry under frozen[<deployment id>]. A kept entry is frozen: vio never refreshes it and never uses it as a live credential, because from the push on the agent owns that token. It exists so a later push can send the same document again, byte for byte.
  • Entries are kept per deployment. A push to one agent never touches another’s.
  • vio stop lapses a stopped deployment’s kept entries.
  • vio connect --forget <connector> clears the ones you name, and vio logout deletes the whole file.
  • If .vio/ is not git-ignored, the push still happens, nothing is kept, and vio says so.

Authorise one connector on a deployed agent

Authorises just that connector and pushes the whole credential document: the new entry, plus every other connector’s kept entry re-sent unchanged. Use it to add a connector to a deployed agent or to authorise one again. The bundle in the current folder must be the one you deployed, and the connector must be one it declares. After a vio redeploy, vio prints this exact command for each staged connector.
  • It takes exactly one connector, a catalogue id or an MCP server URL.
  • --scopes and --forget cannot combine with it. For a deployment, the bundle’s requires[].scopes sets the scopes. Each of these is a usage error and exits 2.
  • It needs the agent’s runner to report the secrets-lineage capability, which vio reads from the deployment. Without it, vio will not push one connector on its own. It says so in one line and authorises every connector again.
  • If this machine keeps no credential for a connector the deployment has (another machine pushed it, or its entry was forgotten), vio prints No kept credential on this machine for … and authorises just those once. It never pushes a document that drops a connector.

Finish or re-authorise a deployed agent

If the agent uses connectors that need sign-in (for example Notion or Google Workspace) and any are not connected yet, or you want to authorise them again, give vio connect the deployment. There are three forms:
The id can be the full id, a unique prefix of at least six characters, or the deployment’s exact name. A path (a .vio file or a folder holding one) picks the live hosted deployment that vio deploy made from that bundle. If several match, vio asks you to choose in a terminal, and otherwise names them and stops. vio prints Connecting <name> (<id>)… first, so you see which deployment it picked before anything is authorised. With only a deployment, vio connect first lists each connector as connected, pending or local entry only (an entry on this machine that is not on the agent yet). It authorises only the pending ones with no usable entry. When every connector is already connected, nothing is consented and nothing is pushed, and it prints the vio connect <connector> --deployment <id> command for authorising one again. It then pushes all of the agent’s credentials — connector tokens, the provider key or Tavily key, whichever apply — in one write. --no-browser prints each authorisation URL instead of opening a browser.
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.

Scopes

A connector asks the provider only for what it is given, in this order:
  1. --scopes a,b on vio connect <connector>.
  2. The bundle’s non-empty requires[].scopes for that connector.
  3. vio’s default for the provider: a short, read-leaning list for Slack, GitHub, Supabase, Google Cloud Logging and Google Workspace.
  4. Nothing. No scope parameter is sent and the provider chooses.
The server’s own advertised scopes are never used. Before each consent, vio connect prints which scopes it is requesting and where they came from. Afterwards it prints requested: … · granted: … for each connector (in --json too), and a notice when the provider granted something different. A staged authorisation whose granted scopes differ from the bundle’s requires[].scopes is not pushed. vio deploy and vio connect <file.vio> report that connector as not connected, name the gap, and authorise it again with the declared scopes.

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?

After any connector push, vio does not hope. It watches the agent’s heartbeat for up to about 90 seconds and reports each pushed connector as one of:
  • picked up — the agent loaded the credentials. ✔ Credentials pushed — the agent picked them up.
  • still pending — the agent has not taken it yet. vio prints the next step.
  • errored — the agent could not use it. The reason is printed.
  • applies on next run — you re-authorised a connector the agent already held connected. An agent sends no heartbeat for new credentials alone, so vio cannot see the pickup. It says the push landed and the agent loads it on its next run, and never calls that “picked up”. In --json the status is applies_on_next_run.
vio connect exits 1 when something needs your action (a connector still pending or errored), and exits 0 for applies_on_next_run. The same check runs after vio deploy pushes staged connectors. An agent deployed by an older vio, one that predates live reload, is not waited on. vio tells you to run vio redeploy <id> instead. Check any time with vio show <id>.

Exit codes and pipes

Do not pipe vio connect through another command. A pipeline’s exit status is the last command’s, so vio connect … | sed reports success even when the connect failed, and grep buffers its output, so the authorisation URL you need can arrive late. Read --json (the result is on stdout, a failure on stderr), or run with set -o pipefail, and branch on the exit code.

If the provider refuses your OAuth app credentials

For a connector that uses your own OAuth app, a refused client id or secret gets a specific message. It says which half is likely wrong, so you check only that key in .vio/.env.connectors. It also lists near-miss names found in that file, such as a lower-case google_oauth_client_id. A secret you just created or rotated can take a minute to take effect, so the message says to wait and run vio connect again. In a terminal, vio offers Try again? [y/N].

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

  • Deploy an agent — credits vs BYOK, and calling the deployed agent.
  • Manage deployments — list, runs, logs, redeploy and stop.
  • Jev — the one connector with its own dedicated page: TypeSafe’s guardrail model, hosted by Viorant, with its full requires[] block and tool list.