Skip to main content
Deploying gives the agent its own URL on Viorant Cloud. It keeps running whether your terminal — or the Hub — is open or not.
Needs vio 1.0.0 or later for credits deploys. The saved run key, --show-run-key and --verbose-logs need 1.0.6. Check with vio --version.

​
Before you deploy

  • Sign in with vio login.
  • Make sure vio validate agent.vio passes. A stale digest is refused at deploy — see Validate a .vio file.
  • Check you have room: vio status shows how many agents your plan still allows.
  • Decide how the agent pays for its model: Viorant credits, or your own provider key.

​
Credits or your own key

The bundle decides, through its agent’s model reference.

​
Viorant credits

An agent whose model is one of Viorant’s managed models runs on your wallet. There is no provider key to find, store or send:
agent.vio (the agent artifact)
Three tiers, all under provider://openai-compatible/: vio providers prints this same list, with Viorant credits shown first. A bundle deploys on credits only when every agent in it uses one of these tiers; anything else — including a mix — is treated as your own key.
A high agent deploys fine on Free or Starter — the tier is not checked at deploy time. But every run then fails with plans.tier_not_allowed, because the plan is checked per run, not at deploy. Use low or mid unless the account is on Pro — check with vio status.
Changing the model changes the agent’s body, so run vio digest agent.vio --fix after the edit. Before a credits deploy, vio prints one line:
The deploy itself spends nothing. Each run of the deployed agent does. vio status shows your balance. A credits agent runs on Viorant Cloud only.

​
Your own key (BYOK)

Any other model — provider://openai/gpt-4o-mini, provider://gemini/… and so on — runs on your own provider key, which vio seals on your machine and delivers straight to the deployment. Inside a Space, vio init creates .vio/.env.provider, you fill it in, and vio deploy reads it. .vio/ is git-ignored, so the key never reaches a commit.
.vio/.env.provider
VIORANT_RUNNER_PROVIDER_KIND must match the bundle’s model: a provider://gemini/… agent needs gemini. If they differ, vio refuses before anything is sent, names both, and says Nothing was deployed. — otherwise the agent would wait forever for a key it never gets. vio providers lists every kind and the key variable it needs. Outside a Space — a loose .vio someone sent you — pass a file explicitly with --env-file, kept outside the repository and never committed. An --env-file always wins over the Space’s own credentials.
Credentials are read from the Space that holds the bundle you are deploying, not from the folder you happen to be standing in. vio deploy ../other-agent/agent.vio uses ../other-agent’s key, not this one’s.

​
Deploy

From the shell:
Or as a subcommand, which is what scripts, CI and AI agents use:
vio validates the file on your machine — the same checks as vio validate — then asks Viorant Cloud to stand the agent up.
  • --env-file <file> names the credentials file.
  • --name "My agent" sets the deployment name; it defaults to the name in the file.
  • --verbose-logs records each tool call’s arguments and result in the agent’s run logs. See Deployment logs. It works with --target viorant_cloud only; a local container refuses it, because its logs are on your machine.
  • --show-run-key prints the run key. See Call the agent.
  • --json prints one JSON object, for scripts.
All of these work in both forms, in the shell and as a subcommand. If you ran vio connect first, vio deploy pushes the staged connectors in the same request, and the agent comes up connected. Before it creates anything, it also checks the tool names your bundle declares against what each staged connector offers. A name the server does not offer stops the deploy. If the agent has OAuth connectors that are still not connected after a Viorant Cloud deploy, an interactive terminal asks Authorise them now? [Y/n], which opens the same consent as vio connect. Without a terminal, vio prints the vio connect follow-up instead.
Deploying creates an internet-reachable service that counts against your plan’s agent limit, and — for a BYOK agent — sends your provider key to it. vio itself never prompts — if a coding agent runs it for you, whether it asks first is your agent’s permission setting, not vio’s. See Use vio with AI coding agents.

​
Call the agent

On success, vio prints the deployment id and its URL. It also mints a run key, the bearer secret that lets something call the agent. For a Viorant Cloud deploy, vio saves the key to ~/.viorant/run-keys.json, keyed by the deployment, and does not print it:
That saved key is what vio run uses, so for a call from your own machine you never need to handle the key. To call the agent from somewhere else, ask for the key:
--show-run-key prints the key and a paste-ready request. vio also prints the key if it could not save it, because that is the only copy. A local container (--target local_docker) always prints its key. In --json, a saved key reads [redacted] unless you pass --show-run-key. Never paste a run key into chat or a commit.
The printed request has an example body built from the inputs your agent declares. Lost the key, or deployed from another machine? You can’t recover it. Issue a new one with vio run-key <id> --rotate, which kills the old key at once. To run it on a timer instead, see Schedule an agent.

​
Connectors

Authorising a deployed agent’s connectors — including ones that need your own OAuth app — and the built-in tools every agent can use (web_fetch, current_time, and web_search with its Tavily key) now have their own page: see Connectors and tools.

​
Next