---
status: reviewed
last_updated: 2026-10-29
---

# Client (client direction): driving vanilla SSH servers as family ops

## The door framing

The client direction is a door *to vanilla servers*: family in,
vanilla out. The motivating consumer is the **reverse-runner** shape
(`docs/research/reverse-runner.md`, alkminer extraction): a family hub
dials vanilla `sshd` on rented/near-ephemeral hosts; the remote boxes
expose plain sshd and hold nothing of ours; every op the hub drives
maps family-side onto the same protocols the server direction serves.
The asymmetry is honest (vision principle 2): the server direction
*serves* family seam entries; the client direction *consumes* family
types. Same features gate both (ADR-003 symmetry rule).

**Type symmetry at the seam is the client contract:** a family app
drives alkssh in family-protocol types; alkssh translates to vanilla
wire ops (russh client surface, ADR-002). No vanilla-concept leaks
up into the family surface.

## The dial surface

Every dial needs: address, **key source** (ADR-005, a vault-backed
blob: decrypt-at-dial, fail-closed on locked/absent, never env vars,
never plaintext at rest), **host-key policy** (the OQ-05 resolution,
assembly-provided; crate default fail-closed reject-unknown, hard
decline on mismatch; the OpenSSH "add to known_hosts?" moment is an
assembly policy, e.g. learn-and-record / prompt / provider-metadata
match, and the crate is policy-blind), and the bounded-resource config
(`keepalive_interval`/`keepalive_max`, a 15 s / 3 default posture per
the reverse-runner evidence; `inactivity_timeout`; window/packet
knobs per `overview.md`).

The identity the dial authenticates *as* is a registered fingerprint
at the remote end: for family-run peers (alkforge runner) that's the
alkcall `IdentityProvider`; for vanilla fleets it's whatever the
vanilla server's `authorized_keys` holds. Either way the *key* is
ours from the vault and the host's key is checked by the policy.

## Op rows (family op → vanilla translation)

| Family-facing op | Family protocol/types | Vanilla-wire translation | Feature |
|---|---|---|---|
| run a command / own a shell on the runner | alktty session types (pipe vs PTY; exit semantics) | `channel_open_session` + `exec`/pty-req/shell-req; data pump; drain `wait()` per the POC-3 §D.3 mechanics (`Channel::exec()`, not `request_exec`; Success/Failure arrive on the channel queue, not as `Err` from the request call) | `session` |
| open a tunnel target | alktunnels `TunnelSession`/target types | `channel_open_direct_tcpip` per connection; the typed open resolves to `Err(ChannelOpenFailure)` on server reject (POC-1 §6); no `wait()` before `into_stream` | `tunnel` |
| the `-D` behavior (local SOCKS door) | alksocks' local door **composed at the assembly**, fed a `DialFn` backed by row 2's open | the wire sees only `direct-tcpip`; alkssh *does not depend on alksocks* on this path (ADR-003 §1a) | `tunnel` |
| listen + ingest (`-R` leg) | alktunnels consumer/`ForwardedHandler` shape | `tcpip_forward(address, port) -> bound` global request (no mpsc sink param) + **accept the server-initiated `forwarded-tcpip` opens** via `server_channel_open_forwarded_tcpip`, routing each to the family handler | `tunnel` |
| upstream git consumption | alkgit client/service types | the same exec grammar the server side parses (`git-(upload,receive)-pack '/repo'` exec), pointed at an upstream `sshd` | `git` |
| artifact/deploy transfer | alkfs client half (future) | `subsystem "sftp"` + the alkfs protocol | `sftp` (decline placeholder, OQ-13 resolved) |

## The acceptor: fail-closed client-side

russh's client handler receives server-initiated channel opens; its
default posture for a forwarded open is **accept-and-drop**, a
half-capability, which the family forbids (ADR-003 symmetry +
`reverse-runner.md` lesson 1). The client contract:

- Server-initiated opens are served only when the assembly registered
  an acceptor **for that type and under its feature** (the real case
  is `forwarded-tcpip` under `tunnel`, the `-R` data path).
- Unregistered/unfeatured accepted opens are **declined cleanly**,
  never silently dropped after accept.
- Acceptor handlers may be installed across a live connection's
  lifetime (the alkminer `install_forward_sink` late-install dynamic:
  consumers turn capabilities on/off per connection; the shape is an
  assembly-mutable acceptor registry).

> **The landed acceptor shape (`w4-reverse-listen`, recorded at
> landing):** the registry is **per-type fixed slots**, exactly the
> two `-R` data-leg types the client direction can serve
> (`forwarded-tcpip`, `forwarded-streamlocal`, both under `tunnel`;
> no map, no generic key), one acceptor trait per type; install is
> **refuse-never-replace** (the `ListenRouter::register` recorded
> posture, mirrored client-side); the slots are read **at arrival
> time** by the dial handler's hooks, so a pre-install/unfeatured open
> is declined at arrival, never buffered. The payload an accepted
> open hands the assembly: the channel duplex (family-typed, the
> `-L` rows' `TunnelChannel` byte duplex, one type both legs ride) +
> the open's echo/originator fields; **the pump is the acceptor's**
> from the handoff on (the family handler shape), and the crate keeps no
> accepted-open ledger. Bounded bookkeeping, the cap relation: the
> registry bounded by construction (two slots); the
> **reverse-listen count** and the **accepted-open handoff count**
> are two dedicated counters, each against the same
> `Limits::max_concurrent_channels` ceiling (the server-side
> listener/ListenerCap posture mirrored: independent counts, one
> ceiling; the listens live at the peer, and the counter exists so a dial
> cannot mint an unbounded listener set). The **forward-request rows
> gate on the registered acceptor** (the issuing-side disposition:
> a listen whose data leg cannot serve is never asked for;
> install-first, `OpError::NoAcceptor` pre-wire), plus
> `OpError::ListenRefused` (the peer's `RequestDenied`:
> denied
> listens and unknown-listener cancels, sshd raw-string parity) and
> `OpError::ListenCapExceeded` (the ceiling, pre-wire). The
> **runtime-Unix gate** rides the unix *listen* rows only (the bind
> is the platform-bound op; the `forwarded-streamlocal` ingestion is
> platform-neutral byte pumping). The `tcpip_forward` reply's mint
> rides only for `port = 0` requests (russh/sshd parity: an explicit
> port's bound *is* the requested port, which the row surfaces).

## Lifecycle primitives (OQ-12 resolution)

- Forward listeners return the **actually-bound port** (russh
  `tcpip_forward -> u32`); every listener/handle is explicitly
  cancellable; disconnects are explicit (`Disconnect::ByApplication`).
- **No reconnect or restore policy is owned by the crate.**
  Reconnect-and-restore (rebinding persisted tunnel ports, the
  alkminer flow) is assembly policy; the crate provides the
  primitives (bound ports, handles, cancellation, clean close) to
  make that possible.

> **The landed lifecycle surface (`w4-lifecycle`, recorded at
> landing):** the `-R` listens return **`ReverseListener` handles**,
> with the `ReverseEndpoint` carried (the *actually bound* values:
> the wire address + the bound port / the socket path, the
> assembly's own record for a rebind policy it may compose) and the
> explicit `cancel()` as the wire-honest teardown (the confirmed cancel
> also releases the connection's listener count; a repeat rides the
> wire and hits the unknown-listener refusal). The **stateless**
> cancel forms (`reverse_listen_cancel` + the unix twin) ride beside
> the handles 1:1 (sshd's global-request cancels are stateless, so a
> cancel by the raw wire strings works from anywhere, including
> after the handle itself is gone: the handle shares the
> connection's internals through the arc, so its `cancel()` is the
> same wire op). **No `Drop` hides a wire op** on any of these
> handles: a cancellation/bundle of the wire ops is async and cannot
> run in a sync `Drop`, and at this russh pin dropping the last
> wire-stack handle ends the client runner, so the transport *breaks*
> (the peer observes an error-class session end, never the clean
> disconnect message). The primitives-not-policy posture is the
> module-docs contract: `client.rs` §Lifecycle posture (the
> primitives list + the abrupt-drop/clean-close boundary,
> row-pinned both ways) and `client_accept`'s recorded decisions;
> the alkminer reconnect-and-restore flow stays assembly
> composition (reverse-runner fact 4).

## What the crate does *not* include (client direction)

- **Job supervision**: background-job lifecycle (the alkminer
  start/stop/logs job model, pid files, host-side ledgers) is
  assembly work composed over the exec rows; the crate gives the
  channels and the exit semantics (including the pipe-mode
  pid-only signal caveat from `mapping.md`'s derivation contract).
- **Credential storage policy**: assembly (the vault handle is
  injected; ADR-005 / OQ-06).
- **Trust decisions**: the host-key policy is assembly-provided
  (OQ-05; the crate default rejects; a permissive case-2 policy for
  ephemeral fleets is the assembly's to choose, since the crate
  carries no trust model of its own).
- **sftp**: the `sftp` feature is the tested decline placeholder on
  both directions (OQ-13 resolved); the alkfs-protocol mapping
  arrives with alkfs, as its own ADR.

## Correctness facts to carry (POC-recorded)

> **The landed op-row shape (`w4-op-rows`, recorded at landing):**
> the exit-*consuming* rows (session exec/pty, git exec) ride the
> **split-halves wait-pump** (`Channel::split()` + a spawned task
> draining `wait()`), never `into_stream()`: the conversion's reader
> side swallows exactly the non-`Data` messages the exit reports ride
> on, so a wait-pump is the only shape that can consume them (the
> same reason `w4-git-exit-close` pinned the split-halves shape
> server-side). Only the exit-less rows (the tunnel directs) use
> `into_stream()`, straight after the typed open; no queue
> consumption ever precedes a conversion, which is POC-1 §6's caveat
> respected by construction. The session rows' family plane is the
> alktty chunk framing both directions (stdin/`CTRL_IN` out, stdout/
> stderr in, the family exit chunk in-band, last, per `exit_code.rs`'s
> two-arm contract: the server arm derives wire reports from family
> codes, the client arm mirrors wire reports into family codes,
> `−signum` through the one table, the `−1` sentinel never widened).
> The op surface carries no russh types: `OpError` mirrors the typed
> open's decline classes (`OpenDeclineReason`), the `wait()`-drain's
> `Failure` reply is `RequestRefused`, and the sftp placeholder
> declines in every build before any wire op (OQ-13).

- `Channel::exec()` (no `request_exec` at this pin); pty/subsystem
  request failures surface as `ChannelMsg::Failure` via `wait()`, not
  `Err` from the call; the caller must drain until the expected
  message and `continue` past the rest.
- `window_change`/`signal` are fire-and-forget and must be sent
  **before** `into_stream()` (the Channel is consumed by conversion);
  server-side they carry no SSH reply.
- Do not consume the channel queue before `into_stream()`: a
  `wait()` on a fresh channel breaks it (POC-1 §6 caveat), both sides.
- Keepalives on cloud fleets: 15 s / 3 (OpenSSH
  `ServerAliveInterval=15`/`CountMax=3` parity), since with russh's
  default (none) dead NAT'd connections sit unnoticed until an exec
  health check fails (`reverse-runner.md` lesson 3).
- A rejected channel open is an `Err` from the typed open call (not a
  `wait()`-match); the connection stays usable after declines.

## Open Questions

None open or deferred; see [open-questions.md](open-questions.md)
(all of OQ-01…13 resolved). Doc-local contract anchors: OQ-05 (the
host-key policy, §The dial surface), OQ-12 (lifecycle primitives only,
§Lifecycle primitives), OQ-13 (the sftp decline placeholder, §op
rows and §not-include), OQ-07 (closed upstream: the vault returns a
`Zeroizing<String>` from alkvault 0.2.0; ADR-005 decision 3 amended,
the adapter-side wrap dropped).

## References

- ADR-002 (the client `russh` surface + config knobs), ADR-003 (§1a the
  alksocks composition; the symmetry rule), ADR-004 (fingerprint
  identity), ADR-005 (key sources), ADR-006 (route-1 bridge, both
  legs)
- `docs/research/reverse-runner.md` (the consumer pattern + lessons),
  `poc-3-mapping-bakeoff.md` §D.3 (client mechanics), §C.4 (the fabric
  recipe), `poc-1-auth-bridge.md` §6/§7 (open-call `Err` semantics,
  plumbing), `poc-2-vault-keys.md` (dial lifecycle)
- `mapping.md` (the server-direction mirror rows)