The place you observe and respond
Ormur renders the terminal, sessions, machine state and the controls a local tool can genuinely expose. Your phone sends an intentional command, answer, keypress or chosen file to a selected computer.
TECHNICAL GUIDE · CURRENT PRODUCT
How Ormur connects your machines and AI tools
Ormur is a mobile control layer for terminal-native work. It does not move your repository into an Ormur cloud, provide an AI model, or replace the tools on your computer. It gives the machines, terminal sessions and command-line harnesses you already use one private, machine-aware control surface.
Product status: Windows companion available · Android private beta · Linux preview · native iPhone and iPad app in App Store preparation.
01
The product model
Four things remain separate on purpose.
The path between paired devices
An embedded userspace WireGuard mesh establishes an encrypted route. The app can use a direct path or an encrypted relay path without exposing a public terminal port.
The owner of the local connection
The Ormur companion runs on your computer, hosts the terminal bridge and reports machine, workspace, route and session context to the paired app.
The process that actually does the work
PowerShell, bash, zsh, an AI CLI or your custom program still runs on the computer, under its own account, configuration, model access and provider limits.
The shortest accurate description: Ormur connects control; your computer executes; your chosen tool provides the intelligence.
02
From zero to a working session
The same system can be simple for a first project and explicit for an experienced operator.
Prepare the computer
Install the Ormur companion on a computer you own or are authorised to control. Your repository, shell, Git credentials, local services and AI CLI stay on that computer.
Pair the phone
Scan the computer's QR code or enter its short code. Confirm the machine identity before trusting it. Pairing creates credentials for that device, not one shared password for every device.
Select the target
Choose the computer and session you intend to control. When several computers are paired, machine context is kept visible so a command or file is not silently sent to the wrong host.
Use the terminal
Start a shell or an installed harness, watch live output, provide input and return later. The process remains a process on your computer; closing the phone view does not turn it into an Ormur-hosted job.
03
Architecture and trust boundaries
What each part can see and what it cannot.
YOUR PHONEOrmur appdisplay · input · device key
encrypted terminal channelYOUR COMPUTEROrmur companionPTY · files · local adapters
local process boundaryYOUR TOOLShell or AI CLIrepo · credentials · execution
Enough metadata to find a route
Pairing and reachability use limited records such as a device label, device public key, private mesh address, online or last-seen state and setup IP information. This plane helps paired devices find one another; it does not receive the keys required to read terminal content.
Terminal traffic remains between devices
Commands, keystrokes, terminal output and files you explicitly transfer travel inside the encrypted device link. A relay can carry encrypted packets but cannot turn them into readable terminal text.
Provider credentials stay with the provider's tool
If Claude Code, Codex, Gemini, Droid or another tool signs in, that relationship is between the local tool and its provider. Ormur does not need the provider password and does not resell its tokens.
A paired phone is powerful
A trusted device can operate a terminal on the selected computer. Protect the phone with operating-system security, review trusted devices and revoke a credential when a device is lost, replaced or no longer trusted.
04
What happens after you tap Send
An action travels through explicit, inspectable stages.
- Target resolutionThe app binds the action to the active device and session.
- Connection checkOrmur verifies whether the selected machine is reachable and which route is active.
- Encrypted deliveryThe input crosses the paired-device channel; a relay, if required, carries ciphertext.
- Local terminal writeThe companion writes the input to the PTY attached to that session.
- Tool executionThe shell or AI CLI interprets the input with its own permissions and configuration.
- Incremental renderTerminal output returns as live updates and is rendered to fit the current screen without changing the process's ownership.
Ormur does not reinterpret a shell command as an AI request. The receiving program decides what the text means.
05
Connection routes
Reachability can change; the content protection does not.
| Route | When it is used | What it means | Terminal content |
|---|---|---|---|
| Direct / mesh | A direct peer path can be established. | Packets travel directly between the paired endpoints through the private mesh. | End-to-end encrypted. |
| Encrypted relay | NAT or network policy prevents a usable direct path. | A relay forwards encrypted packets so the session can remain reachable. | Still end-to-end encrypted; relay cannot read it. |
| Same-network fallback | A supported local route is available on the same trusted network. | The app may use the local path rather than an internet route. | Remains local to that network and uses the app's authenticated connection rules. |
| Offline | No verified route reaches the companion. | The app reports the failure instead of labelling an unverified path as connected. | No action is delivered until connectivity returns. |
Fleet reports the route Ormur has actually verified. “Relay” describes packet transport, not readable cloud terminal storage.
06
Sessions, state and resume
Ormur separates what it observes from what a local tool guarantees.
A process on one machine
Each session belongs to a computer and its local terminal environment. Tabs are views onto those sessions, not separate cloud conversations.
Running, waiting, finished or offline
Ormur combines terminal activity and supported harness signals to present useful state. A generic shell may expose less structured state than a recognised harness.
Only when the local process supports it
App foreground/background transitions and temporary network loss can reconnect to an existing session. Computer reboot recovery depends on the companion, process manager and the CLI's own resume behaviour.
Important distinction: app reconnect, terminal reattach and AI-conversation resume are three different operations. Ormur never promises a provider resume capability that the installed CLI does not provide.
07
Harness and CLI compatibility
Terminal access is broad. Structured integration is capability-based.
| Tool class | Terminal control | Launch / identity | Model & thinking | Usage / state |
|---|---|---|---|---|
| PowerShell, bash, zsh, WSL, custom CLI | Core | Shell or custom command | Owned by the tool | Generic terminal signals |
| Claude Code, Codex, Gemini-family CLIs | Core | Recognised presets and local discovery | Shown or controlled only through documented/live capabilities | Structured data where the installed version exposes it |
| Hermes, Droid, OpenCode, OpenClaw, Cursor Agent | Core | Preset or detected local command | May be read-only, tool-owned or unavailable | Varies by adapter and installed version |
| Your own harness | Core | Saved custom command | No invented universal control | Generic unless an adapter exposes more |
What “works in Ormur” means
If a program is interactive in a supported local terminal, Ormur can present and control that terminal. This is the broad compatibility layer.
What it does not automatically mean
It does not mean every program exposes a safe model switch, thinking level, quota API, completion event or resumable conversation. Ormur only presents those controls when it has a reliable source of truth.
Tool names identify compatibility targets, not partnerships. Their availability and account terms are controlled by their respective providers.
08
Files and multiple computers
A transfer is explicit about source, destination and consent.
Select, target, send
You choose a file on the phone and the destination computer. With several machines paired, the selected machine is part of the action rather than an invisible global default.
Offer, review, accept
A connected computer can offer a file. The phone presents the source machine and requires an explicit acceptance before saving it.
Inside the paired-device channel
Transferred file content follows the encrypted device path. It is not uploaded into an Ormur project drive or stored as a team attachment.
Ormur is not a cloud file-sync service. It transfers files you deliberately choose between paired endpoints.
09
Notifications and background behaviour
Useful when supported, optional by design.
Return to the session that caused the event
Supported local integrations can surface that a task needs a decision or appears complete. A notification should summarise the event and link back to the relevant machine and session rather than duplicate an entire terminal line.
Permissions and operating-system limits still apply
Delivery depends on notification permission, background policy, network reachability and platform power management. Denying notifications does not block normal typed terminal access.
Android release default: the optional external wake relay is off unless a reviewed relay is configured and the user opts in. A wake signal contains no terminal body; opening the app still performs the authenticated reconnect.
10
Security controls
Concrete properties instead of absolute promises.
Device-specific pairing
Each trusted device receives its own credential. A device can be revoked without sharing or rotating a universal terminal password.
No public terminal port
Normal setup uses outbound mesh connectivity; it does not require exposing the terminal service directly to the public internet.
Encrypted relay fallback
A relay can improve reachability but does not receive the endpoint keys needed to decrypt terminal traffic.
Local provider credentials
AI-provider authentication stays in the provider's own CLI or local configuration on your machine.
Revocation and deletion
You can remove a trusted device and request deletion of the limited coordination metadata associated with it.
Honest failure state
When a route cannot be verified, Ormur reports offline or reconnecting rather than claiming a connection that has not been established.
11
Data map
Where each category belongs.
| Data | Primary location | Why it exists | Readable by Ormur coordination services? |
|---|---|---|---|
| Repository and local files | Your computer | Your own development environment | No, unless you explicitly send a selected file through a support request. |
| Terminal input and output | Your paired devices / computer session | Interactive terminal control | No; encrypted between endpoints. |
| AI-provider credentials | Provider CLI / computer | Authenticate the tool you chose | No. |
| Device public key, label, mesh address | Coordination service and paired devices | Pairing, authentication and reachability | Yes, as limited metadata. |
| Online and last-seen state | Coordination service | Explain whether a paired device can be reached | Yes, as limited metadata. |
| Diagnostics | Device and limited operational services | Security, reliability and troubleshooting | Limited records may be processed; designed not to contain terminal bodies. |
| Voice input | Operating-system speech service when used | Turn optional dictation into text | Ormur does not retain raw microphone audio. |
The complete legal disclosure, service-provider details and user rights are in the Privacy Policy. This guide explains the product architecture and does not replace that policy.
12
Failure and recovery model
Different failures require different recovery paths.
| What changed | Expected behaviour | What you may need to do |
|---|---|---|
| Wi‑Fi ↔ cellular | The current route may drop and be re-established through another verified path. | Allow a short reconnect; open Fleet if the machine remains unreachable. |
| App backgrounded or restarted | The app reloads paired-device and session context, then reconnects. | Unlock the device and reopen the relevant session if the OS suspended connectivity. |
| Computer sleeps or loses network | The machine becomes offline; its local process state depends on the operating system. | Wake or reconnect the computer. Ormur cannot execute on a powered-off machine. |
| Computer reboots | The companion can start again when installed for background startup. | AI conversation/process resume depends on that CLI and how the original session was hosted. |
| Credential revoked | The revoked device can no longer reconnect with that credential. | Pair again only if the device should be trusted again. |
| Harness changed version | Generic terminal control can continue while structured controls may be hidden if no longer reliable. | Use the tool's native picker/configuration until its adapter is verified. |
13
Current boundaries and roadmap
What ships now is separated from what Ormur may become.
Private control across your own devices
- Terminal access to paired computers
- Machine-aware sessions and Fleet state
- Explicit selected-file transfer
- Capability-based harness controls
- Direct, mesh or encrypted relay reachability
- Revocable device credentials
Shared work across people
- Team workspaces and shared projects
- Roles and per-person permissions
- Human-to-human handoff and audit
- Organisation policy and managed membership
- Shared project context across separate owners
Why the boundary matters: connecting devices you control and authorising other people are different security models. Ormur will not describe team collaboration as available until roles, consent, revocation and audit are designed and tested for that use.
READY TO TRY THE CURRENT PRODUCT?
Keep the environment. Add a better way to reach it.
Start with the Windows companion and one computer. Add more machines when you need them; the control model stays the same.