Sign-in and maintenance

Find the right credential, keep the host running, and preserve the workspace when restarting or updating.

Token, browser session and instance

Login Token: The instance’s owner credential. Enter it only in that instance’s login form. A Desktop Token comes from Remote connection; a Server Token comes from its terminal or token command with the same data directory.
Browser session: Login creates a browser session for this origin. Another browser, changed origin or an expired session can require login again. Browser credentials are separate from Agent authentication.
Server restart: Server 0.4.1 persists authentication state in its data directory. Reuse that root; a different root means a different instance and credential. A session can still expire.
Desktop restart: Desktop Web must be enabled again after the App restarts. Get the current Token from the running Desktop rather than assuming an older saved credential remains valid.
Scope: This release is a single-owner instance. Do not share the Token as if it were a limited project invitation. HTTPS or Tailscale protects the route, not separate user roles.

Read paths and Token · same data directory

rovai-server --data-dir "$HOME/.rovai-server" paths
rovai-server --data-dir "$HOME/.rovai-server" token

Keep credentials private

On macOS 0.4.0 use the full current/rovai-server path described in Install Server. The paths command reports locations; token prints a secret. Do not paste that output into an issue, a screenshot or a shared terminal recording.

There is no documented rotate-token command in Server 0.4.1. If a credential is exposed, close the reachable entrance first and seek recovery guidance for that release. Do not delete the database or invent a token flag.

Browser connection is not task state

A closed tab, lost Wi-Fi connection or proxy restart can disconnect the view while an accepted request continues on the host. Reconnect to the same instance and conversation, then inspect the Run, pending approvals and Files before repeating a request.

Stopping Server, quitting Desktop, host shutdown or sleep is different: it affects the execution host. Previously written files are not rolled back by stopping a process. After restart, read the recorded outcome and current files; send only the remaining work.

Foreground operation

Keep the terminal that runs Server open. Closing it can stop the process; closing the browser does not have the same effect.
To stop deliberately, finish or stop active work in Rovai, press Ctrl-C in the Server terminal and wait for process exit.
Restart with the same executable version, account, data root and network flags. If you changed --public-origin, open its matching browser address.
Do not start a second process against the same data root. A lock refusal means an instance still owns it; find that process rather than deleting the lock file.

Background startup is configured by the OS

The installer creates no system service. Choose one process owner and one startup mechanism. A service manager’s environment is not your interactive shell: set a PATH that includes the Agent executable and preserve its home/authentication environment.

The following Linux example assumes a normal account named rovai, a default installation under /home/rovai, and a data root /home/rovai/.rovai-server. Create or choose the account deliberately and install/sign in as it first. Replace all paths consistently.

Restart=no avoids repeatedly relaunching a process whose startup failed. systemctl enable starts it at boot; it does not turn an interrupted request into a completed one. Keep the host’s network and Agent dependencies available.

Linux · /etc/systemd/system/rovai-server.service

[Unit]
Description=Rovai Server
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=rovai
WorkingDirectory=/home/rovai
Environment=HOME=/home/rovai
Environment=PATH=/home/rovai/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/rovai/.local/share/rovai-server/current/rovai-server --data-dir /home/rovai/.rovai-server --listen 127.0.0.1:8767
KillMode=control-group
TimeoutStopSec=90
Restart=no

[Install]
WantedBy=multi-user.target

Add the chosen connection flags

The template listens only on loopback. For Serve or Caddy, append the exact --public-origin https://… to ExecStart. For trusted LAN access, replace --listen and add --allow-insecure-lan as explained in that guide. Never launch a second foreground instance for the same root.

Save the unit only after replacing the example account and paths. The commands below check and start it, then enable boot startup. Logs remain in the data directory; journalctl also shows service-level failures.

Linux · start and inspect

sudo systemd-analyze verify /etc/systemd/system/rovai-server.service
sudo systemctl daemon-reload
sudo systemctl enable --now rovai-server
sudo systemctl status rovai-server --no-pager
sudo journalctl -u rovai-server -n 50 --no-pager

Linux · stop and disable boot startup

sudo systemctl stop rovai-server
sudo systemctl disable rovai-server

macOS · start after account login

Use a per-user LaunchAgent rather than assuming the installer installed a daemon. Download the example plist below and replace /Users/rovai everywhere with your account’s absolute home, including program, data, PATH and log paths.
Create the log directory before loading the plist. Save the customized file as ~/Library/LaunchAgents/dev.rovai.server.plist. Add --public-origin and its value as separate ProgramArguments entries if your connection requires them.
Stop the foreground instance first. Validate with plutil -lint, then load it with launchctl bootstrap gui/$(id -u) and the absolute plist path.
RunAtLoad starts this example after that user logs in, not before login. KeepAlive is false; it does not continuously restart failures. Stop/unload with launchctl bootout using the same domain and plist. Inspect the configured logs for launch errors.

macOS · load the customized agent

mkdir -p "$HOME/.rovai-server/logs"
plutil -lint "$HOME/Library/LaunchAgents/dev.rovai.server.plist"
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/dev.rovai.server.plist"

macOS · stop and unload

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/dev.rovai.server.plist"

Windows · a login startup task

Task Scheduler is an optional OS setup, not a Rovai installer feature. Create a task for the same ordinary account that installed and signed in to the Agent. Start with “Run only when user is logged on”; do not enable highest privileges by default.
Use an “At log on” trigger. Set Program to the absolute …\Programs\RovaiServer\current\rovai-server.exe path. Set arguments to --data-dir "C:\Users\rovai\.rovai-server" --listen 127.0.0.1:8767, replacing the account and adding the connection-specific flags.
Set Start in to that account’s home. Disable an arbitrary time limit for a continuously running task, choose “Do not start a new instance” for overlap, and review power conditions so the host does not silently stop the process on battery.
Run the task once and check its result and Server log. This setup begins after login; it is not a pre-login Windows service. To shut down cleanly, finish active work and use the running console’s Ctrl-C when available. Task Scheduler End may force termination; avoid treating it as a graceful stop or killing all same-name processes. Disable the task before maintenance and verify the specific process has exited before updating.

Editable startup examples

Logs and update procedure

Server log: <data-dir>/logs/server.log. --verbose adds diagnostic output to the terminal. Service manager logs explain launch/account/path failures; the Rovai log explains host behavior.
Before updating: Read the Server release notes, finish or stop active work, stop the exact Server process and its startup manager, then back up the data root and project files. Record version and launch flags.
Install the next version: Run that release’s installer with its explicit version. Preserve the existing data directory. On Windows, the installer does not stop the running executable for you. There is no rovai-server upgrade command in 0.4.1.
After updating: Restart the same instance and confirm version, login, teammate configuration, project path and an existing conversation. Desktop’s update mechanism does not update a separately installed Server.

Save and back up the right files

Program revisions are not a backup of workspace data. Stop the instance and copy its whole data directory, including its database, authentication state, managed skills and configuration. Protect the backup like a credential; it can contain private conversations and usable authentication material.

Back up project directories separately, including uncommitted files. Agent sign-in/configuration may live outside Rovai’s root, and source attachments can refer to external paths. A database-only copy does not preserve all of these.

For a rollback, retain a stopped pre-update data snapshot and the corresponding package. Restoring files in place at the same absolute data root is the conservative recovery path; do not promise that an older binary accepts a migrated database. Copying a data root to a different path or host is not a documented automatic migration.

Check a recovery plan on an isolated copy before relying on it. Do not run two hosts against one live data root or delete instance lock/identity files to bypass a refusal.

Troubleshoot by symptom

Address will not open: Check host awake → process running → listener/IP/port → LAN or tailnet routing → scoped firewall. For HTTPS, also check DNS, certificate and proxy status.
Page opens, login fails: Use the same instance’s Token. Check the exact external origin and proxy headers; a token from a different data root cannot authenticate this one.
Agent unavailable after login: Check the process account, service PATH, Agent installation, native sign-in and model access on the host. Installing an Agent on the phone will not help the host.
Service stops with terminal: You ran it in the foreground. Configure one OS startup method above; keep the same data root and inspect its logs.
Browser dropped during a request: Reopen the same conversation and inspect the existing Run before resending. A disconnected view does not tell you whether execution finished.
Bundled Skill resources unavailable: Observed before Agent launch in the published macOS arm64 0.4.0 package. Its required bundled resources are missing. Keep the data and install Server 0.4.1 from its release; see Install Server.
Matching WebUI is missing: Keep the full package together. On macOS 0.4.0 launch current/rovai-server directly, as shown in Install Server.
Symlink or root-lock refusal: Use a real absolute data directory; on macOS /tmp is a symlink, so use its canonical /private/tmp path for a disposable fixture. A root lock means another live process may own the instance.