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
.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
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:
vio connectors tools <connector>— aftervio connect <connector>, it prints the connector’s tools. Use them exactly as printed. (vio connect <connector> --jsonalso carries them, astoolNames.)- 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. - The provider’s own MCP server documentation.
- Ask a human. Never invent one.
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:
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-browserprints 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 beforeviotries to open a browser, so it is there if no browser opens.--scopessets the OAuth scopes, comma-separated, in the provider’s own names. It takes exactly one connector. See Scopes.--forgetremoves staged and kept tokens: the connectors you name, or every one with none named. It deletes the file once nothing is left.vio logoutalso deletes the tokens in the Space you run it from.--jsonprints one JSON object. For each connector it carries thetoolscount and the tool names astoolNames, and the scopes requested and granted.- If a provider refuses,
vio connectexplains the refusal in plain words and what to change, rather than printing the provider’s raw response.
A push keeps the stage
A push does not delete what it pushed. Aftervio 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 stoplapses a stopped deployment’s kept entries.vio connect --forget <connector>clears the ones you name, andvio logoutdeletes the whole file.- If
.vio/is not git-ignored, the push still happens, nothing is kept, andviosays so.
Authorise one connector on a deployed agent
vio redeploy, vio prints
this exact command for each staged connector.
- It takes exactly one connector, a catalogue id or an MCP server URL.
--scopesand--forgetcannot combine with it. For a deployment, the bundle’srequires[].scopessets the scopes. Each of these is a usage error and exits2.- It needs the agent’s runner to report the
secrets-lineagecapability, whichvioreads from the deployment. Without it,viowill 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),
vioprintsNo 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, givevio connect the
deployment. There are three forms:
.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:--scopes a,bonvio connect <connector>.- The bundle’s non-empty
requires[].scopesfor that connector. vio’s default for the provider: a short, read-leaning list for Slack, GitHub, Supabase, Google Cloud Logging and Google Workspace.- Nothing. No
scopeparameter is sent and the provider chooses.
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:
-
Shows the redirect URI first, before it asks for anything:
Add it to your OAuth app, and save the app.
- Asks for the app’s client id and secret. The secret is not echoed. Leave it empty for a public client.
-
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.
.vio/.env.connectors, named for the app:
.vio/.env.connectors
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.
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.
vioprints 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
viocannot see the pickup. It says the push landed and the agent loads it on its next run, and never calls that “picked up”. In--jsonthe status isapplies_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
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 connecteither, andvio connectnever 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
47219on127.0.0.1must 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 inrequires[]. 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.
Tavily (web_search)
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.-
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.connectorsand runvio connect <deployment id>again. -
Tavily is the agent’s only external dependency. With
vio1.0.1 or later, the same command works: update.vio/.env.connectorsand runvio 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. Onvio1.0.0,vio connectrefuses 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 runvio updatefirst.
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.