This page describes
ravi.bot@next.Add a machine to your organization
A machine joins your organization when someone runsravi login on it. Run it as the OS user that runs the daemon, so the daemon reads the same ~/.ravi.
1
Name the machine and log in
RAVI_CLI_INSTALLATION_NAME, the machine is named after its hostname. Other machines see its agents as <machine name>/<agent>, so pick a name people recognize.--no-open prints the URL and code without opening a browser. Use it on a server or over SSH, and approve from any other device. On a laptop, plain ravi login opens the browser for you.In the browser, pick the organization this machine works in. One login works in one organization.2
Check the login
Installation is this machine’s installation id. Scopes must include console.projects.link: without it the daemon cannot report its agents or take requests. If it is missing, run ravi login again.3
Choose the default project
--global covers the whole machine, and --agent overrides it for one agent. See Project scope for every level.What the Console learns at login
ravi login sends a short description of the machine with the login request. Nothing about agents, sessions or files is part of it.
The machine key is random and not derived from hardware. It survives
ravi logout, so the Console recognizes this machine when the same user logs in again. The Console also learns your user and organization from the browser approval.
The name is sent only at login, so set RAVI_CLI_INSTALLATION_NAME before you log in. Whether a later login renames the machine is decided by the Console.
Several Console users on one machine
Ravi keeps one stored login per Console user, and one of them is active.ravi whoami shows the active one. The daemon uses the active login for everything it sends: the agent report, pins and requests.
To switch users, run ravi login and sign in as the other user. The login that completes becomes the active one. There is no separate switch command.
ravi logout removes only the active login and makes another stored login active. Run ravi whoami after it to see who is active now.
What the Console sees
No agent is reported until its operator lists it. While a login withconsole.projects.link exists, the daemon reports the listed agents at start and every 5 minutes. The Console answers with the Library skills pinned to them.
List an agent
--execute. Unlisting applies at once and also closes the agent to requests. An unlisted agent leaves the Console’s Running agents at the next report. Its pins keep loading, but a new pin needs it listed (LIBRARY_AGENT_NOT_LISTED). Agents cannot list or unlist agents (LIBRARY_AGENT_CANNOT_LIST, exit 3).
What the report carries
The report never carries instructions, paths, credentials, sessions or messages. It covers at most 500 listed agents per machine.
Change the interval. Add
RAVI_LIBRARY_PIN_INTERVAL_MS to ~/.ravi/.env, in milliseconds, then restart the daemon. The minimum is 10 seconds, and the same interval sets how often the machine checks for requests.
ravi agents listing <id> on|off, ravi agents requests <id> on|off and ravi skills pin ... --execute.
What else reaches the Console
These features also send data to the Console. See Data flow for the full list.
Cost and token metrics stay in the local database unless you turn on trace upload.
Let other machines ask an agent
Every agent is closed to other machines until its operator opens it. An open agent answers each request in a session of its own, as the person who asked.Open an agent
--execute, and it also lists the agent. Closing only takes exposure away and applies at once; the agent stays listed until you run ravi agents listing <agent> off. Agents cannot open or close agents (LIBRARY_AGENT_CANNOT_OPEN_REQUESTS, exit 3).
The directory learns of the change right away when the login has console.projects.link. If the Console cannot be reached, it learns at the daemon’s next report. Without that scope, it learns nothing until you run ravi login again.
Ask an agent on another machine
<machine>is the name the directory shows. When two machines share a name, use the installation id instead (LIBRARY_TARGET_AMBIGUOUS, exit 2). The error lists each candidate’s id.- Asked from an agent session, the answer arrives in that session as a
[System] Inform. The text marks it as untrusted output from another machine. - Asked from the terminal, the answer waits in
ravi agents requests list --all. - Inside an agent, only the operator’s own turns may ask (
LIBRARY_REQUEST_EXTERNAL_DENIED, exit 3). An agent serving someone else does not carry that conversation to other machines. - Requests expire after 24 hours, and a machine can have 20 open at once.
How the asked machine answers
The asked machine runs one turn of its agent per request, in a new session that it retires once the answer or failure is sent. The prompt names who asked, from which machine, and through which agent or terminal. The turn acts as the person who asked, never with the operator’s authority. Ravi gives it no contact, so it holds no capabilities, like a message from an unknown sender (see What a turn may do). The agent answers in text, except for the gaps in the warning below.Share skills and agents across the organization
The Console Library holds skills, agent definitions, themes and widgets. Each item belongs to the organization (--scope org) or to one project (--scope <project>).
- The Console decides who may publish and who may pin. A person who may not publish proposes instead:
ravi skills propose,ravi themes propose,ravi widgets propose, orravi agents publish --propose. - Agents only propose skills, themes and widgets. They never publish items, pin skills, install, update or publish agents, or set the active theme (exit 3).
- A pinned skill loads in every new session of that agent, at the latest published version. A skill published without
--externalloads only in the operator’s own turns. - If a sync fails or the Console is unreachable, the machine keeps the last pins and its cached copies. Pinned skills keep loading.
- An agent definition never brings routes, instances, contacts or credentials.
Remove a machine
Today you unlink a machine by logging out on it. What the Console shows for that machine afterwards is decided by the Console.1
Unlist its agents
2
Unpin skills you want gone
unpin needs the login. Pins already on the machine stay after logout, and new sessions can still load them.3
Log out
ravi logout asks the Console to revoke the login, then deletes the local credentials. If the Console cannot be reached, it still deletes them and prints Console revoke did not complete: <code>. Repeat until ravi whoami says AUTH_REQUIRED, since each run removes one stored user.ravi login.
When a token refresh fails with INSTALLATION_REVOKED from the Console, the CLI deletes the local login and asks you to run ravi login again.