Skip to main content
An approved terminal lets an Interactive Agent run commands in a connected macOS or Linux environment. The runner can be your computer or a virtual machine running the RevoEngine CLI. The owner approves the terminal before a conversation can use it. Commands run with the runner’s operating-system account; its permissions remain an outer limit.

​
Connect a workspace

  1. Install the RevoEngine CLI on the runner and sign in with a personal API key.
  2. Choose an existing directory and run revo terminal connect --workspace "$HOME/projects/my-project" --name "Work VM".
  3. Open Settings → Vault → Terminals in the browser and approve the pending terminal. Workspace Access is the default command permission. CLI pairing alone does not authorize commands.
  4. Keep the CLI connection running, or install its per-user background service. An Assistant can use an approved online terminal and its approved workspaces directly; you do not need to pair it again for each chat.
  5. Describe the outcome you want. The Assistant can run workspace commands, inspect output, edit files, install packages and run tests within the permission boundaries below.
The owner can share an approved terminal with selected users, groups, or the instance. Sharing does not change the runner’s operating-system account. A conversation can use multiple approved terminals; its activity shows which runner handled a command.

​
One device, several workspaces

The CLI keeps a stable device registration across restarts. Connecting another directory with the same CLI profile and terminal name registers an additional workspace on that device. Approve it in the terminal’s Workspaces settings. Each workspace has its own access and sharing contract, bounded by the device permissions. An already-running device refreshes this contract without a second runner process. Preserve the CLI registration to keep using the same device; restarting the terminal does not itself require a new owner approval. The temporary or whole-thread permissions below apply to the selected chat, device and workspace. A permission for one workspace does not authorize another. If older duplicate registrations make the name ambiguous, select the intended registration explicitly with --terminal-id.

​
Use an updated runner

Current CLI releases verify the workspace location of the file actually opened before an upload can send bytes. Timeout, cancellation and permission expiry also retain ownership of the controlled process group through cleanup, rather than treating the command leader’s exit as proof that all its children stopped. These safeguards were introduced in CLI 1.0.34 and are included in CLI 2.0.0. Use revo terminal --help for current connection commands. Browser authentication profiles are managed in Revo Vault; terminal connect --browser-profile is obsolete and rejected. Explicit cleanup of an older local snapshot remains available through terminal browser-profile forget and does not remove a central Vault profile or revoke the website’s server-side login.

​
Permissions

Terminal permissions have two independent controls in Settings → Vault → Terminals → Permissions. The owner can change either setting while the runner is connected. The runner checks the current grants before each dispatch and stops work that loses required access. The terminal’s Full Access command setting is separate from the Composer permission mode with the same name.

​
Commands

​
Networking

The Assistant requests the command scope and network scope needed for each action. An explicit workspace command retains its workspace boundary. When no command scope is specified, the saved Commands grant selects workspace or host execution; saved Full Access with Full Network Access can also supply the default shell network scope. Select narrower scopes explicitly when needed. For example, Workspace Access + Full Network Access can download dependencies and write inside the workspace, but cannot write elsewhere. Full Access + No Network permits a requested host-level command to access files available to the runner account, while blocking its network connections. A temporary exception can broaden either dimension without changing the saved settings.

​
How the sandbox works

The workspace is the directory selected when connecting the CLI runner. Commands execute on that computer or VM, not in a separate RevoEngine-hosted filesystem. For a workspace command, the runner checks the working directory and launches the process with operating-system-enforced file and network restrictions. It can write in the workspace and a temporary working area; the restrictions block writes elsewhere. It can also read the system and toolchain files needed to run programs, so Workspace Access is not a promise that every file outside the workspace is unreadable. Files reached through links remain subject to the boundary. Child processes inherit these restrictions. On macOS, supported workspace shell actions can connect to localhost under Local Access. On Linux, the workspace shell remains isolated from host localhost; the local Browser action is available. Host commands with Local Access are unavailable on Linux until that boundary can be enforced. If the runner cannot enforce a required boundary, it rejects the action. Browser actions have their own controlled execution path and follow the networking grant. Full Access removes the workspace file boundary for a host-level command; it does not elevate the runner’s operating-system account. Use a dedicated account or VM if the runner has access to other projects, personal files, or credentials. With Full Network Access as well, a host-level command can reach external services and transmit data available to that account.

​
Approvals for elevated actions

The Assistant explains why an action needs host-level commands or more network access. Under Restricted or Full Access Composer, a missing command or network scope goes directly to you. Only Auto Review lets RevoShield assess that exact action first and ask you if it cannot safely approve it. Full Access Composer bypasses RevoShield; it does not supply missing terminal scopes. A saved Full Access command grant or Full Network Access grant covers its own dimension regardless of Composer mode. Destructive commands and secret access may still require separate review. When your decision is needed, you can approve the exact invocation once or grant the missing command or network scope for 15 minutes, one hour, eight hours, 24 hours, or this thread on this chat, device and workspace. A timed grant does not change the terminal’s permanent settings or authorize a different action after a one-time approval. It ends at expiry, explicit chat disconnect, or a change to the grant. Whole-thread consent has no time expiry, survives later messages and short reconnects, and ends on explicit disconnect, thread deletion or a grant change. It is not copied to a forked chat. A short runner reconnect can preserve a still-valid permission for the same chat, device and workspace. The runner checks authorization again before input or another action; work requiring an expired or revoked scope is stopped. The approval shows the proposed command or Browser action and the reason for elevation. Terminal activity in the conversation shows the runner, command, output, and execution status. Ordinary workspace actions within the available grants do not create an approval prompt for every read, edit, or test.
Full Access gives a requested host-level command broad control over everything the runner account can access. It can modify or delete files outside the workspace. Full Network Access can contact external services. Review the requested scope and destination when an approval reaches you. A terminal grant does not expand operating-system permissions.

​
Work with running commands

The Assistant starts a command and waits briefly for its result. A long-running command remains visible under its execution ID; its shell output and final status update in the conversation even if the Assistant continues with other steps. It can check status, cancel, send input, and resize a PTY for interactive programs. An ordinary command may run for up to 59 minutes. A compatible runner can keep an explicitly requested background process running without that fixed command deadline, while its authorization and runner remain valid. Startup output is not proof that a development server is ready; the Assistant should verify its URL. Several commands may run at once, subject to runner limits. If the runner’s connection drops, the CLI retries temporary transport or dependency failures and resumes the same execution without starting the command again. Recovery has a two-minute window; unsuccessful reconnects do not restart that window. Authentication failure or confirmed revocation stops recovery. If a dispatched operation has no confirmed outcome, inspect its status and target before repeating a command with side effects. A reconnect alone does not prove that the operation completed. The Assistant can request a connection refresh while the CLI remains running. Recovery can continue through renewed permission or a clarification when user action is required. It cannot wake a stopped CLI or reconstruct processes that ended when the CLI stopped. Internal status checks are omitted from the visible activity list; the original command still shows its progress and outcome. The Assistant can apply a workspace patch without asking for each ordinary edit. Browser actions can navigate to an HTTP(S) page, inspect visible page text, interact with forms, and take a screenshot. The CLI installs the required browser runtime; a separate browser installation is not required. The activity shows the visited URL and page output. User-facing screenshots are attached to the conversation; private screenshots used by the Assistant for visual inspection do not create a chat attachment. Browser access follows the terminal’s network grant and any temporary exception. For a password or similar secret field, the Assistant can request a secure input popup: the value goes directly to the connected browser session and is not included in the model-visible tool call. A successful secure fill confirms only that the field was filled. The Assistant then submits the authorized login form once and checks a fresh result. An error left from the previous attempt is not evidence that the new value was rejected. The conversation shows background progress and the next required action without a manual refresh. The browser runs as a dedicated controlled action, separate from the shell’s operating-system sandbox.

​
Browser state and limits

Each conversation owns its browser tabs, selection and human-control boundary. Tabs survive later messages and short connection recovery while the runner and browser remain alive. Compatible conversations can share the live website login of an authorized Vault profile on the same user, instance, terminal, workspace and network mode. Login or logout affects that shared website identity; closing one conversation closes only its tabs. The runner permits four browser contexts, with one hour of idle retention. A shared context supports up to sixteen conversations and thirty-two tabs in total, with at most sixteen tabs per conversation. Active contexts are not silently evicted. Inspect the authorized session inventory before closing an unused session; another user’s sessions are not exposed through Assistant inventory. Manage profiles in Settings → Vault → Browser Profiles and select an assigned profile in Live Preview. Compatible macOS and Linux runners support them, including service mode. The former connection flag is no longer supported. Profiles can retain cookies, local storage and IndexedDB; treat saved state as sensitive website authentication. It never extends network permission or guarantees that a website still accepts the login. Closing the last live session does not clear saved Vault state. The legacy forget command affects only an old local snapshot. See browser profiles for access, migration and clearing state. Choose Local Access or Full Network Access before starting a login flow. A localhost application can require Full Network Access for remote APIs, assets or sign-in. Changing scope can recreate a context: do not expect tabs or unsaved forms to survive; a compatible profile can restore its last saved website state. A shared profile context keeps its current mode, and every joining conversation needs its own lasting permission for that mode. Timed or one-time approvals cannot join a shared context. A one-time approval closes an independent context after that action; a timed or whole-thread permission can support continued independent browsing. Slow pages can use an explicitly increased browser action timeout, up to two minutes. This changes the wait for that operation; it does not extend permissions or automatically repeat a click or submission. To show images created by a command, the Assistant can attach up to 32 PNG, JPEG, or WebP files from the workspace per upload request (240 MiB total). Larger collections require separate requests. User-facing browser screenshots attach automatically. The runner uploads them securely; RevoEngine then attaches them to the conversation. The Assistant loads their pixels in the next model step only when it explicitly needs to inspect them. Uploading workspace images requires Full Network Access or a temporary full-network exception. If a side-effecting command has an uncertain outcome after recovery, inspect its status before trying it again. Starting it twice could repeat its effects.

​
Transfer workspace files

On a compatible runner, the Assistant can upload an authorized workspace file to Storage or download a Storage file into the workspace. File bytes travel directly between the runner and managed Storage using a short-lived upload or download URL; the terminal connection carries control and completion metadata. Full Network Access or its approved exception is required. Treat transfer URLs and their required headers as credentials and keep them out of source files and logs. An upload must finish before its Storage upload session is finalized. Resumable uploads can continue from the confirmed committed offset; an uncertain write must be checked before retrying. Downloads use a temporary file and become visible at their destination only after successful completion. Existing files are preserved on failure and overwritten only when explicitly requested. Transfers have a 90-second idle timeout, rather than a short fixed total duration. Permissions, URL validity, available disk space and runner lifetime still limit a long transfer.

​
Keep a terminal available

The foreground revo terminal connect command works while the CLI runs. A terminal can remain registered for months, but live command and browser state depends on the running process. Presence and last-online time describe connectivity; they do not grant access or create a configuration version. Configuration changes have their own revision and Activity history. After approval, you can install a per-user background service on macOS or Linux:
Use the same CLI profile to manage the device service. The service remains associated with the device’s original service directory even when it serves several registered workspaces. Newly installed services restart eligible failures and stop after fatal authentication or revocation errors. Reinstall an existing service to adopt the updated supervisor behavior. A background service keeps the runner available; it does not make browser cookies or ordinary command processes durable across a runner restart.

​
Disconnect and revoke

Disconnecting a runner from one conversation removes that conversation’s connection. It does not revoke the owner’s terminal grant or stop an already-running process. The owner can remove the terminal in Settings → Vault → Terminals to revoke its grant. To remove a locally registered runner, stop its background service first if installed:
The terminal settings and conversation show activity for authorized viewers. A pending request or offline runner cannot execute commands. An approved online workspace can establish its conversation connection automatically.

Browser workflows

Start with public reads, interactive sessions, Live Preview, private takeover and profiles.

​
Live Preview and human control

On a compatible updated runner, open Live Preview from browser activity or the browser shortcut beside the terminal control in Composer. The shortcut appears for the current chat after a successful browser operation, or while a pinned human step is waiting. It returns to the same device, workspace, session and tab after you minimize the floating preview. The preview shows the local browser at up to five frames per second. The browser can reach localhost services on the connected device, subject to its network permissions. Observing does not give control. Explicit takeover pauses the Assistant’s browser actions across that context and lets you click, drag, scroll, type or switch tabs. Passwords and one-time codes are handled privately by the connected browser. Finish the human step to return control; the Assistant checks the fresh page before continuing. Disconnect does not silently hand control back. The Assistant can inspect a focused image and use coordinate interactions when DOM selectors are insufficient. It attempts CAPTCHA solutions with bounded retries and checks the result; a blocked challenge falls back to your same-session preview. MFA approvals and secret codes still require you. During takeover, create or select a named encrypted profile and choose it as the default for this user, instance, device and workspace. A later chat restores that selection automatically; you do not need to ask the Assistant to save it in memory. Profiles follow the compatible runner and shared-session boundaries described above. Website authentication and current network permissions still determine access. Recording is opt-in: select a local file, private Storage, or both. Native WebM segments pause around private input and authentication work. Storage files are restricted to the owner and verified after upload. Existing repository Playwright E2Es continue through terminal commands in their own test contexts; Live Preview shows the connected browser’s current session.

​
Public page retrieval fallback

Public web research tries direct page retrieval first. When a page fails to load or needs JavaScript to expose readable content, a compatible connected terminal can render it in an isolated browser with existing network authorization. This read uses no saved login profile or cookies, cannot interact with the page, and closes its temporary browser resources when finished. The chat’s interactive browser and Live Preview stay available. The fallback does not grant network access or guarantee access to pages protected by authentication, CAPTCHA or other site restrictions. Successful pages in a batch keep their direct-retrieval results.
Last modified on November 11, 2026