Remote access and transport providers

UHP Access is the transport-neutral bridge for remote or embedded clients. It lets a provider carry normal UHP 1.0 frames without building any transport into Luvus core.

Looking for the interactive TUI?

Use luvus --remote devbox when a person wants to open the full Luvus interface over SSH. The Remote Sessions guide covers installation, SSH configuration, named sessions, phones, and troubleshooting. UHP Access is for an independent application or transport provider.

For one request from a shell script, use the simpler SSH proxy instead of starting an access endpoint:

printf '%s\n' '{"id":"snapshot","method":"session.snapshot","params":{}}' \
  | ssh devbox luvus uhp proxy

Start an access endpoint

luvus uhp access
luvus uhp access --ttl 7200
luvus uhp access --control --ttl 3600
luvus uhp access --no-expiry

The command emits one compact JSON descriptor and stays in the foreground. It binds an ephemeral IPv4 loopback port and creates a one-use pairing code. Read-only and control authority both default to 24 hours. --control remains a limited control surface, and --ttl <seconds> overrides either lifetime with a value from 1 through 86400 seconds. Pairing lasts at most five minutes and is shortened automatically when the configured authority expires sooner. --no-expiry makes access process-bound instead: it remains valid until the foreground command exits or is interrupted.

The descriptor includes:

• UHP and access-contract versions;
• 127.0.0.1, the ephemeral TCP port, and NDJSON framing;
• the one-use pairing code and expiry;
• the exact delegated mode, scopes, and expiry.

It never contains the delegated token or the owner-only Luvus socket or named pipe. Validate it against the access descriptor schema emitted by luvus uhp schema.

Authority and expiry

Command	Mode	Scopes	Pairing	Authority
luvus uhp access	Read-only	read	One use, at most 5 minutes	24 hours by default; --ttl accepts 1 second to 24 hours
luvus uhp access --control	Bounded control	read, workspace, agent, terminal, orchestration	One use, at most 5 minutes	24 hours by default; --ttl accepts 1 second to 24 hours
Either mode with --no-expiry	Same scopes as selected mode	Unchanged	One use, at most 5 minutes	Until the foreground access command closes

Finite descriptors expose authority.expires_at as a Unix timestamp. Process-bound descriptors expose authority.expires_on_close:true. Luvus keeps its upstream server tokens bounded and rotates them internally, so --no-expiry does not create a permanent token in the server.

Control mode does not expose every local mutation. The gateway allows the advertised read surface plus selected focus, prompt, terminal-control, and automation methods. An automation created remotely is durable and can run after the pairing token or access command expires; disable or delete it explicitly when that is not intended. Discover the exact live method set after pairing rather than treating a scope name as permission to call every method in that namespace.

Connection sequence

1. A provider launches luvus uhp access for the selected session.
2. It validates and consumes the single descriptor line.
3. It carries only the descriptor’s loopback byte stream through its secure transport.
4. A client connects through that provider and spends the one-use pairing code.
5. The client discovers capabilities, then opens one connection per ordinary request. Event and terminal streams remain open for their bounded lifetime.
6. Stopping the foreground command closes the gateway and revokes its token.

Provider responsibilities

A provider launches luvus uhp access, reads the descriptor line, and forwards only its loopback endpoint through an authenticated, confidential, integrity-protected ordered byte stream. Preserve half-close, EOF, and backpressure. Do not parse or rewrite UHP, persist credentials, publish the loopback listener, or silently fall back to plaintext.

The provider and Luvus lifecycles stay separate. If the provider fails, Luvus continues normally. If the access command exits or reaches its deadline, its gateway closes and token is revoked while panes and agents stay alive. When the command is not running, this feature has no listener, thread, transport process, timer, or network activity.

Client responsibilities

Connect to the forwarded port and send this LF-terminated frame first:

{"type":"pair","code":"ABCD-EFGH-JKLM"}

The paired response returns the client token and scopes, plus either expires_at or expires_on_close:true. Open a new stream for each ordinary UHP request, include the token in auth, and half-close the request side after its single frame:

{"id":"caps","method":"uhp.capabilities","params":{},"auth":"<ephemeral-token>"}

Keep the connection open for events.subscribe, terminal.backend.observe, or terminal.backend.control. Discover live capabilities after pairing; do not assume methods from a Luvus release number.

Provider implementations

Luvus does not bundle or select a remote transport. A provider may use SSH, a private overlay network, an authenticated tunnel, or another secure ordered byte stream. It only needs to launch the access command, consume its descriptor, and forward the advertised loopback endpoint without rewriting UHP frames.

The provider owns transport authentication and reachability. Luvus owns UHP framing, pairing, delegated authority, request validation, and server-state mutation. A client should therefore remain portable across providers: only the way it obtains the forwarded byte stream changes.

Continue with Practical examples and the Method reference. Use Schemas and conformance before shipping a client or provider.