Using Vyre

Agents

An agent is a named record that says how Vyre should run sessions for you on your own server: which credentials, which projects, what instructions. Its work happens in ordinary headless threads that Vyre owns, so each one keeps running after you close a window or turn off your laptop, streams to every surface, and routes its permission questions to wherever you are, your phone included. An agent's sessions start on Claude. When Claude's usage runs out, the session can move to Codex, Grok or OpenRouter if you set a fallback order for the agent (see Sessions). Every install has one special agent, the assistant, made at onboarding. You can make others, such as a research agent or a bookkeeping agent.

An agent never draws context from a project outside its list: its brief, its prompt hints and its recall.search stay inside those projects' folders.

Talk to the assistant or an agent#

From Lumen, press Control twice and type. The assistant is the default destination; type @ to pick another agent, a project or a thread. The "Sends to" row shows where Enter will send before anything goes.

From the terminal:

vyre agents ask juno "What changed in the Juniper Studio project this week?"

  juno › Two threads ran in Juniper Studio this week: ...
  thread 3f9c2a71 · $0.0123

vyre agents ask waits up to ten minutes for the reply. Or run vyre with no arguments, pick an agent under Agents, and talk a line at a time. An empty line goes back to the list.

In the Vyre app, open Assistants (/u/assistants) for every assistant and agent and what it is doing. Open one for its page: a line to talk to it, what wakes it, its usage, its model and its computer. Search (Command-K) asks the assistant what you type, and @kit ... there asks kit.

If an agent stops on a permission question, the reply says so and names the question. Answer it from any surface; in the terminal:

vyre threads answer <ask> allow

The tool is agents.ask {agent, text}. It sends to the agent's current thread, resumes it if it stopped, and starts one if there is none.

Run an agent on your own quota#

Agents run on your own Claude credentials, kept in the Vault and set only in that agent's own child process. Two kinds of item work:

• A subscription setup token from claude setup-token, stored as a secret. Onboarding runs claude setup-token for you and stores the result as claude-setup-token.
• An Anthropic API key, stored as an api-key. Onboarding names this one anthropic-api-key.

The subscription is used first. When its limit is reached and the agent has an API key as a fallback, the thread switches to the key and says so in the thread, with the budget left. At 80% of the budget the thread is told; at 100% it stops, and the note says to raise it with vyre agents update <name> --budget <dollars>.

With neither item set, an agent uses the Claude Code login already on this machine.

To store your own and point an agent at them:

1. Store the token and the key. Each prompts for the value without echo:

   vyre vault put claude-setup-token --kind secret
   vyre vault put anthropic-api-key --kind api-key
   

2. Let the agents module release them:

   vyre vault grant claude-setup-token agents
   vyre vault grant anthropic-api-key agents
   

3. Point the agent at them, with a budget in dollars for the key:

   vyre agents update juno --vault claude-setup-token --fallback anthropic-api-key --budget 20
   

If this happens

"juno cannot start: ..."#

The item named by --vault is missing, has no value, or is not granted to agents. Check it with vyre vault list, then grant it. A missing fallback key does not stop the agent: it starts without one, and Vyre's log says so.

Make an agent#

vyre agents create kit --projects juniper-legal,northwind-bakery \
  --vault claude-setup-token --fallback anthropic-api-key --budget 20 \
  --instructions "You keep the books for Juniper Studio and Northwind Bakery."

  made kit  agent · juniper-legal, northwind-bakery

A name is lowercase letters, digits and dashes, starting with a letter, 2 to 31 characters. Flags: --projects a,b (or *), --model, --vault, --fallback, --budget (dollars), --instructions, and --assistant to make the one assistant. vyre agents update <name> takes the same flags and changes only what you name; the change applies from the agent's next thread.

In the Vyre app, New assistant (/u/settings/assistants/new) is a form for a new agent: a name, its projects, its job, what it runs on and the Its own computer switch. agents.create and agents.update also take an effort; vyre agents has no flag for it. Making or changing an agent asks for no passkey. It is yours: the CLI, the Vyre app, the Lumen and onboarding may call agents.create and agents.update. A model never edits an agent. Your assistant, or the agent itself, proposes a change to its instructions, skills, model, effort or tags (see project templates), the agent's owner approves it, and it is a version you can roll back. Any other agent, a bare MCP session and a guest are refused with "denied", and nobody is asked.

Make the assistant later#

If you skipped the assistant at onboarding, make it from a terminal: vyre agents create juno --assistant, with the flags you give it. To give it a computer, see Give an agent a computer.

See what agents are doing and what they cost#

vyre agents                 # every agent, the assistant first, with what each is doing
vyre agents threads kit     # its threads, newest first
vyre agents history kit     # what was asked of it, and its answers
vyre agents resume kit      # bring its latest thread back, with its own credentials
vyre agents usage           # turns, time, tokens, dollars against each budget, rate-limit state
vyre agents stop kit        # stop every running thread of kit; its record and transcripts stay
vyre agents delete kit      # remove the record; refused while a thread runs, and for the assistant

The matching tools are agents.list, agents.threads, agents.history, agents.resume, agents.usage, agents.stop and agents.delete. agents.delete is open only to your own surfaces (the terminal, the Vyre app and the Lumen), not to Claude.

In the Vyre app, Assistants shows the same list, and each assistant's page shows its Usage.

Give an agent a computer#

An agent can have its own computer: a container on your server with a desktop, Chrome and a terminal. Screens come from a small shared pool and are checked out only while the agent needs to look at something; an idle computer is frozen and its home volume stays. Computers need a machine that can run containers; on one that cannot, computers.list reports driver none.

Turn it on with computer: true on agents.create or agents.update, or Give kit a computer (with the agent's name) in the Computer section of its page in the Vyre app. Screen Share, which lets you watch the screen and take over the keyboard, comes in 0.3.1.

Two rules hold for every computer:

• Each agent has its own. An agent can start, stop, pause and read only its own computer. Naming another agent's computer is refused. Your assistant can, because it acts for you.
• Only you resume a pause. When a computer is paused, or you have taken it over, its hands refuse every input action. The agent cannot lift that, and neither can another agent or a model. Resuming is yours, and so is giving the keyboard back.

From a terminal:

vyre agents computer kit                          # its state, screen, cores and memory
vyre agents computer kit restart                  # a new container on the same home
vyre agents computer kit limits --cpus 2 --memory 4

A restart closes whatever is open on its screen and keeps its files and Chrome profile. New limits apply at the next restart.

The vyre home#

vyre with no arguments, from any folder, opens the home: every project, New session without a project, and every agent with what it is doing. Pick an agent to talk to it. See projects and threads for the rest of the home.

Which surface does what#

What it will not do#

• Let a model answer a permission question, its own or another session's.
• Give an agent other than the assistant the tools to drive other sessions.
• Let an agent act on another agent's computer, or resume its own paused one.
• Show an agent's token or key. It goes from the Vault into the agent's child process and nowhere else.
• Spend past an agent's budget on the API key.

Next#

• Vault: where the setup token and API key live.
• Watchers: things an agent can watch for you.
• Every tool: agents, threads, computers. Every command: vyre agents.