rustdesk-server-starry 1.1.16-patch-v1.3.1

Based on official rustdesk/rustdesk-server 1.1.16.

Container image: https://github.com/q1ngyang/rustdesk-server-starry/pkgs/container/rustdesk-server-starry

Recommended Docker deployment: https://github.com/q1ngyang/rustdesk-server-starry/wiki/Docker-Deployment

Container guide: https://github.com/q1ngyang/rustdesk-server-starry/blob/1b8080bf074e3236cf9a3c0dfae2bdf16832249e/docs/container/CONTAINER.md

Single-host Compose asset: https://github.com/q1ngyang/rustdesk-server-starry/releases/download/1.1.16-patch-v1.3.1/compose.yaml

Control Agent sidecar example: https://github.com/q1ngyang/rustdesk-server-starry/blob/1.1.16-patch-v1.3.1/examples/control-agent/compose.yaml

中文发布说明：https://github.com/q1ngyang/rustdesk-server-starry/blob/1b8080bf074e3236cf9a3c0dfae2bdf16832249e/docs/releases/RELEASE-NOTES-patch-v1.3.1.zh-CN.md

Verify binaries, packages, documentation, and the deployment-example
archive against SHA256SUMS before use.

patch-v1.3.1 preview notes

English | 简体中文

patch-v1.3.1 is developed from the frozen patch-v1.3.0 baseline commit
abf1dbcfdf7c4384f8c7ac34724089932a1bc58c. It adds the Starry half of Akari
FastCompat/FastMediaV1 Relay support and Starry Pairing v1 while preserving
official clients, old Akari, manual deployments, and the frozen Relay Quality
v1 contract.

Release state: PREVIEW_APPROVED. The wire and Control contract is frozen at commit
6f5a31008ab7761d8557c8cf9fefcb5be11c49e6, whose
CONTRACT-RELEASE-SUMMARY.json SHA-256 is
67cc28287ed8c6fedfc37b88c6b0ecbc95a734a4644a34bfbb2d85e6d801df67.
The source candidate has passed a protocol-level
Akari↔HBBS↔HBBR dual-role authorization/bind, encrypted forwarding, reliable
fallback, and same-session automatic re-entry harness. This is sufficient for
an opt-in preview whose Fast switches remain off by default. It is not stable
runtime approval: the real two-client GUI/signalling, device/NAT/fault matrix,
and production PKI gates have not passed for one exact reviewed commit.

Fast Relay and FastMedia

• HBBS now signs its own final Relay even when Relay Quality is disabled, has
  fewer than two compatible candidates, times out, or uses legacy fallback.
  A completed Relay Quality v1 decision remains authoritative, and ordinary
  relay_server always equals the signed relay_server.
• FastRelayAuthorization.version = 1 retains fields 1–6 and appends tags
  7–12: UDP protocol, selected Relay, UDP port, fresh 16-byte allocation ID,
  datagram bound, and endpoint role. Controller is role 1 and target is role 2.
• FastMedia sessions receive two different Ed25519 combined grants; an old
  six-field FastCompat grant remains compatible. Both feature switches default
  to false and failures retain the reliable HBBR stream.
• HBBR implements the 32-byte AKR1 envelope and Hello/Cookie/Bind/Bound/Media
  state machine. It uses a source-bound stateless cookie, verifies role grants,
  pins allocation/session/Relay/source tuples, waits for both roles, validates
  the clear AKF1 preamble, strips AKR1, and forwards encrypted AKF1 unchanged.
• Same-role migration requires a new cookie and atomically revokes the old
  tuple. Grant size, datagram size, expiry, half-bind/idle/absolute lifetime,
  allocation count, cleanup work, replay window, rebinds, and per-role/per-IP/
  global traffic are bounded.
• The signed bitrate is the encoded-source ceiling. HBBR permits at most
  ceil(source × 1.45) wire Kbit/s with a role burst bounded by
  max(256 KiB, 50 ms wire allowance).

Relay Quality v1 correction

The frozen protobuf, tags, scoring, staged strategy, telemetry interpretation,
hysteresis, reason codes, privacy, and digest are unchanged. Only the native
initial-response route guard is corrected: PunchHoleSent/LocalAddr may use
a new target source port when the original controller route, target IP and ID,
allocation, stage/token, target role, candidate set, and generation all match.
Top-level reports and controller routes remain exact; one identical duplicate
is idempotent and a conflicting duplicate is rejected.

Schema v5, telemetry, and Control API

Schema v5 adds independent, default-off fast_compat_enabled and
fast_media_v1_enabled, relay_max_datagram, and a per-Relay
fast_media_udp_port. FastMedia authorization requires fresh authenticated
telemetry schema 2, explicit fast_media_relay_udp = 1, and a healthy UDP
listener. Public client probes do not expose this load/runtime data.

Authenticated HBBR telemetry adds capability, UDP health, active allocations
and streams, and bounded cookie/bind/grant/role/session/allocation/rebind/
forward/drop/rate/replay/expiry/listener counters. Control API exposes only
typed per-Relay status and bounded aggregates. It never exposes full client
addresses, UUIDs, allocation IDs, nonces, stage tokens, grants, secrets, or
media.

Starry Pairing v1

• starry-control-agent pair, adopt, and rotate consume a short-lived,
  single-use SP1 code only from stdin or a mode-0600 file. The Agent generates
  its private key and CSR locally, validates Broker origin/SPKI pin, response
  bindings, key/certificate match, CA signature, and certificate lifetime, and
  never overwrites an unrelated existing identity. An explicit
  --tls-server-name is placed in the CSR as a validated DNS SAN; interrupted
  first pairing reuses its durable pending instance UUID, and rotation
  preserves the validated installed Agent-v1 runtime settings.
• Relay enrollment is authorized by the existing mTLS/JWT Control Agent API.
  Kessoku may broker claim delivery but cannot choose Relay endpoints, pools,
  secrets, or configuration. Prepare/complete/health-activate/revoke/list/get
  operations are bounded and idempotent. Health activation additionally binds
  a succeeded config operation ACK to the exact generation and a freshly read
  HBBS inventory snapshot before the enrollment becomes active. Revocation
  retires only the exact current credentials, and a later same-node enrollment
  may clean up only a matching revoked or expired predecessor.
• starry-relayctl enroll generates the Relay node key locally without
  changing upstream hbbr CLI. Each Relay gets a separate telemetry secret,
  certificate, approved runtime configuration, and a non-secret
  relay-compat.env that points to the secret file.
• Manual Agent YAML/mTLS/JWT and manual HBBR public-key/secret-file operation
  remain supported. Established data planes do not depend on the Broker.

Persistent deployment boundary

All container Control identity/state/shared-token/generated config,
per-Relay material, and compatibility snapshots live below
STARRY_PERSIST_ROOT. Relay enrollment lives below RELAY_DATA_DIR.
Pairing/startup rejects container overlay/tmpfs state, unsafe path types or
permissions, absent explicit mounts, and Relay host-identity mismatch. The
image has no anonymous /root volume.

pull, force-recreate, and down/up retain identities when the same host
roots are mounted. down -v, mounting a different relative directory, and
concurrent identity clones are fail-closed operator errors. Native/DEB layouts
use /etc/rustdesk-server-starry and /var/lib/rustdesk-server-starry; normal
package upgrade/downgrade does not overwrite identity.
The Relay-only Compose profile defaults enrollment enforcement to 1; the
preserved manual public-key mode requires an explicit 0 and must not be used
to restart a previously enrolled Relay with missing state.
The compatibility-file parser splits each allowlisted assignment at its first
delimiter so standard Base64 padding in the public RustDesk KEY is retained.

Upgrade and rollback

Upgrade HBBR first, then HBBS, Control Agent, and finally compatible Akari.
Keep both Fast switches disabled until authenticated schema-2 telemetry and
reliable-session regression tests pass. Canary FastCompat before FastMedia.

For v1.3.1→v1.3.0, first disable FastMedia and use
starry-control-agent config downgrade --to-schema 4 --preview. The command
queries the local Agent for active allocations, authorizations, streams, and
latest grant expiry; an audited --runtime-state file is an explicit offline
override. Export is refused until all are drained and every Agent/Relay
certificate has at least ninety days remaining. The output removes only v5
fields and never overwrites its destination.

patch-v1.3.0 can read pairing-generated Agent v1 YAML/PEM/JWKS. Enrolled HBBR
uses relay-compat.env for its public KEY and existing telemetry secret-file
path, retaining ordinary Native/WSS Relay and telemetry. The old version
ignores rather than deletes enrollment/FastMedia state; upgrade back to v1.3.1
reuses identity and requires fresh UDP health.

Compatibility matrix

Client/HBBR combination	Result
Official clients + official/legacy HBBR	Ordinary P2P/LAN/Relay is unchanged; no Fast grant or UDP candidate.
Old Akari + patch-v1.3.1 HBBR	Six-field FastCompat remains accepted; unknown fields are ignored; reliable Relay remains.
New Akari + legacy HBBR	HBBS may issue FastCompat for its final Relay but never FastMedia; UDP capability is null/fail-closed.
New Akari + healthy patch-v1.3.1 HBBR	Role grants and AKR1 are eligible when policy/authentication gates pass; reliable Relay remains connected.
Mixed official/new Akari	Official endpoint ignores tag 64; the ordinary HBBS-selected Relay remains interoperable.
v1.3.1 enrollment + v1.3.0 runtime	Agent v1 credentials and ordinary Relay/telemetry survive; pairing automation and FastMedia are ignored.

Frozen contract candidate

Relay Quality v1 remains the already-frozen inherited contract. The unique
patch-v1.3.1 CONTRACT-RELEASE-SUMMARY.json freezes Control OpenAPI, config
schema v5/UI schema, capabilities/relays/status, Re...

rustdesk-server-starry 1.1.16-patch-v1.3.0

Based on official rustdesk/rustdesk-server 1.1.16.

Container image: https://github.com/q1ngyang/rustdesk-server-starry/pkgs/container/rustdesk-server-starry

Recommended Docker deployment: https://github.com/q1ngyang/rustdesk-server-starry/wiki/Docker-Deployment

Container guide: https://github.com/q1ngyang/rustdesk-server-starry/blob/abf1dbcfdf7c4384f8c7ac34724089932a1bc58c/docs/container/CONTAINER.md

Single-host Compose asset: https://github.com/q1ngyang/rustdesk-server-starry/releases/download/1.1.16-patch-v1.3.0/compose.yaml

Control Agent sidecar example: https://github.com/q1ngyang/rustdesk-server-starry/blob/1.1.16-patch-v1.3.0/examples/control-agent/compose.yaml

中文发布说明：https://github.com/q1ngyang/rustdesk-server-starry/blob/abf1dbcfdf7c4384f8c7ac34724089932a1bc58c/docs/releases/RELEASE-NOTES-patch-v1.3.0.zh-CN.md

Verify binaries, packages, documentation, and the deployment-example
archive against SHA256SUMS before use.

patch-v1.3.0 release notes

English | 简体中文

patch-v1.3.0 adds three Akari-focused features while preserving the official
RustDesk client wire path: active candidate-Relay quality scoring, signed
FastCompat Relay authorization for Akari's P2P fast mode, and generation-safe
Profile Activation Leases with bounded rapid re-registration. The reviewed
release-preparation change records approval; publication still fails closed
unless every source, security, protocol, package, image, and release-candidate
job succeeds for the exact commit receiving the immutable tag.

What changed

HBBS can retain up to five eligible Relay candidates after transport, health,
GEO-rule, and configured-order filtering. The default adaptive strategy asks
both Akari endpoints to probe only the GEO primary first. HBBS accepts that
primary when its server-interpreted score and loss meet the configured
good-enough thresholds; otherwise it concurrently expands both endpoints to
the remaining candidates. strategy: eager remains available for explicit
all-candidate probing. Only HBBS combines the reports with trusted HBBR load,
chooses one Relay, and writes the same result to the ordinary relay_server
and decision extension.

Each stage has a fresh token and a server deadline. Reports bind allocation,
stage, token, endpoint role, configuration generation, signalling route, and
both endpoint IPs. Duplicate reports are idempotent, old-stage or replayed
reports cannot change a decision, and a bounded HBBS timer completes partial
or fallback decisions at the deadline. Successful P2P explicitly cancels the
allocation without waiting for Relay probes. Force Relay, symmetric NAT, WSS,
and mixed paths wait for the final server decision before connecting HBBR.

The default score is higher-is-better on 0..10000:

• RTT: 40%; for two successful endpoint reports, effective RTT is
  (2 × max(RTT_A, RTT_B) + RTT_A + RTT_B) / 4;
• jitter: 20%, using the worse endpoint;
• loss: 25%, using the worse endpoint; and
• Relay load: 15%, using HBBS-observed HBBR telemetry.

Missing endpoint measurements receive a configurable penalty. A symmetric
IPv4 /24 or IPv6 /56 cache plus a score hysteresis threshold avoids Relay
flapping. Full client IP addresses are not used as cache keys.

HBBR now accepts one bounded RelayProbeRequest on either native framed TCP or
WebSocket Relay transport and returns a nonce-bound RelayProbeResponse.
Public /ws/relay handshakes and probe responses expose only the exact Starry
version plus probe/load protocol capability versions; they never contain the
detailed load snapshot. HBBS obtains active sessions, pending pairs, bandwidth
EMA, capacity, draining/admission state, and aggregate counters only from the
authenticated /ws/telemetry channel. The upstream session pairing and
byte-forwarding loop remains intact.

HBBR enforces global and source-IP probe budgets and publishes only bounded
malformed, unsupported, rate-limited, and successful counters. It also treats
STARRY_RELAY_MAX_SESSIONS as a real admission limit: capacity or draining
rejects new pairs without terminating existing sessions. Every signed schema-v1
snapshot carries a process instance ID, monotonic sequence, observation time,
uptime, and admission-rejection count so HBBS can fail closed on replay, stale
data, or an instance restart.

Mixed sessions receive endpoint-specific probe URLs under one allocation: the
native side measures native TCP while the WebSocket side measures WSS.

After connection authentication and the final Relay-quality decision, HBBS
can sign a short-lived FastRelayAuthorization with its existing Ed25519 key.
The target's RequestRelay and controller's RelayResponse receive the exact
same signed bytes. Grants are bound in server memory to the session UUID,
initiator IP, target IP, selected Relay, allocation, and active configuration
generation. Valid retries reuse the original decision and signature without
extending expiry.

This release authorizes only FastCompat over the existing reliable HBBR
stream. Every signed grant explicitly sets allow_fast_media_v1 = false;
Relay-side FastMedia UDP is not implemented or advertised in patch-v1.3.0.

Akari registration can now include a 16-byte random activation ID and a
monotonic epoch. A successful Ready ACK echoes both and returns an opaque
32-byte, node-local route lease plus the HBBS route generation. Akari commits
the Profile switch only after all values match. Native UDP/TCP and WSS share
one generation authority; explicit DeactivatePeer, WSS reader exit, idle
drain, delayed packets, and A→B→A switching can remove only their exact current
route. A 45-second lease TTL remains the crash fallback.

Verified re-registration requires an exact stored peer ID, network identity
UUID, and public key. It receives a bounded 12-new-lease burst per rolling 30
seconds while the global/IP blocker remains active. The optimization neither
deletes registration limits nor relies on a shorter TTL. HBBR receives no new
Profile-activation data message.

Compatibility contract

All Starry fields are additive protobuf extensions: Relay-quality messages use
tags 100+, while the opaque signed authorization uses unoccupied tag 64 in
RequestRelay and RelayResponse. No official field is renumbered or retyped.
Compatibility behaves as follows:

Initiating client	Controlled client	Behaviour
Official	Official or Akari	Legacy HBBS selection and one ordinary relay_server; no quality allocation or FastCompat grant is created.
Akari protocol v1	Official	Akari probes the primary and, if needed, the remaining candidates alone; the missing peer report is penalized and marked partial. The selected ordinary relay_server works for the official peer. The official peer ignores tag 64.
Akari protocol v1	Akari protocol v1	Both endpoints probe the primary, expand together only when required, and receive one HBBS decision; when all authorization gates pass HBBS forwards the same signed FastCompat grant to each side.
Akari without an offer	Any	Direct RequestRelay remains on the legacy path. Force-Relay mode should first perform the quality-capable PunchHole preflight.

Official HBBR implementations do not understand the probe oneof and simply
close that short probe connection. They can remain an explicitly configured
ordinary relay_server fallback, but never enter a quality offer or consume
max_candidates. Production quality pools must use HBBR that explicitly
advertises relay_probe_protocol=1 and relay_load_protocol=1; Starry version
strings are inventory only and never imply capability.

The normative field binding and message definitions are in the
Relay Quality v1 contract and
Fast Relay Authorization v1 contract.
The matching-ACK, deactivation, multi-node, rollout, and rollback rules are in
the Profile Activation Lease v1 contract.

Configuration

Relay quality requires schema v4 and is off by default:

version: 4
relay_servers:
  - relay-asia-1.example.com:21117
  - relay-asia-2.example.com:21117

websocket_signal:
  relay_health:
    endpoints:
      - relay: relay-asia-1.example.com:21117
        url: wss://relay-asia-1.internal.example.com/ws/telemetry
        telemetry_secret_file: /run/secrets/starry-relay-telemetry
      - relay: relay-asia-2.example.com:21117
        url: wss://relay-asia-2.internal.example.com/ws/telemetry
        telemetry_secret_file: /run/secrets/starry-relay-telemetry

relay_quality:
  enabled: true
  strategy: adaptive
  legacy_fallback_relays: []
  max_candidates: 3
  primary_probe_samples: 3
  primary_accept_score: 8000
  primary_max_loss_basis_points: 500
  p2p_probe_grace_ms: 300
  probe_samples: 5
  probe_interval_ms: 50
  probe_timeout_ms: 1000
  report_timeout_ms: 15000
  max_telemetry_age_seconds: 180
  allocation_ttl_seconds: 30
  cache_ttl_seconds: 300
  max_allocations: 10000
  hysteresis_basis_points: 500
  missing_report_penalty_basis_points: 1000
  rtt_bad_ms: 300
  jitter_bad_ms: 100
  weights: {rtt: 4000, jitter: 2000, loss: 2500, load: 1500}

fast_mode:
  relay:
    fast_compat_enabled: false
    authorization_ttl_seconds: 90
    max_bitrate_kbps: 50000

Weights must all be positive and sum to 10000. Enabling quality requires at
least two non-legacy Relays, one unique telemetry endpoint for every quality
Relay, and max_candidates >= 2. Configure ev...

rustdesk-server-starry 1.1.16-patch-v1.2.2

rustdesk-server-starry 1.1.16-patch-v1.2.2

• Based on official rustdesk/rustdesk-server 1.1.16.
• Adds private ID/UUID registry verification for Kessoku device discovery.
• Image: ghcr.io/q1ngyang/rustdesk-server-starry:1.1.16-patch-v1.2.2 (linux/amd64).
• Verify release assets with SHA256SUMS and the attached attestations.
• Read more · 中文说明 · Docker guide

rustdesk-server-starry 1.1.16-patch-v1.2.1

Based on official rustdesk/rustdesk-server 1.1.16.

Container image: https://github.com/q1ngyang/rustdesk-server-starry/pkgs/container/rustdesk-server-starry

Recommended Docker deployment: https://github.com/q1ngyang/rustdesk-server-starry/wiki/Docker-Deployment

Container guide: https://github.com/q1ngyang/rustdesk-server-starry/blob/519be8372d78c459bb79a6660d90013ba63e307e/docs/container/CONTAINER.md

Single-host Compose asset: https://github.com/q1ngyang/rustdesk-server-starry/releases/download/1.1.16-patch-v1.2.1/compose.yaml

Control Agent sidecar example: https://github.com/q1ngyang/rustdesk-server-starry/blob/1.1.16-patch-v1.2.1/examples/control-agent/compose.yaml

中文发布说明：https://github.com/q1ngyang/rustdesk-server-starry/blob/519be8372d78c459bb79a6660d90013ba63e307e/docs/releases/RELEASE-NOTES-patch-v1.2.1.zh-CN.md

Verify binaries, packages, documentation, and the deployment-example
archive against SHA256SUMS before use.

patch-v1.2.1 release notes

English | 简体中文

Adds Relay version reporting: HBBR advertises its exact Starry version during
the WebSocket handshake, HBBS records it through the existing health probe,
and Control API v1 exposes it in the Relay inventory. Legacy or unprobed Relay
nodes continue to report null.

rustdesk-server-starry 1.1.16-patch-v1.2.0

Based on official rustdesk/rustdesk-server 1.1.16.

Container image: https://github.com/q1ngyang/rustdesk-server-starry/pkgs/container/rustdesk-server-starry

Recommended Docker deployment: https://github.com/q1ngyang/rustdesk-server-starry/wiki/Docker-Deployment

Container guide: https://github.com/q1ngyang/rustdesk-server-starry/blob/1.1.16-patch-v1.2.0/CONTAINER.md

Single-host Compose asset: https://github.com/q1ngyang/rustdesk-server-starry/releases/download/1.1.16-patch-v1.2.0/compose.yaml

Control Agent sidecar example: https://github.com/q1ngyang/rustdesk-server-starry/blob/1.1.16-patch-v1.2.0/examples/control-agent/compose.yaml

中文发布说明：https://github.com/q1ngyang/rustdesk-server-starry/blob/1.1.16-patch-v1.2.0/RELEASE-NOTES-patch-v1.2.0.zh-CN.md

Verify binaries, packages, documentation, and the deployment-example
archive against SHA256SUMS before use.

patch-v1.2.0 release notes

English | 简体中文

patch-v1.2.0 prepares strict connection authentication, observable Relay
allocation, and a least-privilege management plane while preserving Starry's
overlay model and the official RustDesk wire protocol.

These are the release notes for the full 1.1.16-patch-v1.2.0 artifact tag.

The reviewed release-preparation change sets RELEASE_STATUS to APPROVED.
Publication still fails closed unless every source, security, test, package,
image, and release-candidate job succeeds for this exact commit.

Component and platform scope

• The overlay still changes HBBS only. HBBR remains unmodified.
• No account, address-book, or device API is included.
• starry-control-agent is a separate optional management binary. Its remote
  API never proxies the HBBS 21115 protocol and exposes no shell, arbitrary
  file, URL, process, Docker socket, or generic command operation.
• Writable Control Agent transactions and all promised v1.2.0 artifacts are
  supported on Linux amd64. The release contains a linux/amd64 image, Linux
  x86_64 binaries/tar, and amd64 DEBs. ARM remains best-effort source
  compatibility; Windows is an experimental non-blocking build. Neither ARM
  nor Windows enters the v1.2.0 candidate.

Recommended Docker deployment

Docker Compose on a Linux amd64 host remains the recommended deployment path.
The published image contains Starry HBBS, an unmodified convenience HBBR,
rustdesk-utils, and the optional Control Agent; the recommended single-host
example deliberately runs HBBR from the matching official RustDesk Server
image so the component boundary remains visible.

• GHCR image page
• Container image guide
• Recommended Docker deployment guide
• Single-host Compose example
• Control Agent sidecar example
• Multi-node deployment guide

After publication, pull the immutable release tag rather than relying on
latest:

docker pull ghcr.io/q1ngyang/rustdesk-server-starry:1.1.16-patch-v1.2.0

Configuration lifecycle

• Schema v3 adds connection_auth; schema v1/v2 remain accepted with
  authentication off.
• Runtime state now records generation, exact source digest, effective digest,
  activation time, and subsystem acknowledgements.
• A missing, empty, or invalid first configuration keeps upstream-compatible
  behavior. A rejected later reload retains the active last-known-good
  generation and reports the error.
• Candidate parsing/validation is separated from activation. Configuration is
  not reported as active until required subsystems acknowledge the same
  generation.

Connection authentication

• One shared verifier runs after bounded frame/protobuf parsing and before
  target lookup, punch recording, Relay selection, or delivery.
• It covers controller PunchHoleRequest and direct RequestRelay on native
  TCP, negotiated Secure TCP, and /ws/id WSS.
• UDP initiation remains unsupported and receives no allocation path.
• Native controlled-endpoint registration and heartbeats in official 1.1.16
  still use the upstream UDP path. That path does not carry the controller
  requests above and cannot bypass controller authentication. Use WSS
  registration when controlled-endpoint UDP must be disabled.
• Only access JWTs with alg=EdDSA, typ=at+jwt, and an explicit kid
  selecting a public Ed25519 JWK are accepted. Issuer, audience, token use,
  complete scope value, numeric user_id, decimal sub binding, positive
  auth_version, UUID jti, iat, nbf, exp, token size, and signature
  are mandatory. These rules match Kessoku's issued wire representation and
  the checked-in byte fixtures.
• JWKS rotation is atomic and last-known-good. Remote-cache freshness is stored
  in a digest-bound sidecar so restart or reload cannot reset key age. Missing,
  mismatched, or stale metadata, invalid refreshes, and configured
  introspection failures cannot fail open.
• Any configured remote JWKS or introspection endpoint requires HTTPS plus an
  explicit CA, client certificate, client key, and exact DNS server name.
  These internal clients require TLS 1.3 and disable system roots and
  redirects. Local
  JWT failure never calls introspection; an introspection request uses
  Kessoku's strict token-only DTO and the returned subject must match the
  locally verified JWT.
• audit records would-allow/would-deny without changing the connection;
  enforce uses stable, target-independent existing protobuf denial fields.
• --must-login is a deployment enforce floor that config reload and the
  remote management plane cannot lower.

The normative profile and byte fixtures live under contracts/auth/v1.

Relay visibility and simulation

• HBBS publishes an immutable Relay/config/health snapshot to the local
  control layer.
• Relay probe or readiness changes advance the health snapshot identity, so
  inventory, production allocation, and simulation on that snapshot can be
  correlated accurately.
• Allocation simulation shares the production decision core but does not
  advance rotation, mutate health/config state, create a Relay UUID, deliver a
  peer message, or increment production allocation counters.
• Responses include generation/snapshot identity, normalized endpoint facts,
  ordered rule/Relay decisions, the selected result, and warnings.

Control Agent v1

• Remote access requires both a client certificate chaining to the configured
  CA with an exact allowed URI SAN and an independent short-lived EdDSA service
  JWT bound to the Agent instance and requested scope.
• The fixed API provides capabilities, status, Relay inventory, allocation
  simulation, config schema/state/validation, configuration transactions,
  operation lookup, history, rollback, and audited runtime reload.
• Every known HTTP action is mapped to an exact scope and verifies the mTLS/JWT
  principal before body allocation. Unknown actions remain 404.
• The loopback HBBS bridge accepts only bounded STARRYCTL/1 frames carrying a
  constant-time-checked secret from an absolute, regular, mode-0600 token file.
  The legacy text-command dispatcher is not reachable at runtime.
• config.write_enabled defaults to false. In that profile the Agent omits
  write capabilities and returns 404 for plan/apply/rollback/reload after
  authentication.
• Apply uses a plan bound to instance, caller, exact-byte ETag, runtime
  generation, candidate digest, and expiry. If-Match and an idempotency key
  are mandatory for mutations.
• Resident plans are bounded by count and aggregate bytes; idempotent replays
  are bound to the Agent instance and the authenticated caller identity.
• Intent, operation, idempotency result, revision, recovery material, and
  redacted audit data are durable. The raw JWT and raw idempotency key are not
  persisted.
• Candidate publication uses temporary-file create/write/fsync, atomic rename,
  directory fsync, and synchronous HBBS activation acknowledgement. Failure
  restores the original bytes and runtime; unresolved recovery enters
  manual_intervention_required and blocks later writes.
• A write-enabled Agent validates at startup that an existing managed config
  is a single-link regular file owned by the Agent's effective UID and primary
  GID, so an ownership-preserving atomic replacement cannot fail late.

See contracts/control/v1/openapi.yaml and
the Control Agent guide.

Upgrade and rollout

1. Back up the HBBS data, exact config bytes, identity key, and prior image or
   package. Do not start the Agent yet.
2. Upgrade HBBS while retaining the existing schema v1/v2 config and verify
   native, Secure TCP, WSS, and mixed paths that the deployment already uses.
3. Move to schema v3 with connection_auth.mode: off; reload and verify the
   activation acknowledgement and generation.
4. Deploy the Agent in read-only mode on a private management path and verify
   mTLS, service-JWT scopes, status, Relay inventory, and simulation.
5. Test write transactions and rollback in staging before setting
   write_enabled: true anywhere else.
6. Deploy compatible client JWT issuance, JWKS, and mTLS introspection. Run
   audit for a complete business cycle and reconcile every would-deny reason.
7. Canary enforce on one instance or user cohort; then expand only after real
   ...

rustdesk-server-starry 1.1.16-patch-v1.1.0

Based on official rustdesk/rustdesk-server 1.1.16.

Includes ordered GEO Relay routing, native HBBS Secure TCP compatibility,
and opt-in persistent WebSocket Signal for restricted enterprise networks.

patch-v1.1.0 keeps native/P2P signalling as the default. When a client
explicitly enables WebSocket, HBBS supports persistent WSS registration,
bounded session routing, mixed WSS/native Relay sessions, trusted-proxy
source handling, and certificate-verified /ws/relay health filtering.

Docker Compose

Download compose.yaml and compose.env.example, then run:

cp compose.env.example .env
mkdir -p data
docker compose --env-file .env -f compose.yaml up -d

Starry creates the empty functional configuration at
data/starry/config.yaml and the documented template at
data/starry/config.example.yaml. GEO, MMDB, Secure TCP, and
Relay priority and WebSocket Signal settings belong in that YAML file,
not in .env.

Documentation: https://github.com/q1ngyang/rustdesk-server-starry

简体中文

下载 compose.yaml 与 compose.env.example，将后者复制为
.env 后执行上面的 Compose 命令。功能配置仍写入
data/starry/config.yaml，不要把 GEO、MMDB、Secure TCP 或 Relay
规则或 WebSocket Signal 设置放入 ENV 文件。patch-v1.1.0 默认仍走原生
信令/P2P；只有客户端显式开启 WebSocket 时才走 WSS 与 Relay。

中文文档：https://github.com/q1ngyang/rustdesk-server-starry/blob/main/README.zh-CN.md

Verify local binaries and DEB packages against SHA256SUMS before installation.

rustdesk-server-starry 1.1.16-patch-v1.0.0

Based on official rustdesk/rustdesk-server 1.1.16.

Includes ordered GEO Relay routing and native HBBS Secure TCP compatibility.

Docker Compose

Download compose.yaml and compose.env.example, then run:

cp compose.env.example .env
mkdir -p data
docker compose --env-file .env -f compose.yaml up -d

Starry creates the empty functional configuration at
data/starry/config.yaml and the documented template at
data/starry/config.example.yaml. GEO, MMDB, Secure TCP, and
Relay priority settings belong in that YAML file, not in .env.

Documentation: https://github.com/q1ngyang/rustdesk-server-starry

简体中文

下载 compose.yaml 与 compose.env.example，将后者复制为
.env 后执行上面的 Compose 命令。功能配置仍写入
data/starry/config.yaml，不要把 GEO、MMDB、Secure TCP 或 Relay
规则放入 ENV 文件。

中文文档：https://github.com/q1ngyang/rustdesk-server-starry/blob/main/README.zh-CN.md

Verify local binaries and DEB packages against SHA256SUMS before installation.