Logonomic Companion

Use Logonomic Companion on Android to check your desktop's sessions, work in their terminals, launch configured work, inspect repositories, and follow usage and quota. Commands run on the desktop, which must stay awake, running, and reachable.

Contents

• What to prepare
• Pair over the local network
• Pair through Relay
• Switch between authorized Local and Relay
• Navigate the phone application
• Sessions on the phone
• Work in a live terminal
• Repositories and launching work
• Usage and Quota
• Notifications and background connection
• Paired devices, lost phones, and forgetting
• Disconnect, reconnect, and last-known information
• Troubleshooting by symptom
• Where to do desktop-only work

What to prepare

Companion is included with both retail desktop editions, Logonomic and Logonomic Pro. Logonomic Free excludes Companion. Connecting directly over a shared network is included at no additional charge.

Check Release status for Companion availability before pairing. Contact Logonomic support if you need help obtaining your package. Set up repositories, launchers, and provider accounts on the desktop first.

Choose a connection method:

Pair only a phone you trust. It can read terminal output and send commands with the same consequences as typing at the desktop, as well as launch and close sessions. Keep active pairing QR codes private. Companion uses the desktop's accounts and feature availability; Relay sign-in does not select a provider account for your work.

Pair over the local network

1. Connect both devices to the same private network.
2. On the phone, select ⋮ → Pair desktop and allow camera access.
3. On the desktop, select the title-bar QR button to open Pair companion, then choose Local.
4. If several desktop networks are listed, use the scanner's network advice to select the one shared with the phone.
5. Let the desktop check its firewall. If it says Not configured, follow the popup's instructions, then select Retry / choose network. See the firewall steps below if needed.
6. Scan the desktop QR code with Companion and keep both apps open until the phone connects and loads your sessions.

A Local code lasts five minutes. Scan a fresh code if it expires. Once pairing succeeds, it survives normal app restarts and you can close the popup. Closing the desktop popup or changing its connection method cancels the unfinished invitation. A credential already saved on the phone may still need confirmation; see Pairing progress and recovery.

The phone verifies the desktop's secure identity from the QR code. If verification fails, scan a fresh code directly from the intended desktop. You should not need to bypass certificate verification.

Local pairing uses private IPv4 networks (10.x.x.x, 172.16.x.x through 172.31.x.x, or 192.168.x.x). Guest Wi-Fi, network isolation, and VPN routing can prevent access even when both devices have internet. Use Relay when a direct connection is unsuitable.

Pair through Relay

Relay access is separate from the desktop licence. It is prepaid for twelve months and does not renew automatically. Buying and using it requires a Logonomic or Logonomic Pro licence on the same Varinomics Account; a perpetual licence remains eligible after its update coverage expires. See Relay access and terms.

1. On the desktop, open Pair companion → Relay.
2. If prompted, select Sign in with browser, complete Varinomics Account sign-in, and return to Logonomic.
3. Check the Account and Relay status; select Check availability if offered.
4. Select Pair phone or, after a failed invitation, Request a new code.
5. On the phone, select ⋮ → Pair desktop and scan the Relay QR code.
6. Keep both apps open until the header shows Connected (Relay).

The code shows its expiry time. Follow the desktop's instruction to request a new one if it expires. Reconnect retries an existing connection; you do not need another code for an ordinary disconnection.

The desktop still runs your terminals and stores repositories and provider credentials. Check the Relay pane if the service or Account is unavailable; use Local on a shared network when appropriate.

Pair Local and Relay separately if you want to use both. Each QR code must come from the same desktop installation. Pairing one method does not authorize the other. Once both are confirmed, you can switch without rescanning.

What Relay can read and retain

The paired desktop and phone encrypt terminal and session data end to end. Relay forwards the encrypted connection through Cloudflare without receiving the keys needed to decrypt that content. Keep pairing QR codes private: they contain a secret used to authorize pairing.

Relay forwards a live connection. It does not provide a cloud transcript archive or queue terminal input for an offline desktop or phone.

Connection records are separate from terminal content. The services retain routing, access authorization, expiry and revocation metadata, including account-associated records. These records can outlast their expiry or revocation. A customer-service retention period has not yet been established.

Switch between authorized Local and Relay

In the phone's root ⋮ menu, Connection: Local or Connection: Relay names the selected method. Choose Local or Relay to switch to a confirmed authorization. The choice is saved; it does not start another pairing ceremony. Each method retains its own permissions: Local input access does not grant input through a read-only Relay authorization.

Companion uses the selected method without automatic fallback. A network or Account failure leaves that method Offline; choose the other confirmed method explicitly if you want to use it. Switching retains uncertain terminal input without automatically resending it through another credential. Inspect the original terminal and resolve pending input. An interrupted session action can have an unknown outcome; inspect the desktop before repeating it.

To finish an interrupted pairing, choose Finish Local pairing or Finish Relay pairing. See Pairing progress and recovery.

To drop an unfinished attempt, leave the pairing view with Cancel, then choose ⋮ → Abandon pending Local pairing or Abandon pending Relay pairing. This removes only the observed pending phone credential; confirmed Local and Relay authorizations remain. If that pairing has already been confirmed or replaced, Companion retains the current record and explains why it could not abandon the old attempt. Abandoning a phone record does not revoke a credential on the desktop. Choose an existing confirmed connection explicitly to use it.

Navigate the phone application

Use the bottom bar for Sessions, Repositories, and Usage and Quota. Switching sections retains an open detail page so you can return to it. Use the back arrow or Android Back to leave that page. Dismiss the terminal keyboard to reach header controls it has hidden.

The ⋮ connection menu is on a section overview. The header shows whether you are connected, with the desktop address for Local or Relay for Relay. Android Back first dismisses an active selection, keyboard, or pairing view; at the top level it backgrounds Companion without closing desktop sessions.

Sessions on the phone

Open Sessions to find live terminals and remembered conversations. Collapse remembered groups to focus on running work; these choices are saved on the phone. Session cards identify the repository, launcher, account, and activity. Read only marks a session with restricted interaction.

Find and open a session

Use Search sessions to filter by the titles, summaries, repository, account, and other searchable information supplied by the desktop. Search ignores case. The resumable group shows 50 entries per page by default; use the page controls and page-size selector for more history. Search applies before paging. Clear the query to restore the full list.

Tap a live session to open its terminal. A remembered or structured session may instead show its recorded conversation, including user and agent messages and tool activity. To send input, open an available live terminal; the recorded log has no separate mobile prompt composer.

Activity and attention indicators help you find work that needs a response. No session update · … gives the age of the latest activity, rather than confirming that a program stopped. Disconnected statuses are marked Last known. See Sessions and coordination for history and resumption rules.

Close, remember, forget, remove, and resume

Open a session's ⋮ menu, or hold a card to select several sessions. Tap more cards in the same group to change the selection. Live, resumable, and non-resumable groups are selected separately. A batch can include up to 128 targets; complete one batch before starting another.

For selected live rows, Close opens the remember/forget choices. Read the reason beneath any unavailable action. Choose a conversation appears when the session offers more than one conversation target.

Close and resume need a ready connection. You can request a remembered entry's removal while offline; it stays pending until the desktop reconnects and checks that the entry is still eligible. Keep Companion running until that result arrives, or use Revoke removal while offered. Pending removals are not saved as a durable offline job list.

After a successful resume, Companion opens the live terminal or asks you to find it in Sessions. Leaving the progress view does not cancel a request already sent. If an action's outcome is unknown, check it before retrying.

Work in a live terminal

The phone and desktop share the same running terminal. Commands entered on either device affect that program, and resizing can change its layout on both.

Type, send terminal keys, and use a hardware keyboard

Tap a writable terminal to open the keyboard. Enter submits text exactly as it would at the desktop; there is no separate Send button.

In portrait orientation, Companion normally uses its terminal keyboard. Swipe across the space bar to cycle enabled language layouts; a US layout is also available. To use Android's usual keyboard, enable Use system keyboard in the session menu. This preference applies across sessions and is saved. Landscape uses the system keyboard.

The terminal-key strip provides keys missing from the system keyboard:

A hardware keyboard supports ordinary typing, navigation, function keys, and supported Shift/Control combinations. Unavailable combinations are reported.

Select, copy, and paste

Long-press terminal text, adjust the selection handles, and choose Android's Copy action. When a selection finishes, the phone makes one request to acquire its text, within the 24 KiB UTF-8 companion copy limit. Acquisition does not change the phone's clipboard or clear the selection.

Once acquired, Copy selection in the Session view and Android's Copy action use the retained text locally. Ordinary output and a disconnect do not erase that text. A new selection, deselection, another terminal surface, or changed authorization retires it. Tap outside or use Back to dismiss selection.

If acquisition is refused or loses its connection, the phone does not replay it automatically. Text that was never acquired cannot be copied offline; select it again after the view settles.

Use the touch paste action or a hardware-keyboard paste shortcut to send the phone's clipboard. Long-pressing terminal padding can open Paste without selecting text. Check the destination prompt first: pasted newlines can execute commands. A single paste is limited to 24 KiB of UTF-8 text; split larger text deliberately if appropriate for the receiving program.

Scroll and follow output

Drag vertically through scrollback. Tap Newest to return to current output; Waiting… means that move is still being confirmed. Full-screen terminal programs have their own scrolling behavior and do not offer Newest.

Terminal size and fitting

Opening a supported terminal requests a grid fitted to the phone. To change who controls its size, use the fit-to-screen header button:

• Use desktop for terminal sizing returns control to the desktop.
• Use this companion for terminal sizing fits the terminal to this phone.

Only one view controls sizing at a time; another phone or the desktop can take over. With phone sizing active, changing text size changes the terminal's rows and columns. With desktop sizing active, the phone may need horizontal panning to show a wide terminal. Drag horizontally to see content beyond the view.

Opening the keyboard makes room to type without resizing the running terminal to the keyboard's temporary overlap. Terminal view resizing means the new dimensions are still arriving.

Appearance

Open the session menu's gear action, Appearance, to choose Color scheme and Font. Pinch the terminal to change text size from 6–72 pixels. These choices are saved for all terminals on the phone and leave the desktop's font and colors unchanged. Phone sizing can still change the shared grid.

Repositories and launching work

Open Repositories, expand a repository/worktree group, and select an entry. The detail page brings together its sessions, desktop path, launchers, branch status, line-count history, workflows, and recent commits.

Launch a session from the phone

1. Select the intended repository or worktree.
2. Check its desktop path and branch.
3. Under LAUNCHERS, tap the launcher to run.
4. Wait for the desktop to start it; Companion then opens the session.

The selected repository becomes the working directory, using the launcher's desktop command and account. Configure or repair missing launchers on the desktop. SESSIONS opens existing work and offers the same selection and session actions as the Sessions overview.

Repository status and commits

BRANCH shows modified and untracked counts, ahead/behind counts, and upstream state. Clean means both file counts are known to be zero; ignored files are excluded. Compact badges use M for modified tracked paths and U for untracked paths. An unavailable count is unknown, not zero. See Working-tree status for details.

Up to date reflects the desktop's known upstream state, so fetch on the desktop before relying on it for recent remote changes. No upstream means there is no comparison target. Off the default branch identifies branch position.

Expand Branches to inspect local (L) and remote (R) presence. The list is informational and does not perform checkout. Under COMMITS, tap a commit for its full message. The mobile list shows up to the newest 500 published commits; use desktop Git history for broader exploration.

Under LINES OVER TIME, drag to pan and pinch to change the time scale. An empty history means no measurements are available. Sections load separately, so an error in workflows or history can leave sessions and other details usable.

Read workflow history

Workflow history uses the checkout's Hosting remote, chosen on the desktop in Repositories. To read another hosted project, change that desktop choice; see Connect GitHub or GitLab. A missing remote or access failure appears as an error, rather than No runs.

The run's ref and commit identify the displayed result; they may differ from your checkout. Updated describes the run. Last checked, when available, is the last successful history check for that workflow.

A failed check can leave the previous result and check time visible alongside an error. Read Last checked before relying on a passing result; another workflow may have been checked more recently. No runs means the last successful check found none. Not checked or Run history unavailable means no history is available for that row.

Run a workflow

Read Reference · … on the workflow card, then select Run. The action uses that displayed reference, which can differ from the displayed run's ref; mobile does not offer a branch or workflow-input editor. Follow the reported run status for the result.

Run disabled · … explains why dispatch is unavailable. GitLab pipeline history may be shown, but GitLab dispatch is unavailable. See Repositories and CI for the desktop's supported operations.

Usage and Quota

Open Usage and Quota for Last 14 days and provider quota windows. Use the plotting control beside a source to include it in the chart and combined total. Drag the chart to pan and pinch to zoom. Some sources report token history without quota; the reporting count identifies those with quota.

The measurement control separates Dated activity · …, available Provider dates · … calendars, and Accounting history · completion dates. Dated activity shows proved token increments in the named desktop timezone, even when the phone uses another timezone. Provider dates keep their recorded calendar meaning. Accounting history groups accepted totals by completion date; those rows can contain cumulative conversations and are not daily token increments.

Quota bars show remaining percentages and reset information when available. Missing quota is neither zero remaining nor unlimited allowance. A combined total may be unavailable even when individual sources have useful data. Configure accounts and investigate provider data on the desktop; see Usage, notes, and insights.

The explanation beside the combined plot separates accounting history, dated instants, provider dates and amounts without daily evidence. These coverage amounts describe the accepted history as a whole; an undated remainder is not assigned to the fourteen-day period. Missing or conflicting evidence can leave the daily plot unavailable without removing retained accounting or quota. An older desktop that cannot supply dated activity also leaves that plot unavailable; select the labelled accounting history to inspect its records. Read Usage date reference before comparing days.

Notifications and background connection

From a section overview, open ⋮ → Notifications and enable Play sound when the agent needs attention. It is off by default. Set Completion minimum (minutes) to a whole number from 0–1440, initially 10. The choice is saved on this Companion installation. 0 alerts for every completed observed work episode.

Questions alert immediately when received and enabled. Completion alerts count only observed working time, excluding waits, and accumulate that time within the same work episode. The minimum sets how much work qualifies, rather than delaying a question alert.

In one session's menu, the same control cycles through Use global setting (on/off), On for this session, and Off for this session. A per-session choice overrides the global sound setting and is saved. All sessions use the same global completion minimum.

On Android, select Enable Android notifications if system permission is missing, and Allow background connection if battery optimization can pause Companion while the phone sleeps. The ongoing connection notification can offer the latter action too.

Alerts titled Agent needs input or Agent finished working open Companion. Use Sessions to reach the named session if needed. Keep the desktop awake and the connection available for timely alerts. Each eligible completion alerts once. When you first connect, earlier alerts are skipped. A brief reconnect can catch up retained alerts without repeating those already delivered. If notifications are unavailable, ordinary Companion sessions can still be used.

Paired devices, lost phones, and forgetting

Open Paired devices from the desktop's phone/device title-bar control. The list includes authorized phones that are offline, so you can revoke a lost phone without connecting it or another phone.

• To revoke one pairing, select Remove device beside it. Use its Pairing ID and pairing time to distinguish similar names.
• To revoke every paired phone, select Revoke all, then confirm Revoke all paired devices?. This includes offline phones and both Local and Relay pairings. Cancel or closing the confirmation leaves their access unchanged.

Successful removal revokes that particular credential; desktop terminals keep running. The removed method needs pairing again to regain access. An independently authorized other method remains usable through an explicit choice on the phone. To retire both methods, revoke both credentials or use Revoke all. The Relay pane also offers Revoke for connected phones. Simply disconnecting a phone does not revoke its saved credential.

If Logonomic reports Revoked N of M devices, successful removals remain in effect. The remaining devices are still listed: resolve the reported problem and retry Revoke all to remove their access too.

On the phone, hold ⋮ → Forget this desktop for one second until progress completes. It removes both Local and Relay active/pending phone records and retained terminal input, regardless of the selected method. Desktop work and history remain. A partial deletion stays Offline; resolve the reported problem and use Retry Forget.

After deleting the phone records, Forget attempts to revoke retained Relay Account grants. This is best effort, with no durable retry queue or offline success guarantee. Phone Forget does not implicitly revoke a remaining Local desktop credential. For a lost or untrusted phone, revoke both methods on the desktop rather than relying on Forget on that phone.

Relay Sign out stops Relay connections and clears the desktop's Varinomics Account sign-in, while preserving pairings. Sign back in to restore eligible Relay access. Removed devices cannot connect here. Account revocation is pending means local removal has succeeded while service-side removal still needs to finish. That status remains available even when the paired-device list is empty.

Pairings use protected phone storage. Clearing Android app data or reinstalling with data removal can require pairing again. Ordinary Android app backup does not transfer that trusted pairing to another device.

Disconnect, reconnect, and last-known information

Companion normally reconnects when the desktop becomes available. Use Reconnect when offered, or Search again for the paired desktop for Local. A normal change of the desktop's LAN address does not require pairing again.

During a disconnect, terminal output is muted and statuses become Last known. Repositories and usage may also remain visible with older data. Wait for a live connection before acting on that information. The phone's retained views are not a backup of desktop history.

The desktop supports up to 32 active Companion connections. Saved offline pairings do not occupy those connections.

If a connection failed during a command or session action, inspect the result before repeating it. The desktop may have accepted the operation before the phone lost confirmation.

Troubleshooting by symptom

Pairing and network problems

Pairing limits

The desktop supports up to 64 pairing credentials across Local and Relay. Authorizing one phone through both methods uses two places. An unfinished pairing occupies one place; confirmation keeps it, while expiry or removal releases it. Replacing an existing Relay credential reuses its place.

Relay also has a 32 saved-route limit, including unfinished routes and locally revoked routes awaiting Account cleanup. These limits count saved authorization records. For pending cleanup, follow the Relay pane's revocation status; a revoked route occupies its place until cleanup succeeds.

Windows Firewall

For Not configured, follow the popup's instruction to allow the installed Logonomic application for the named Windows network profile, then select Retry / choose network. Connection and discovery both need incoming access. An explicit block or managed policy may require your administrator's help; do not disable the entire firewall to pair.

The Windows Private/Public network category is separate from the address range. Follow the popup's named profile and your network's policy. Could not verify includes details such as missing authorization or a timeout. Inactive only describes the local Windows firewall; other network restrictions may remain.

Linux firewall

Logonomic checks firewalld for the selected interface. If rules are missing:

1. Select Copy runtime command and run it in a desktop terminal, granting the authorization requested by sudo.
2. Select Copy permanent command and run that command too.
3. Return to Pair companion and select Retry / choose network.

The first command permits access now; the second keeps it across firewall restarts. Use the generated commands for the selected zone and ports. Not installed or Inactive refers to firewalld; other firewalls may still apply. For Could not verify, follow the accompanying detail.

Understand pairing progress and recovery

Keep both apps open while Pairing desktop finishes. If it stops after saving a credential, choose Retry to recover that pairing and finish confirmation. Repeatedly scanning new codes can interrupt this recovery.

Finish Local pairing or Finish Relay pairing resumes the saved pending credential, including after restart. The other authorization stays saved; access starts after the desktop confirms. Other connection choices are disabled until confirmation finishes.

If the desktop rejects pending Relay pairing, Relay stays selected and Offline. Local authorization and input remain saved. Choose Local explicitly to reconnect through it.

Cancel leaves the pairing view but does not necessarily delete a credential already saved. For a saved unfinished attempt, use Cancel, then the root menu's Abandon pending Local pairing or Abandon pending Relay pairing to retain confirmed connections. Forget this desktop removes all Local and Relay active and pending records stored on this phone, together with retained terminal input. See Forgetting a desktop for desktop revocation and partial-deletion behavior. If the desktop reports that a device replacement awaits completion, finish the phone confirmation and any indicated Relay sign-in step before starting again.

An action or terminal input is unconfirmed

The action result is unknown means a request may already have happened. Inspect the desktop or refreshed session list before repeating it.

For End, Close and remember, Close and forget, Remove, and Resume, open Sessions → Recorded actions. Each record names the original sessions. Check status, when enabled, reads that original action's status; it does not send the action again. An action the desktop still reports pending continues to block further changes. A confirmed result or rejection is shown when the desktop can provide it; some recorded outcomes can remain unknown.

Acknowledge, when enabled, stops locally waiting for that action while keeping its unknown outcome visible, including when its session disappears. It does not prove completion or cancellation. Further changes require fresh, consistent desktop authority and an eligible current session. A desktop restart or changed authorization can make the original status unavailable. Acknowledging a removal does not cancel its Pending removals record or make it eligible to send again; use that record's separate cancellation control to stop tracking it. Acknowledge does not release unconfirmed terminal input or other action guards.

For other unconfirmed requests, such as a launch, or when Companion still asks you to restart, check the actual desktop result first, then fully stop and reopen the phone app.

For terminal input, use Review pending terminal input (the hourglass control) when it appears in the header. Pending terminal input names the original session and shows the retained text and keys. Switching sessions does not send that input to another terminal.

• Queued input can be sent automatically when the connection and original terminal are ready; it does not need Resume.
• Preserved input may already have reached the terminal. Inspect that terminal's output before choosing Resume input: resuming can send the input again. Resume requires a live connection and the original session to be selected; the dialog explains when it is unavailable.
• Discard input, when enabled, clears the retained input without closing the desktop terminal. It cannot undo anything already delivered.

If the original session is no longer available, keep the preview for reference or discard it. Closing the dialog keeps the input available for review.

Terminal and session problems

Some distributions offer ⋮ → Copy connection diagnostics. When reporting a problem, include those diagnostics, the visible error, Local or Relay, desktop edition, both app versions, and the failed step. Omit active QR codes and credentials.

Where to do desktop-only work

Use the desktop to edit launchers, configure accounts and integrations, add repositories, manage Git/file/diff work, edit notes, set up orchestration, and manage edition or activation. See Repositories and CI, Terminals, and Settings and reference for those procedures.