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.

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 --machines --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.

--machines explicitly adds the owner-local machine catalog. Read-only access can inspect redacted profiles and run bounded status/session probes. Control access can add, rename, enable, disable, and remove profiles and advertises the additional machine scope. Without this flag, machine methods are absent.

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, pane-rename, prompt, agent-key, 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.

agent.keys is allowed only in control mode and only for a recognized agent pane. It uses the same key vocabulary as local luvus agent keys, including ctrl+z, printable Unicode, and composed sequences such as ["esc","[","Z"]. This vocabulary is wider than a terminal control stream’s send_key action. A bad batch queues no prefix; success means queued, not consumed. agent.send, raw pane input, agent launch/fork, and pane close remain forbidden.

Control also permits pane.rename with the existing pane and name parameters; read-only Access denies it. Rename retains the owner name validation and pane.renamed event. An empty name clears the pane alias.

Effective permissions

After pairing, uhp.capabilities retains the full owner methods catalog and adds an endpoint-specific projection (excerpt):

{"access":{"mode":"control","allowed_methods":["uhp.capabilities","pane.rename","agent.keys"],"limits":{"connections":16,"requests_per_minute":120}}}

The abbreviated list above is illustrative. The live list includes every compiled method advertised by the owner that the gateway’s authorization predicate permits. access.mode is read_only or control; access.allowed_methods is the effective RPC set for this gateway. access.limits.connections and requests_per_minute describe the gateway, not the owner server’s capacity. The owner endpoint does not add access.

Clients should intersect supported methods with access.allowed_methods and their own product action support. Keep unknown additive fields valid. Control includes pane.rename, agent.keys, and existing automation.* writes. This does not mean every allowed method should become a UI action. Standalone terminal input methods and uhp.token.* remain absent, even when a terminal control stream can accept input actions.

An older gateway may omit access; absence is not evidence of owner authority or permission to write. Re-discover after pairing/reconnect. This projection contains no owner socket or token, introduces no event, and does not replace normal authentication, expiry, rate, scope or target validation. Malformed capabilities, mismatched response IDs, missing/invalid method lists, an empty effective set, or projection beyond the frame limit return unavailable with the original request ID; valid owner error replies pass through.

Connection sequence

A provider launches luvus uhp access for the selected session.
It validates and consumes the single descriptor line.
It carries only the descriptor’s loopback byte stream through its secure transport.
A client connects through that provider and spends the one-use pairing code.
The client discovers capabilities, then opens one connection per ordinary request. Event and terminal streams remain open for their bounded lifetime.
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.