visor

Overview ¶

Package visor pkg/visor/api.go c3-vis-core

Package visor pkg/visor/api_all_transports.go c3-vis-core

Reader-side helper for the TPD all-transports CXO snapshot. The publisher lives in pkg/deployment/tpd/api/cxo_all_transports_publisher.go and writes JSON-encoded []*transport.Entry to two paths (transports/all/with-self, transports/all/without-self). This helper Acquires the TabCLITransports tab on the CXOSubscriptionManager, reads the requested path's snapshot, and returns the raw JSON body so FetchCXO can serve it to the CLI unchanged.

"Acquire on each call" is intentional and lightweight — the manager's reference counting plus close-grace amortize repeated CLI invocations within ~10s, and a CLI not running once a minute keeps the cycle from running forever.

Package visor pkg/visor/api_app_settings.go

The visor half of the live app-settings surface: a map of tuning knobs per app, held on the proc manager and PULLED by the app on a tick it already runs (pkg/app/appserver/app_settings.go explains why a pull and not a push).

The knobs themselves are opaque here — name → int64, plus name → string for the list ones, exactly as pkg/skysocks/skysettings encodes them. The visor carries them; the app's own registry owns their meaning, their kinds and their defaults, so a knob can be added to the client without touching this file or the wire.

What the visor DOES own is how long a knob lives. It outlives the app process (the proc manager no longer clears the set on stop) and it outlives the visor: every change is written to visorconfig.V1.AppSettings and restored into the store at boot, the way routing.mux_fec is. An operator who set a value gets to keep it until they reset it.

Package visor pkg/visor/api_apps.go c3-vis-core api_apps.go contains app management API methods.

Package visor pkg/visor/api_ar.go c3-vis-core

Package visor pkg/visor/api_browse.go c3-vis-core virtual browser (the native analog of the wasm-visor's skywireVisor.fetchDmsg / fetchClearnet). The same browse.js engine runs in the native hypervisor UI; instead of the wasm JS hooks it calls these over /api/browse/*.

Package visor pkg/visor/api_browse_client.go c3-vis-browse

Package visor pkg/visor/api_browse_jar.go c3-vis-browse

Package visor pkg/visor/api_browse_stream.go c3-vis-browse

Package visor pkg/visor/api_browse_ws.go c3-vis-browse

Package visor pkg/visor/api_config_fields.go c3-vis-core

Field-level editing of the RUNNING visor's config.

Editing skywire-config.json by hand while a visor runs does not work: the visor holds the config in memory and re-marshals the whole struct over the file on every setter that persists (see Visor.SetIsPublic, persistHypervisors, persistRouterKnobs, the launcher app updates, …). Whatever the operator typed into the file is erased at the next flush. The only durable edit is one the visor itself makes.

SetConfigFields is that edit. It addresses a field by its dotted JSON path, validates the value against the visorconfig.V1 struct, and then either

• hands it to the live setter registered for that path (liveConfigFields below), so the running subsystem picks it up immediately, or
• writes it into v.conf and flushes, which takes effect on the next start ("restart-required").

Path resolution is reflection over V1's json tags rather than a hand-written field table: the config grows every release, and a table would be stale the week after it was written. The LIVE half is a table, because "a running subsystem can pick this up" is a property of the code, not of the struct — one place to register a new live setter (see liveConfigFields).

Identity is not editable: sk/pk and every *_sk / *secret_key path is refused outright, matching SetRuntimeConfig. Maps another subsystem owns and rewrites wholesale (app_settings, routing.router_app_settings) are refused too, with a pointer at the command that does own them — persisting a value there would be silently overwritten by the owner's next flush.

Package visor pkg/visor/api_config_mirror.go c3-vis-core

Package visor pkg/visor/api_dmsg.go c3-vis-core api_dmsg.go contains DMSG ping, bandwidth, and HTTP API methods.

Package visor pkg/visor/api_dmsg_diag.go c3-vis-core

Package visor pkg/visor/api_fetch_cxo.go c3-vis-core

FetchCXO routes a (feed, path) pair to the matching lazy-on-demand CXO subscriber and returns the cached payload — or a miss reason the CLI's fetch chain can decide what to do with.

Adding a new feed: register a new (subscriber struct, ensure helper, Fetch helper) under pkg/visor/api_*_subscriber.go using the same lazy-on-demand pattern, then add a case to the switch below. The CLI side learns about it through its URL→feed mapping table; nothing in the RPC/marshal layer needs to change.

Package visor pkg/visor/api_host_stats.go c3-vis-core

HostStats — psutil-style resource snapshot of the host the visor is running on. Backs the hypervisor UI's "Resource Monitor" panel; the data shape is meant to be polled at ~1s and graphed.

Counter-style fields (network bytes, GC count, …) are cumulative since boot or process start; the client diffs across polls to derive a rate. Gauge-style fields (CPU%, mem%, RSS) are absolute.

The first call to cpu.Percent(0, …) returns 0 because there's no previous sample to compare against; that's fine — the second call returns a real value, and 1s polling means the "0 on first reading" only shows up briefly during initial paint.

Package visor pkg/visor/api_hypervisors.go c3-vis-core

Package visor pkg/visor/api_local_transport_stats.go c3-vis-core

Local transport-bandwidth read API. The visor's stats tracker (pkg/visor/stats) already keeps a bbolt-backed rollup of every transport's sent/recv counters and latency stats — current snapshot + per-day daily rollups, retained for a configurable window (default 30d). This file exposes that local data through the Visor RPC surface so the hvui's per-visor Bandwidth tab can render it without round-tripping through TPD.

Mirrors what `GET /stats/transports` and `/stats/transports/history` return on the visor's logserver, but reachable via the same hypervisor proxy chain everything else in the hvui uses.

Package visor pkg/visor/api_local_uptime_stats.go c3-vis-core

Local tier-uptime read API. The visor's stats tracker (pkg/visor/stats) keeps a 288-slot-per-day bitmap per tier (process / dmsg / skynet) reflecting which 5-minute slots the visor was observed online. This file exposes that data through the Visor RPC surface so the hvui's per-visor and network-wide Uptime tabs can render it through the same hypervisor proxy chain everything else in the hvui uses — no per-visor logserver HTTP client.

The wire shape mirrors `GET /stats/uptime` on the visor's logserver (a {tier: {date: 288-ascii}} map): the renderer just reads '.' as online, ' ' as offline.

Package visor pkg/visor/api_mux_controls.go c3-vis-core

The visor side of the DIAL-TIME and PER-LEG routing controls: the dial knob set (`skywire cli route settings dial`), the per-leg send-weight override and forward-only leg pin (`skywire cli proxy mux weights` / `proxy mux add --forward-only`), and the negotiated per-group view (`proxy mux negotiated`).

Everything here is one file — the API method, the RPC server method, the RPC client method and the two non-visor API stubs for each control — because the set is one feature and reading it in one place is worth more than filing each half next to its neighbors of the same kind.

The per-leg controls reach the router through router.MuxLegController, an OPTIONAL capability interface, rather than through the Router interface: a source-only (tinygo) router has no route groups to control, and asserting keeps that build compiling without stubs.

Package visor pkg/visor/api_network.go c3-vis-core api_network.go contains network connection, port forwarding, and module reinitialization API methods.

Package visor pkg/visor/api_network_view.go c3-vis-core

NetworkView — server-side combination of service-discovery, transport-discovery, and uptime-tracker data into a per-PK summary, mirroring the table that `skywire cli sd` prints.

Lives at the hypervisor scope (no per-visor binding) because the data is network-wide. Cached for shortLivedCacheTTL on the visor side to absorb the 30s+ poll the UI does, plus any concurrent CLI hits.

Package visor pkg/visor/api_ping.go c3-vis-core api_ping.go contains ping, bandwidth test, and visor test API methods.

Package visor pkg/visor/api_proxies.go c3-vis-core

Runtime status + live enable/disable for the in-process resolving proxies (dmsgweb, skynetweb). Hypervisor UI reads EmbeddedProxies to render its "browser proxy" widget and calls SetEmbeddedProxyEnabled to toggle resolvers without a visor restart.

Design note: toggling only affects the live runtime. The visor config file is NOT rewritten — a restart reverts to whatever Enable says on disk. That keeps runtime toggling a "session-scoped experiment" rather than a destructive operation, and avoids config-file-locking coordination with the config refresh path.

Package visor pkg/visor/api_proxy_tunnel.go

Per-tunnel teardown: close ONE of an app's tunnels and let the app's own standby pool replace it.

`proxy mux rm` cannot do this. It drops a LEG from a route group and the router refuses to take the last one, which is exactly the case a tunnel is — so a bench that wanted one tunnel gone had to cut the underlying transport on the host and take every other route over it down with it. The measurement it produced was therefore never the measurement it asked for.

The tunnel belongs to the APP, not to the visor: only the app knows which of its yamux sessions that route group carries, and only the app can put the replacement into the active set. So this is an op queued on the app's settings channel (pkg/app/appserver/app_settings.go) rather than a router call — the visor resolves the port to a real route group of that app first, so a typo is an error here and not silence five seconds later.

Package visor pkg/visor/api_routing.go c3-vis-core api_routing.go contains routing rule and route group API methods.

Package visor pkg/visor/api_routing_policies.go c3-vis-core surface for the hypervisor UI's routing-policy panel. Walks the router's installed DialHook (when it's a *policy.Hook) and projects its visor-wide default + per-app overrides into a JSON-friendly shape.

Read-only by design — runtime policy installation lives on the SetAppRoutingPolicy path (separate PR). This file only surfaces what's currently configured.

Package visor pkg/visor/api_runtime_config.go c3-vis-core

Whole-config replacement for the visor's on-disk config file. Companion to GetRuntimeConfig: lets the hvui round-trip the config through an editor pane and write the user-edited JSON back to disk.

Validation chain — failure at any step rejects the write:

1. Strict JSON decode into a fresh visorconfig.V1 with DisallowUnknownFields(), so typos in field names surface instead of silently dropping data.
2. SK/PK consistency — when both are present the PK must derive from the SK; when only SK is present the visor identity isn't accidentally rotated by an empty PK.
3. Non-empty config path on the live visor (refuse on STDIN- sourced or in-memory configs).

We deliberately do NOT attempt a hot-reload: the visor's many subsystems (router, app launcher, dmsg client, etc.) hold references to v.conf at startup, so swapping it in-process would leave them stale. Caller must restart the visor for the change to take effect — the hvui surfaces this in the response.

Package visor pkg/visor/api_services.go c3-vis-core api_services.go contains service discovery, health, and configuration API methods.

Package visor pkg/visor/api_skychat.go c3-vis-core

Skychat support — password management + reverse proxy.

The hypervisor UI surfaces skychat as a first-class tab. The browser doesn't talk to skychat directly; it goes through the hypervisor at /api/visors/<pk>/skychat/* which forwards to the skychat app's local HTTP listener. The proxy attaches a per-startup random "internal token" so authenticated hvui sessions bypass any password the user set on the standalone :8001 surface.

Package visor pkg/visor/api_skyenv.go c3-vis-core

Reading and editing /etc/skywire.conf from the running visor.

skywire.json is a derived file: `skywire autoconfig` regenerates it from skywire.conf on every package install and update, and the browser visor does so on every page load. A setting that lives only in the json — which is where SetConfigFields writes — lasts until that next regen. The .conf file is the layer that survives, and until now the only way to edit it was `skywire autoconfig --<flag>` in a shell on the host.

Edits are addressed by autoconfig flag name and go through the same flag→variable table (autoconfigcmd) and the same writer (skyenvfile.Update) as that command, so a setting changed here is byte-for-byte the setting `skywire autoconfig --<flag>` would have written.

Package visor pkg/visor/api_skynet.go c3-vis-core

Package visor pkg/visor/api_state.go c3-vis-core

Package visor pkg/visor/api_state_diag.go c3-vis-api

The `diag` section of `visor state`: the in-process plumbing — router intake, transport read queue and per-transport handlers/pong health, VStream muxes, dmsg session ping health and relay state, Go runtime — that until now could only be inferred from logs. Every value is a cheap read of live counters; the section is built for the default snapshot.

Package visor pkg/visor/api_state_roles.go c3-vis-api

The `roles` section of `visor state`: what this visor is FOR the rest of the network, as opposed to what it is doing for itself. Three answers an operator used to have to assemble from `mdisc entry`, `ss` on the host and the logs:

• dmsg SERVER — is one running in-process, under which key, on which address, and is it sharing the visor's transport TCP port (#4785/#4787) or bound to one of its own. An own-key server registers in the SAME discovery entry as the visor's client; a config_path server is the standalone dmsg-server service folded into this process on its OWN key.
• dmsg RELAY, both directions (#4789/#4790/#4791) — the peers this visor nominated as its relays and which of them it is actually attached to (with the carrier), plus the peers attached TO this visor and the streams it is carrying for them against the configured slot cap.
• TRANSIT — whether this visor refuses to be an intermediate route hop (routing.no_transit, #4788).

Everything here is a cheap read of live counters and config, so the section is part of the default snapshot and is selectable on its own.

Package visor pkg/visor/api_suspend.go

Package visor pkg/visor/api_tpd_metrics_subscriber.go c3-vis-core

Reader-side helper for TPD's network-wide transport metrics feed. The CXO subscription lives in the unified CXOSubscriptionManager (see cxo_subscription_manager.go); this file is a thin facade that AcquireFor's the relevant tab and serves the cached blob.

TPD publishes one leaf per calendar day at "metrics/day/<YYYY-MM-DD>", so a day window is assembled HERE from the N newest leaves — see the pivot/merge pair in pkg/deployment/tpd/store/cxo_metrics_layout.go. Callers still get the single JSON array of store.TransportMetric they always got.

The reader also still understands the previous layout, one leaf per window at "metrics/days/<n>". TPD and visors update independently from the same develop-latest binary on a ~5 minute timer, so a new visor talking to a not-yet-updated TPD is a real state, and it is one visor-side branch rather than a second set of leaves TPD would have to keep publishing.

Pre-task-#134 this file owned its own standalone Subscriber that bound DmsgTPDMetricsCXOPort directly. That subscriber raced with the unified manager for the same DMSG port, causing one of them to fail with "dmsg listen on port 51: port already occupied". The duplication is gone now — there's a single subscriber per CXO port, owned by the manager.

Package visor pkg/visor/api_tpd_perkey_subscriber.go c3-vis-core

Reader-side helper for TPD's per-key feed (perkey/stats): every visor's transports counted by type. The publisher lives in pkg/deployment/tpd/api/cxo_perkey_publisher.go. Served in the exact shape of GET /all-transports/per-key-stats, so a caller of that endpoint takes the feed in its place without knowing which one answered.

Package visor pkg/visor/api_tpd_stats_subscriber.go c3-vis-core

Reader-side helper for TPD's network-aggregate stats feed. The publisher lives in pkg/deployment/tpd/api/cxo_stats_publisher.go and writes three gzipped leaves:

stats/network   the GET /all-transports/stats shape
stats/versions  the GET /version fleet histogram
stats/daily     the GET /metric daily aggregate (~2.7 KB)

Both carry a completeness stamp (observed_at / complete / confidence / trailing peak) that the reader passes through untouched — deciding whether a partial sample is usable is the consumer's call, not the visor's, and stripping the stamp here would recreate exactly the blind spot skycoin/skywire#4513 describes.

The subscription itself lives in the unified CXOSubscriptionManager; this is a thin facade that AcquireFor's TabNetworkStats and serves the cached blob.

Package visor pkg/visor/api_tpd_uptime_subscriber.go c3-vis-core

Reader-side helper for TPD's network-wide visor-uptime feed. The CXO subscription lives in the unified CXOSubscriptionManager (see cxo_subscription_manager.go); this file is a thin facade that AcquireFor's the relevant tab and serves the cached blob.

Pre-task-#134 this file owned its own standalone Subscriber that bound DmsgTPDUptimeCXOPort directly. That subscriber raced with the unified manager for the same DMSG port, causing one of them to fail with "dmsg listen on port 52: port already occupied". The duplication is gone now — there's a single subscriber per CXO port, owned by the manager.

Package visor pkg/visor/api_tps.go c3-vis-core api_tps.go contains embedded Transport Setup Node (TPS) API methods.

Package visor pkg/visor/api_transport.go c3-vis-core api_transport.go contains transport management API methods.

Package visor pkg/visor/api_visor.go c3-vis-core api_visor.go contains visor lifecycle and status API methods.

Package visor pkg/visor/api_visor_cat.go c3-vis-core

VisorCat bridges a remote dmsg / skynet stream to a 127.0.0.1 loopback TCP listener inside the visor process. The CLI dials that loopback and the visor splices the two halves bidirectionally so stdio on the CLI side flows to/from the remote peer without the bytes ever crossing the local RPC channel.

Two modes:

• dial: the visor opens the outbound stream and waits for the CLI to dial the returned loopback. Useful for the `cli dmsg cat <pk>:<port>` client.
• listen: the visor binds a one-shot listener on the requested remote port (dmsg + skynet mirror), accepts the first inbound stream, authorizes the peer PK against the dmsgscp whitelist, and splices it to a loopback the CLI dials. Used by `cli dmsg cat listen <port>`.

Listener concurrency is one-shot by design — accepting a second stream into the same stdout would interleave bytes meaninglessly. A persistent server would need its own protocol; we don't have one.

Package visor pkg/visor/api_visor_scp.go c3-vis-core

VisorSCP performs a dmsgscp-protocol file transfer from inside the visor process. The visor has both transports plumbed (dmsg.Client + appnet SkywireNetworker), where a standalone CLI has only the dmsg path. Routing the SCP through the visor lets callers pick either transport without bolting an appnet shim onto the CLI.

Lives in its own file so the dmsgscp / appnet imports stay scoped to one compilation unit.

Package visor pkg/visor/ar_reach_decl.go c3-vis-core

The visor's reachability declaration: the "reach" leaf of its AR-bind feed, which the address resolver folds into its reach feed (see pkg/deployment/ar/arfeed/reach.go). It states what the visor alone can know: its STUN-measured NAT class, which types it serves inbound, and when it last accepted an inbound transport of each.

It is rebuilt on a timer and Put only when its bytes change. Inbound times are rounded to an hour, so a visor accepting transports all day rewrites the leaf at most hourly; between changes the feed heartbeat carries it unchanged.

Package visor pkg/visor/ar_resolve_cxo.go

Address lookups from the address resolver's bindings feed. The visor holds the feed (about 100 KB for the whole network) and answers stcpr, squicr and swtr lookups from it, in microseconds and with no request to the resolver, where GET /resolve costs an authenticated round trip of about 140 ms (measured in pkg/deployment/ar/arpreview).

A miss of any kind falls through to GET /resolve, which stays the authority. The feed trails the resolver's store by its publish window, so an answer may be an address the peer has just left. A peer and type are therefore answered from the feed at most once per fastResolveRepeatAfter: a second lookup inside that window, which usually follows a failed dial, goes to the resolver.

Package visor pkg/visor/autoconnect.go c3-vis-core

Package visor pkg/visor/autoconnect_reach.go c3-vis-core

Autoconnect picks its peers from the address resolver's reach feed: per peer and per transport type, whether a transport is known to work, should work, is untested, or is known to fail (arfeed.Reach.Verdict). Known failures are never dialed; confirmed peers are dialed first; untested ones — visors too old to state anything, bindings not yet probed — get a few dials per cycle so they are not starved, but no more.

Package visor pkg/visor/autotp_cooldown.go

Package visor pkg/visor/browseorigins.go Untagged, dependency-free string work, so the rule it encodes is covered by a test that runs in CI: which app origins a browse origin will accept content from. Getting it wrong does not fail loudly — the browse frame just waits on its interstitial until the handshake times out.

Package visor pkg/visor/conf_cxo.go c3-vis-core

The visor's subscription to the conf service's services feed (published by pkg/deployment/conf/api/cxo_publisher.go on DmsgConfCXOPort). The feed is the deployment's current services config, signed by the conf service's key; when it changes, the new config is applied the same way the hourly dmsg-HTTP refresh applies it (applyDeploymentServices), so the deployment can change its service keys without a release.

The subscription is held, not cycled: the document changes rarely, and the publisher's heartbeat (every 45s) keeps the one connection warm, so a change arrives within the publisher's interval at the cost of no new handshakes. The subscriber's own watchdog re-dials if that heartbeat stops. Until the first connect succeeds, startConfCXOSubscriber retries with backoff; the watchdog only takes over after one.

Package visor pkg/visor/config_refresh.go c3-vis-core

Package visor pkg/visor/csrf.go c3-vis-core

Package visor pkg/visor/cxo_feed_allowlist.go c3-vis-core

Subscriber-allowlist gating for the visor's service-consumed CXO feeds (telemetry stats, tp-list, dmsg-discovery registration). These feeds were historically PUBLIC — a nil SubscriberAllowlist accepts any subscriber, so any peer could subscribe and read the visor's full transport set, undermining the transport-setup-node-mediated access model. This module composes each feed's allowlist and keeps it in sync with the live peer whitelist.

The composed set for a feed is:

v.peerWhitelist  (configured Hypervisors + Pty.Whitelist + own PK)
  ∪ {that feed's consuming-service PK}  (TPD for stats/tp-list,
                                          dmsg-discovery for registration)

The consuming-service PK MUST be present or gating breaks that service: the OnSubscribeRemote hook fires even for the consumer over the visor-initiated announce conn (the check keys off c.PeerID()).

Guard: if BOTH the peer whitelist is empty AND the consumer PK is unknown, the feed is left OPEN (nil allowlist) rather than gated to an empty set that would lock everyone out. When the consumer PK IS known it is always included, even when the peer whitelist is otherwise empty.

Package visor pkg/visor/cxo_subscription_manager.go c3-vis-core

Thin visor-side shim over the reusable pkg/cxo/cxosub cycle-based CXO sync manager. The implementation lives in cxosub, decoupled from *Visor via cxosub.Deps; this file only:

• re-exports the cxosub types/consts under their historical visor names (CXOFeed, CXOTab, CXOSubscriptionManager, the FeedXxx/TabXxx consts, FeedStatus) so existing callers compile unchanged, and
• supplies the visor's dependency wiring: the live dmsg client accessor and the feed → (peerPK, port, prefix) resolver that reads service publisher PKs out of the visor config.

The manager's cycle semantics are documented in the cxosub package.

Package visor pkg/visor/cxo_transport_discovery.go c3-vis-core

CXO-aware wrapper around the visor's transport.DiscoveryClient. The only override is GetAllTransports — the network-wide snapshot used by calculateLocalRoutes, autoconnect, the hypervisor's calc tools, and a few RPC paths. Every other DiscoveryClient call (per-edge lookups, registrations, deletes) keeps going to HTTP because the CXO publisher doesn't carry that fan-out and a stale single-edge answer can produce route-setup failures that don't self-correct.

The CXO snapshot is refreshed on the manager's 5min cycle while the feed is held; for read-heavy paths (mux-bw probes, hvui Transports tab, route calc on every Dial) that's tighter than the per-call HTTP fetch was. AcquireFor on each call keeps the cycle alive across bursts via cxoTabCloseGrace.

Package visor pkg/visor/cxo_user_feeds.go c3-vis-core

CXO user-feed registry. Each visor publishes one always-on system feed (the telemetry feed wired up by initStats on skyenv.DmsgCXOPort) and any number of user feeds — distinct CXO TreeStore publishers running on distinct DMSG ports under the visor's PK. Subscribers discover them via the dmsghttp logserver's /feeds endpoint, then connect their CXO subscriber to (visor PK, feed.DmsgPort) directly.

The system feed is reserved at skyenv.DmsgCXOPort. User feeds must pick a different port; collisions with system DMSG ports listed in pkg/skyenv (hypervisor=46, transport-setup=47, http=80, dht=100, etc.) are rejected at registration so a user feed can't shadow a reserved listener.

Package visor pkg/visor/dmsg_lookup_cxo.go c3-vis-core

dmsg-entry LOOKUP over CXO — the consumer/resolver shim that lets a visor's dmsg client resolve a peer's discovery entry from the local CXO clients-by-server snapshot instead of a fresh HTTP-over-dmsg Noise handshake to dmsg-discovery (profiled 76% CPU in handshake crypto). The publish side is dmsg-discovery's ClientsByServerCXOPublisher (DmsgDMSGDClientsByServerCXOPort, 54), which mirrors every client's signed dmsgdisc.Entry into a TreeStore feed under clients-by-server/<server>/<client>/entry. The visor already ingests that feed for the hypervisor's network visualizer; this reuses the same cxosub-managed snapshot as a resolution path.

Wiring: init_dmsg installs the resolver returned here into the dmsg client's discovery client (disc.NewCXOEntryClient), where it fronts the existing HTTP/direct chain for Entry() only. On a hit the peer entry is served with no network round-trip; on ANY miss the wrapped client resolves it over HTTP — "not in my CXO tree" is never "doesn't exist" (see the deployment-services-over-CXO roadmap's back-compat rules).

Provenance: the snapshot comes from exactly one authoritative publisher — the configured dmsg-discovery PK (cxoFeedSpec resolves FeedDMSGDClientsByServer to dmsgdCXOPeer). There is no per-record reporter to police here: dmsg-discovery is the single signer of every entry in the feed, so the feed-PK gate already enforces provenance. The snapshot's own bodies are dmsg-disc-signed dmsgdisc.Entry values.

Lifecycle: cxosub runs the feed as a periodic subscribe → snapshot → unsubscribe cycle (no long-lived subscription), so the orphan- feed reclaim the roadmap calls for is handled by the manager — the visor holds no unbounded CXDS here.

SecKey binding: the cxosub manager subscribes over the visor's single dmsg client (v.dmsgC, keyed to the visor SecKey); there is no second dmsg client and no zero/random keypair (see feedback_never_two_dmsg_clients_same_key).

Package visor pkg/visor/dmsg_over_skynet.go c3-vis-core

"dmsg over skynet transports": serve a .dmsg fetch by reaching the peer's :80 over a skynet transport via the VStreamMux relay (direct → 1-hop relay, route ID 0, PK-addressed, NO route-finder), with dmsg-servers as the only fallback. dmsg is a relay layer — this path never uses a route.

Package visor pkg/visor/dmsg_rpc_transport_oracle.go c3-vis-core

A destination-transport oracle that sources a peer's OWN transports over the always-on visor RPC (skyenv.DmsgVisorRPCPort), plus a composite that layers the general RSN-signed oracle over it. Feeds the RSN-oracle 2-hop route computation (pkg/router/rsn_oracle_routes.go) so the adaptive mux can find disjoint intermediates WITHOUT depending on TPD's (chronically under-filled) view of a busy exit's transports.

Package visor pkg/visor/dmsg_servers_cache.go c3-vis-core

DmsgServersCache persists dmsg-server discovery entries (the "static" PK plus the live `server.address` and metadata) to a JSON file in the visor's local_path. Its purpose is to remember the addresses learned from dmsg-discovery across visor restarts so the bootstrap direct client doesn't have to start from the addresses frozen into skywire.json (which can be months stale).

Read order at startup:

1. cache file (`<local_path>/dmsg_servers.json`)
2. main config (`v.conf.Dmsg.Servers` — typically /opt/skywire/skywire.json)

The two are merged: for any PK present in the cache, the cached entry wins; PKs only in the config are kept; PKs only in the cache are also included. This way a server that has rotated its address is reached via the new address without losing PKs the cache hasn't seen yet.

Write trigger: a background loop in initDmsg refreshes the cache from dmsg-discovery once dmsgC is connected, then on a fixed interval. If dmsgd is unreachable, the previous cache contents are kept (no destructive write on transient errors).

Package visor pkg/visor/dmsg_servers_cxo.go

The registered dmsg servers from dmsg discovery's clients-by-server feed, which the visor already holds for its entry lookups. The server cache refreshes from this snapshot and asks dmsg discovery over HTTP only when the feed carries no servers, as a publisher older than the server leaves does.

Package visor pkg/visor/dual_listen.go c3-vis-core

Parity helpers: every port the visor binds on dmsg is also bound on the skywire router (appnet.TypeSkynet) at the same port number. The dmsg listener provides the bootstrap path (works before the router has any transports up); the skynet mirror provides the steady-state path that flows over arbitrary transports (dmsg / stcpr / sudph / etc.) negotiated by the router.

Usage shape across the visor:

dmsgLis, err := v.dmsgC.Listen(port)
if err != nil { return err }
// ... start the dmsg accept loop / server / ServeListener ...
goServeSkynetMirror(ctx, v.conf.PK, port, "label", log,
    func(skyLis net.Listener) {
        // run the same accept logic / server.Serve() on skyLis
    })

Bootstrap order: the skynet networker (appnet.TypeSkynet) is registered during initRouter, which may run *after* this helper is invoked from earlier init steps. The mirror goroutine polls for the networker to register, with exponential backoff capped at 5s, then binds the listener and runs serve. If the context is canceled before the networker shows up, the goroutine exits without binding.

Address-type agnosticism: existing dmsg handlers commonly cast conn.RemoteAddr() to dmsg.Addr to extract the peer PK. Mirrors must use remotePK() instead, which handles both dmsg.Addr and appnet.Addr shapes.

Package visor pkg/visor/embedded_dmsgweb.go c3-vis-core

EmbeddedDmsgWeb is the in-process version of the `skywire dmsg web` utility. It runs a localhost SOCKS5 proxy + HTTP bridge that resolves `.dmsg` (or a configured domain suffix) hostnames by tunneling requests through the visor's own dmsg client.

Why in-process rather than a separate app: running standalone requires spinning up a second dmsg identity with its own sessions, doubling server load for the same PK's worth of connectivity. By sharing the visor's client the resolver piggybacks on sessions that already exist for routing / health / transport probes. This mirrors the setup-node sharing pattern (see embedded_route_setup.go).

Runtime supervision (Start/Stop) is local to this type so the RPC layer can flip resolvers on and off without restarting the visor. Stats live on the struct (not inside pkg/dmsgweb) so counters survive Start→Stop→Start cycles.

Package visor pkg/visor/embedded_proxystatus.go c3-vis-core

visorStatusProvider implements pkg/proxystatus.Provider on top of the visor's existing read APIs, so the resolving proxies (dmsg_web / skynet_web) can serve each surface's reserved in-process status host (http://status.<surface>/).

It is deliberately READ-ONLY and reuses APIs that already exist:

• logs: Visor.LogsSince(app) — the app's bbolt log store tail
• mux: Visor.RouteGroupMuxInfo(app) — the same per-leg telemetry the `cli proxy mux plot` renderer consumes
• running: procManager.ProcByName(app)

Route CONTROL is intentionally out of scope for the MVP; the extension seam lives in pkg/proxystatus (Snapshot doc + the disabled control section). When it lands, a mutating method is added to proxystatus.Provider and implemented here on top of the visor's existing mux-reshape API (AddMuxRoute / RemoveMuxRoute / SetMuxMode), which already exists — no new plumbing.

Package visor pkg/visor/embedded_proxystatus_skywire.go c3-vis-core

The skywire status surface: every app and visor subsystem that holds a route group or a direct stream, each drawn with the same tunnel model as the proxy surfaces.

Package visor pkg/visor/embedded_resolver_local.go c3-vis-core

Publishing a resolving proxy as a LOCAL SERVICE: an app on this visor dials the visor's own PK on the resolver's port and is served in-process over net.Pipe, with no second SOCKS hop on 127.0.0.1 and no port to configure on both sides. See pkg/app/appnet/local_service.go for the table itself.

The port is the resolver's own SOCKS5 port (4445, 4446, …), read as a routing port. Routing ports are a separate space from TCP ports, so there is no collision, and an app that knows which resolver it wants already knows the number. Two resolvers cannot share one, because ValidateResolvers already refuses a duplicate listener port.

A local service is NOT in pkg/visor's ServiceRegistry, which is what handleServerConn dispatches incoming PEER connections from. That distinction is the whole point: a resolver answers for this visor's alias table, mints leaves from its MITM CA and leaves through its exit, so only this visor's own apps may reach it.

Package visor pkg/visor/embedded_resolver_tls.go c3-vis-core

Helpers shared by EmbeddedDmsgWeb and EmbeddedSkynetWeb to wire optional TLS MITM mode onto their underlying runtime configs.

Trust model and threat analysis live in pkg/skynetca; the helpers here only handle the visor-side bookkeeping: load the CA from the configured paths, build a LeafMinter, mutate the runtime config. All errors are non-fatal — when CA load fails the resolver continues to run in non-MITM mode and the caller logs the reason.

Package visor pkg/visor/embedded_resolvers.go c3-vis-core

initEmbeddedResolvers brings up the ADDITIONAL resolving proxies declared by the `resolvers` config list — the ones beyond the dmsg_web / skynet_web primaries that embedded_dmsgweb.go and embedded_skynetweb.go own.

There is no new runtime here. Each entry is projected onto the same DmsgWebConfig / SkynetWebConfig the primaries use and handed to the same EmbeddedDmsgWeb / EmbeddedSkynetWeb type, so an extra resolver is not a second implementation that can drift from the first — it is another instance of the one that already works, with a different listener and, for a dmsg resolver, optionally a different identity.

What IS new is the failure this file has to avoid. The primaries could not collide with each other (4445 vs 4446, fixed), so nothing ever checked. With N resolvers the operator picks the ports, and two SOCKS5 listeners on one port do not both fail loudly: the first binds, the second's Run loop returns "address already in use" into a log line, and the app row still says running. So the port map is validated before anything is constructed, and a resolver that loses a conflict is not constructed at all — with an ERROR naming both claimants.

Package visor pkg/visor/embedded_route_setup.go c3-vis-core

Package visor pkg/visor/embedded_services_cxo.go c3-vis-core

The visor as CXO host for the services it embeds. Visors publish their registration and telemetry feeds on fixed DMSG ports and a service aggregates each feed on the same port, dialing visors back there. A visor that embeds the service holds both ends under one key, and a port takes one listener, so the service's aggregator runs on the visor's own publisher node for that port. The visor's own feed on that node never arrives from a peer, so each Root it publishes is handed to the aggregator in-process.

Package visor pkg/visor/embedded_skymail_bridge.go c3-vis-core

EmbeddedSkymailBridge wraps the pkg/skymailbridge SMTP server so it can be hosted directly inside the visor process — the SMTP-side analog of EmbeddedDmsgWeb / EmbeddedSkynetWeb. The bridge accepts inbound SMTP from a co-located Postfix's transport_map, parses the recipient envelope, and dials peers over the visor's existing dmsg client. No separate app, no second dmsg identity.

Lifecycle mirrors the resolvers exactly: idempotent Start/Stop, running flag, runtime toggle via RPC (SetEmbeddedProxyEnabled("bridge", …)). Standalone deployments (hosts without a full visor) should use cmd/smb instead.

Package visor pkg/visor/embedded_skynetweb.go c3-vis-core

EmbeddedSkynetWeb hosts the `.skynet` resolving proxy inside the visor. Mirrors EmbeddedDmsgWeb's lifecycle (Start/Stop + Stats) but speaks the skynet protocol (route + handshake) instead of DMSG.

Skynet dialing requires establishing a route group — a router-internal operation. This file defines the adapter (routerSkynetDialer) that implements pkg/skynetweb.SkynetDialer on top of router.Router.

Package visor pkg/visor/embedded_tps.go c3-vis-core

Package visor pkg/visor/embedded_wisp.go c3-vis-core

EmbeddedWisp is the in-process Wisp server: the same protocol `skywire cli wisp serve` speaks, bound to the page's virtual loopback instead of an HTTP port.

Why in-process and why vnet. A browser-side Linux guest gets its network by asking a Wisp backend to open connections by name, and the backends such a page normally uses are one central WebSocket somewhere. A visor running in the same tab can be that backend instead, which puts the guest's traffic on a route to a skywire exit. Two things force the shape:

• websocket.Accept is //go:build !js, so a WebSocket server cannot exist in a tab at all;
• a service worker cannot intercept ws:// or wss://, so a page-served WebSocket endpoint could not be reached even if one existed.

So the session is framed over a plain conn (wisp.Server.ServeConn) and carried on a vnet port, which page JS reaches with vnet.dial(port). Only a browser-tab visor runs it (initEmbeddedWisp). Natively bottle's vnet is net, which is how the tests bind ordinary loopback and reach it with `wisp.DialConn`.

Egress is the visor's own skysocks-client. Reaching it needs bottle's vnet as the forward dialer: in a tab the proxy's port lives in the page's port table, which net.Dial knows nothing about.

Package visor pkg/visor/execwasm_serve.go c3-vis-api

Package visor pkg/visor/fetchdest.go c3-vis-core

Package visor pkg/visor/flightrec.go c3-vis-core

Package visor pkg/visor/forward_proxy.go c3-vis-core

Package visor pkg/visor/forwarded_ports.go c3-vis-core

ForwardedPorts manages the set of ports that are accessible over skynet and/or DMSG, with per-port metadata (label, description, visibility on the landing page, PK whitelist).

Package visor pkg/visor/gctune_native.go c3-vis-core

Package visor pkg/visor/geo_summary.go c3-vis-core

Package visor pkg/visor/group.go c3-vis-core

Visor-level wrapper around the cmd/apps/skychat/group package. Mirrors pkg/visor/pairing.go in shape: owns one group.Manager (initialized in init_group.go) plus an in-memory ring of recently received messages. RPC clients call GroupCreate / GroupJoin / GroupList / GroupSend / GroupPoll / GroupDelete / GroupLeave; the poll model is the same as PairPoll, so apps that already drain a pair-poll loop can layer on a group-poll loop with the same shape.

Scope (v1, D1 owner-centric):

• Owners can create groups, invite via link, broadcast messages.
• Members can join via invite, read messages, leave.
• Member-side "send" is NOT in v1. Members read only; the owner drives the conversation. Phase-2 (project memo group-chat plan) adds member-side relay via the existing pair-message wire with a group_id tag.

Package visor pkg/visor/gui.go c3-vis-core

Package visor pkg/visor/gui_linux.go c3-vis-core

Package visor pkg/visor/gui_unix.go c3-vis-core

Package visor pkg/visor/helpers.go c3-vis-core Common helper functions to reduce code duplication across the visor package.

Package visor pkg/visor/hostbridge.go c3-vis-wasm

Package visor pkg/visor/hostbridge_dial.go c3-vis-wasm

Package visor pkg/visor/hostbridge_probe_other.go c3-vis-wasm

Package visor pkg/visor/hostbridge_sockets.go c3-vis-wasm

Package visor pkg/visor/hypervisor.go c3-vis-core

Package visor pkg/visor/hypervisor_attached_graph.go c3-vis-api

The hypervisor's attached visors report their transports in the Summary it polls every hypervisorBackgroundPollInterval. AttachedTransportEntries turns that cache into transport entries, so route calculation on the hypervisor's own visor can use those edges without a TPD or route-finder query (#4750).

Package visor pkg/visor/hypervisor_dmsg_ingest.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_admin.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_apps.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_browse.go c3-vis-core The native hypervisor's web surfaces: the Angular dashboard (index.html with its version stamp) and the desk on its own listener, whose browser reaches the mesh and the clearnet through /api/browse* on this visor.

Package visor pkg/visor/hypervisor_handlers_clientlog.go c3-vis-core browser-side error reports from the hypervisor UI.

The hvui installs a global error reporter (a window.onerror / unhandledrejection hook + an Angular ErrorHandler + a console.error/ warn wrapper) that POSTs each client-side error here. The handler writes them to the visor log under the "hvui_client" logger, so an operator debugging a broken UI page (a dead tab, a failed XHR, a thrown change-detection error) can read the browser's errors right in `./local/log/skywire.log` instead of copy-pasting the dev-tools console.

It's intentionally unauthenticated — a broken page (or one that crashes before login) must still be able to report — so it is hardened against abuse of an open log sink: the request body is size-capped, reports are rate-limited, and every field is sanitized (control chars stripped) to prevent log-injection of forged lines.

Package visor pkg/visor/hypervisor_handlers_ctx.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_disc_proxy.go c3-vis-core

Hypervisor-hosted dmsg-discovery proxy.

Visors configured with the hypervisor's HTTP address as their dmsg discovery URL hit these routes. For Entry GETs we check the embedded dmsg server's active client sessions first and synthesize a minimal entry (`DelegatedServers: [H]`) when the requested PK is locally connected; that lets sibling visors dial each other through the hypervisor's relay even when public dmsg-discovery is unreachable. Anything else falls through to the upstream public discovery via a reverse proxy — POSTs (entry registration) included, so non-sibling peers continue to find these visors via the canonical discovery.

`/dmsg-discovery/local/...` mirrors the local-only view for operator inspection (UI / CLI), without the upstream fall-through.

Package visor pkg/visor/hypervisor_handlers_dmsg.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_group.go c3-vis-core

Hypervisor HTTP routes for skychat GROUP chat — the native-visor counterpart to the wasm visor's skychatGroup* JS hooks. These thin handlers bridge the hvui's group panel to the local visor's group RPC surface (ctx.API.Group*), so the same Angular UI drives group chat on a native visor (over HTTP here) and on a wasm visor (over the in-process JS hooks) with no divergence.

Scope: the LOCAL visor only (hv.visorCtx), matching the skychat password + proxy handlers. The group manager runs in the visor process (init_group.go); ctx.API resolves to it. Remote managed visors are out of scope here (a follow-up, same as skychatProxy).

Package visor pkg/visor/hypervisor_handlers_health.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_log.go c3-vis-core Events stream of the local visor's live log, so the HV-UI log window can show the NATIVE visor's server-side log (the wasm visor logs to the browser console and is captured there directly; the native visor's log lives server-side).

Package visor pkg/visor/hypervisor_handlers_mail.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_misc.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_notify.go c3-vis-core

The host-app sink of the notification hub (tier (b), see notifyhub.go): an SSE stream of the notifications apps publish, for a host application that can surface them natively — the Android foreground service posting through per-app notification channels, and later the manager UI's notification bell.

Live-only, no replay: a subscriber sees what arrives while it is connected and nothing else. A reconnecting phone getting a burst of stale "you had a message" toasts is worse than missing them, and the hub's whole contract is best-effort delivery to whoever is listening now.

While at least one subscriber is connected the hub stops posting to the host OS, so a desktop running the Android-style host app doesn't double up. That is derived per publish from the live subscriber set — never cached — so a dropped connection restores the desktop path immediately.

Package visor pkg/visor/hypervisor_handlers_pair.go c3-vis-api

Pre-auth pairing endpoints (#4484 stage 5). A desk tab this hypervisor serves has no session yet; it learns its own standing from GET /pair/status and, as the fallback to `skywire cli visor hv pair`, redeems a one-time code the operator made on the board with POST /pair. Both sit beside /tp/ws, outside the session-auth group; the code is the credential, single-use and revoked after a few wrong attempts.

Package visor pkg/visor/hypervisor_handlers_proxies.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_reachability.go c3-vis-core

HTTP handlers for the per-visor Reachability tab: skywire-route ping (DialPing + Ping + StopPing), dmsg ping (DialDmsgPing + DmsgPing + StopDmsgPing), and a remote /health fetch over dmsg. All three wrap RPC methods that already exist on Visor; this file just exposes them to the UI's HTTP API.

Package visor pkg/visor/hypervisor_handlers_router.go c3-vis-core

Hypervisor HTTP handlers for the unified visor-wide router-knobs resource at GET/PUT /visors/{pk}/router-settings. Backs the hypervisor UI's "Router Settings" panel which gives operators the same knobs the CLI exposes via 'cli proxy start --xxx' (force_local_routes, existing_tp_only, mux_routes, min_hops).

Package visor pkg/visor/hypervisor_handlers_routes.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_routing_tools.go c3-vis-core

HTTP handlers powering the Routing tab's Find + Calculate forms. route-find queries the route-finder service via the visor's configured rfClient. route-calc enumerates routes locally using the same graph machinery the gRPC StreamCalcRoutes uses, but in a bounded-count one-shot form so it fits a JSON HTTP response.

Package visor pkg/visor/hypervisor_handlers_rsn.go c3-vis-core

Per-RSN remote stats fetch for the hvui's Services Health page. Mirrors `skywire-cli route rsn-remote-stats` — for every RSN PK in EffectiveRouteSetupNodes the local visor's DmsgHTTP RPC is used to GET dmsg://<pk>:80/stats, the response is parsed back into a StatsSnapshot and the array is returned to the UI.

Package visor pkg/visor/hypervisor_handlers_skychat.go c3-vis-core

Hypervisor HTTP routes for skychat: password get/set/clear and a reverse proxy to the local skychat HTTP server. The proxy is what backs the hvui's "Chat" tab — the browser talks to the hypervisor (already authenticated), the hypervisor adds the internal-token header and forwards to localhost:<skychat-port>.

Package visor pkg/visor/hypervisor_handlers_skyenv.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_skynet.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_tpd.go c3-vis-core

Network-wide transport metrics proxy for the hvui's Transports home tab. Three fetch strategies are tried in order:

1. CXO subscriber (instant when fresh) — the visor maintains a long-lived TreeStore subscriber to TPD's metrics-aggregate publisher (see api_tpd_metrics_subscriber.go). When the publisher has pushed a Root for the requested day window the subscriber's local cache returns it immediately, no DMSG round-trip per hvui open.
2. DMSG-HTTP — bypass the CXO path and ask TPD for /metrics over dmsghttp through the visor's existing DmsgHTTP RPC.
3. Plain HTTP fallback — last resort when DMSG isn't ready / TPD doesn't publish a DMSG address.

The first strategy that returns 2xx wins; later strategies aren't tried unless the earlier one explicitly missed.

Package visor pkg/visor/hypervisor_handlers_tpd_reduce.go c3-vis-core

Folding TPD's /metrics payload down to what the hvui Transports tab can actually render.

TPD returns one record per transport for the whole mesh, with a daily bandwidth array per record. On the production deployment that is upwards of 180,000 records and over 60 MB of JSON — measured 2026-09-28, and still growing. Proxying it verbatim broke in three places at once:

• the upstream body was cut off mid-record at ~30s, so the client received HTTP 200 and unparseable JSON;
• 60 MB exceeded the hypervisor's own 10s WriteTimeout, so the browser got ERR_EMPTY_RESPONSE and the page never loaded at all;
• and had it arrived, the Angular table renders every row it is given, which wedged the browser's main thread for minutes.

The client only ever displayed a fold of each record — two bandwidth totals from the daily array — sorted by bandwidth, so that fold happens here now. The response carries the full total alongside the capped rows, so the UI can say what it is not showing rather than quietly lying about the size of the mesh.

Package visor pkg/visor/hypervisor_handlers_transports.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_visors.go c3-vis-core

Package visor pkg/visor/hypervisor_handlers_voice.go c3-vis-core

Hypervisor HTTP routes for skychat VOICE calls — the native-visor counterpart to the wasm visor's skychatVoice* JS hooks. These thin handlers bridge the hvui skychat panel to the local visor's voice surface (ctx.API.Voice*), so the SAME Angular UI drives voice on a native visor (over HTTP here) and on a wasm visor (over the in-process JS hooks) with no divergence — mirroring the group + proxy handlers.

Scope: the LOCAL visor only (hv.visorCtx), matching the skychat password + proxy + group handlers. Voice is disabled (ctx.API returns ErrVoiceDisabled) unless the visor was built/started with voice; that surfaces here as 503 so the UI can hide the controls.

Package visor pkg/visor/hypervisor_handlers_voice_audio.go c3-vis-core

The two routes that carry a call's AUDIO between the visor and the app that started it, for a visor whose audio device belongs to that app rather than to itself — Android, where nothing else can work (see pkg/skychat/call/bridge.go and voiceAudioMode in init_voice.go).

POST /skychat/voice/mic      the app's microphone, streamed in
GET  /skychat/voice/speaker  what the calls want played, streamed out

Both carry RAW little-endian int16 PCM, mono, at call.SampleRate — no framing, no JSON, no base64. A voice stream is a continuous 96 KB/s in each direction and every wrapper here would be paid 50 times a second for nothing; the format is fixed on both sides at compile time, so there is nothing to negotiate. The one real cost of that choice is that a wrong sample rate is silent corruption rather than an error, which is why the constant is exported for the app to build its capture and playback from.

**Long-lived, and deliberately so.** A call is minutes; a request per frame would be 50 round trips a second in each direction. Each stream instead re-arms its own deadline as it goes, exactly as the notification SSE stream does — the server's 5 s read / 10 s write timeouts are single deadlines for a whole request, and clearing them outright would leave a wedged peer parked in a syscall forever holding the device.

LOCAL visor only. The bridge is this process's audio device; proxying it to a remote visor would mean shipping someone else's microphone across the mesh through the operator's browser, which is not a thing this route offers.

Package visor pkg/visor/hypervisor_handlers_wallet.go c3-vis-core wallet ("wallet HV-served" mode, docs/design/gui-app-serving-modes.md).

The wallet is the dashboard's #/wallet page: skycoin-web's wallet module compiled into the dashboard, its crypto client-side in skycoin's TinyGo cipher, its wallets in browser storage. The hypervisor serves that cipher and proxies the wallet's node API (wallet/coins, wallet/coin/<index>/…) to the configured backend over the visor's dmsg client: NO skycoin-web process, NO listening port. The same handlers run in the tab's wasm hypervisor, so native == wasm.

When the skycoin-web app runs in this process, wallet/coins and wallet/coin/<index>/… go to it instead, so the same page uses its node settings and its server-side wallet files.

Package visor pkg/visor/hypervisor_hostbridge.go c3-vis-wasm

Package visor pkg/visor/hypervisor_tpviz.go c3-vis-core

Package visor pkg/visor/hypervisor_ws.go c3-vis-core

/ws — the hypervisor API as a message transport.

The Angular UI already routes /api through one seam (SkywireHttpBackend, "the bottom of the Angular HttpClient pipeline"), which today has four backends: same-origin XHR for a visor-served build, a function call into an in-tab wasm visor, a dmsg call for the standalone hypervisor, and dmsg frames to a remote PK. Three of those are message-oriented; the native one is the odd one out, and that asymmetry is what stops the two UI variants converging on a single transport.

This endpoint closes that gap WITHOUT a second API. A frame names a method, a path and a body; the handler replays it through the hypervisor's OWN router, so every route, middleware, permission check and response is byte-identical to the HTTP call it stands in for. There is exactly one implementation of the API — this is a transport, not a parallel surface.

It is deliberately mounted OUTSIDE the /api group: that group's 30s Timeout would kill a long-lived socket. /pty sits outside for the same reason and opts into auth explicitly; this follows it.

Wire format is JSON text frames. `type` is carried from the first version so server-push ("type":"event") can be added later without breaking the request/response contract.

client → server  {"type":"req","id":7,"method":"GET","path":"/api/about","body":null,"headers":{}}
server → client  {"type":"res","id":7,"status":200,"body":"{...}","headers":{"Content-Type":"application/json"}}

Bodies are strings, not base64: the hypervisor API is JSON in and JSON out, and the UI's gateway contract already decodes a text body.

wsReadLimit bounds what a client may SEND; responses are not capped, and some are large — /api/visors-tree-summary is 8.6 MB on a fleet of nine visors, over plain HTTP as much as here. A browser's WebSocket has no read limit so the UI is unaffected, but a Go client must raise coder/websocket's 32 KiB default (SetReadLimit) or the first big response closes the connection.

Package visor pkg/visor/init.go c3-vis-core

This file is the "table of contents" for visor initialization. It declares all init modules, registers them with their dependencies, and provides the shared context helpers used by the init functions spread across the init_*.go files.

Actual initialization logic lives in:

• init_dmsg.go — DMSG client, ctrl, pty, ping, server latency
• init_transport.go — Transport manager, STCPR/SUDPH/STCP, address resolver, TPD
• init_router.go — Router, route setup hooks, embedded route setup, node health
• init_apps.go — App launcher, CLI/RPC, hypervisors
• init_services.go — Event broadcaster, uptime, survey, forwarding, ping, UI server

Package visor pkg/visor/init_apps.go c3-vis-core init_apps.go contains app launcher and CLI initialization logic.

Package visor pkg/visor/init_ar_bind_cxo.go c3-vis-core

AR-bind-over-CXO publisher. The visor mirrors its address-resolver bindings — the same stcpr/sudph/quic/wt reachable-address payloads it POSTs to /bind (and re-registers over a fresh dmsg stream every ~90s) — onto a persistent CXO feed on DmsgVisorARBindCXOPort and announces to the AR, which subscribes back and ingests them. This moves the address binding off the timer-driven re-registration, each a fresh dmsg stream with a full Noise handshake (the secp256k1 ECDH handshakeResponder that dominates AR CPU), onto one warm CXO connection.

Once the AR is subscribed and answering, its ingest of the heartbeat Roots refreshes the bindings' TTL and unchanged re-binds skip HTTP. HTTP carries a changed payload, the first bind, and one re-bind after the AR resubscribes on a new conn or stops answering (see cxoKeepaliveHealthy). The publisher is fed by a hook the AR client fires on every successful bind (see addrresolver.BindPublisher), so the CXO leaf always carries the exact LocalAddresses the visor last registered. It is inert until an AR subscribes to the feed.

Package visor pkg/visor/init_coinnode.go c3-vis-core

Brings up fibercoin node discovery (servicedisc.ServiceTypeCoin). For each v.conf.CoinNodes entry the visor:

1. reverse-proxies the node's local HTTP API over dmsg on the configured DmsgPort (reusing the forwarded-ports infra), so a remote thin-client wallet — including the browser wasm visor over its HTTP-over-dmsg shim — can reach the node's API through the mesh; and
2. on the SD heartbeat interval, probes the node's /api/v1/health, builds a DETECTED CoinInfo (never operator-claimed), and registers a type=coin SD entry ONLY while the node answers — deregistering when it goes away, so the advertisement is always truthful (no dead entries).

The node itself runs INDEPENDENTLY of the visor (systemd/terminal); the visor never starts or stops it. See docs and project_skycoin_wallet_over_dmsg.

Package visor pkg/visor/init_dmsg.go c3-vis-core init_dmsg.go contains DMSG initialization logic.

Package visor pkg/visor/init_dmsg_relay.go c3-vis-core

dmsg over skynet through this visor (#4484 stage 3). Two halves of one mechanism, both on the visor's single dmsg client:

• RELAY (accept side): a listener on skyenv.DmsgRelayPort over skynet. A whitelisted peer that dials it gets a server-role dmsg session on this client (dmsg.Client.AcceptRelaySession); its stream requests are carried over this visor's own dmsg server sessions under the PEER's key.
• CARRIER (dial side): the client's session dialer for skynet:// server addresses. A seeded server entry "skynet://<pk>:70" is dialed as a skywire route to that visor's relay, then wrapped in the usual Noise+yamux dmsg session.

Neither half registers anything in discovery or opens a TCP listener.

Package visor pkg/visor/init_dmsg_relay_local.go c3-vis-core

The LOCAL dmsg relay acceptor: the third pipe into the same relay init_dmsg_relay.go already serves over skynet, and the only one that does not involve the network at all.

It exists for the standalone dmsg client that has to keep its key. The dmsgweb proxy is the case that forced it: it runs beside the visor under a key the survey whitelist knows, so rotating the key is not an option, and yet every one of those processes holds its own sessions to dmsg servers and publishes its own discovery entry — a whole second client's worth of server capacity, per process, on a host that already has a visor with sessions and transports. Attached here it keeps the key, holds exactly one session (to this visor, over a unix socket), publishes nothing, and its streams ride this visor's sessions.

AUTHORIZATION — read dmsg.DmsgLocalRelayConfig's comment for the full model. In short: the unix socket's 0600 mode means the attacher is already running as the visor's user, which is a process that could read the visor's secret key off disk anyway; and the optional allowed_keys list is real authentication, because the dmsg session handshake is Noise XK and proves the attacher holds the secret key for the PK it claims. The loopback listener has no filesystem gate, so it is refused unless allowed_keys is non-empty.

Package visor pkg/visor/init_dmsg_skywire.go c3-vis-core the dmsgpty Host over skynet routes.

Lives in pkg/visor (not pkg/dmsg/dmsgpty) because pkg/app/appnet imports are visor-tier — pushing them down into the dmsgpty package would invert the layering. The dmsgpty package keeps its generic StreamDialer / PKExtractor interfaces (Phase 1/2); this file bridges them to appnet.SkywireNetworker on the visor side.

Phase 3 effect: the dmsgpty Host gains a parallel listener on appnet.SkywireNetworker AND its MultiDialer chain prepends a skynet strategy. `cli dmsg pty start` now rides the visor's already-negotiated transports first; on miss (no route, remote not exposing skynet listener) the chain falls through to the existing dmsg strategy. Backward-compat: every dmsg-only deploy keeps working unchanged because dmsg is the chain's last entry.

Package visor pkg/visor/init_embedded_services.go c3-vis-core

Deployment services running inside the visor. Each block in config.embedded_services is built by its pkg/services factory and mounted under a path prefix on the dmsg HTTP port, next to the log server, so transport-discovery becomes dmsg://<visor pk>:80/tpd/... and is reached the way the visor itself is: one dmsg stream to this key, over any session that reaches it. The service keeps no key, no listener and no dmsg sessions of its own; its CXO aggregators and publishers run on the visor's dmsg client under the visor's key.

Requests over dmsg carry the caller's key in RemoteAddr, which is what the services' whitelists and SW-Sig auth read, so their access rules are unchanged. The nonce path only exists for plain HTTP and is not served here.

Package visor pkg/visor/init_embedded_services_register.go c3-vis-core

Package visor pkg/visor/init_group.go c3-vis-core

Init wiring for the chat-group feed manager. Parallel to init_pairing.go — same shape, same best-effort failure semantics, same close-stack registration. Depends on dmsgC, opens its own bbolt store under v.conf.LocalPath/skychat/groups.db, and resumes any non-terminal group records persisted from a previous run.

Package visor pkg/visor/init_hypervisor_transport.go c3-vis-core

Visor → hypervisor transport auto-upgrade.

The visor's `Hypervisors` config field lists hypervisor PKs the visor reports to. ServeRPCClient establishes a dmsg session to each as the bootstrap RPC channel — that's the "is the hypervisor reachable" signal. Once that session is up, the goroutine started here attempts a direct transport between the visor and the hypervisor too, so subsequent RPC + skypty dials can ride the fast p2p path instead of the dmsg relay.

Ordering rationale:

1. dmsg session up → hypervisor is alive + reachable through the network.
2. Attempt every direct carrier this visor can open, in the active preference order (tptypes.PreferenceOrder), stopping at the first that succeeds. dmsg is skipped — it is the relay being escaped, not a destination.

The carrier set is deliberately NOT a fixed pair. It used to be stcpr-then-sudph, which quietly excluded every visor that has neither: a browser visor opens swtr/swsr/webrtc and nothing else, so it never upgraded off the relay at all. Preference is one setting, owned by tptypes and settable at runtime; this loop reads it rather than restating a subset of it.

The transport persists past first creation; the goroutine reconciles every 5 minutes (or after a failed attempt's backoff expires) by re-checking whether a fast transport is still present and re-trying if not.

Stops cleanly when the visor's lifecycle ctx is canceled.

Package visor pkg/visor/init_lan_dmsg.go c3-vis-core

Package visor pkg/visor/init_pairing.go c3-vis-core

Init wiring for the chat-pair feed manager. Mirrors initStats and initCXOUserFeeds: depends on dmsgC, opens its own bbolt store under v.conf.LocalPath/pairing/, and resumes any pairs persisted from a previous run.

The pairing module sits intentionally low in the dependency graph — it doesn't need transports, routes, or the launcher — so the only init-ordering constraint is "after dmsgC."

Package visor pkg/visor/init_registration_cxo.go c3-vis-core

Registration-over-CXO publisher. Runs whenever a dmsg-discovery PK resolves (there is no opt-in flag — earlier comments referenced a Dmsg.RegistrationCXO field that was never added). It publishes this visor's own signed discovery entry as a CXO feed on DmsgDMSGDRegistrationCXOPort and announces to the deployment's dmsg-discovery, which subscribes back and ingests the entry. This moves client-entry registration off the timer-driven HTTP PUT — each a fresh dmsg stream with a full Noise + post-quantum handshake, the load that dominates dmsg-discovery CPU — onto a persistent CXO connection kept warm by the treestore heartbeat.

The entry is published verbatim from the dmsg client's canonical registration path (see EntityCommon.SetEntryPublishHook): the same bytes, sequence and signature dmsg-discovery accepts over HTTP, so the CXO ingest is a drop-in mirror. HTTP PUT is kept alongside as the fallback, so this is safe to enable ahead of the server-side aggregator rollout — it is simply inert until a dmsg-discovery subscribes to the feed.

Package visor pkg/visor/init_router.go c3-vis-core init_router.go contains router initialization logic.

Package visor pkg/visor/init_router_listener.go c3-vis-core

Package visor pkg/visor/init_sd_reg_cxo.go c3-vis-core

SD-registration-over-CXO publisher. The visor mirrors its own service-discovery entries — the type=visor / vpn / skysocks / coin registrations pkg/app/appdisc POSTs to /api/services and re-POSTs every 90s (skyenv.ServiceDiscUpdateInterval) — onto a persistent CXO feed on DmsgVisorSDRegCXOPort, and announces to the service-discovery, which subscribes back and ingests them. This moves the SD heartbeat off the timer-driven re-registration, each a fresh dmsg stream with a full Noise handshake (the secp256k1 handshakeResponder that dominates discovery- service CPU), onto one warm CXO connection.

The feed is inert until an SD subscribes to it. Once the SD is subscribed and answering, its ingest of the heartbeat Roots refreshes the entries' TTL and unchanged heartbeats skip HTTP (servicedisc.KeepaliveSink). HTTP carries a changed entry, the first registration, deletes, and one registration after the SD resubscribes on a new conn or stops answering.

What is published ¶

A visor's service set is per-app and changes when apps start and stop, so the feed carries ONE batched leaf holding the visor's WHOLE current live set, republished on every change:

services        // FrameGzip(v1, JSON []servicedisc.Service)

The entries are verbatim what the SD accepted and echoed back (the clients feed them in through servicedisc.EntrySink), so the ingest is a drop-in mirror of the HTTP register.

Deregistration is ABSENCE, not a tombstone — the same rule SD's own publisher documents (pkg/deployment/sd/api/cxo_publisher.go). A service that stops is simply missing from the next batch, and SD's Redis store expires it on the existing entry TTL. When the set empties, the leaf itself is deleted.

Package visor pkg/visor/init_selfprobe.go c3-vis-core

Package visor pkg/visor/init_services.go c3-vis-core init_services.go contains service initialization logic: health tracking, uptime, survey, forwarding connections, ping listeners, and the UI server.

Package visor pkg/visor/init_skynet_ports.go c3-vis-core

Auto-registers the visor's localhost service ports for skynet forwarding so they're accessible via .skynet URLs (or any skynet client) without manual RegisterTCPPort calls.

Which ports: everything that already listens on localhost and would be useful to reach remotely. The sky-forwarding server (port 57) validates each forwarded port against this list, so only explicitly registered ports are reachable — the access control model is the same as DMSG (PK-authenticated route + noise handshake) just over the routing mesh instead of dmsg servers.

Ports that serve ONLY over DMSG (no localhost listener) like port 136 (route setup RPC) are NOT registered here because there's nothing on localhost to forward to. Making those skynet-accessible would require also binding them on localhost — a separate, larger change.

Package visor pkg/visor/init_stats.go c3-vis-core store into the visor lifecycle.

initStats opens the bbolt store, builds the pull-style probes (transport snapshot, tier states, service states), constructs the Tracker, and registers the Close in the visor's close stack so the store and goroutine drain on shutdown.

Package visor pkg/visor/init_transport.go c3-vis-core init_transport.go contains transport initialization logic.

Package visor pkg/visor/init_udp_forwarding.go c3-vis-core faithful-UDP port forwarding (#2607 stage-4c). The dial/client side lives in appnet (DialPacket). This is the accept side: for every forwarded port marked UDP, the visor registers datagram intent with the router, then a single accept loop drains the datagram siblings the route-setup builds for inbound datagram routes and bridges each to the local UDP service via a UDPBridge.

Package visor pkg/visor/init_uptime.go c3-vis-core service-self uptime recorder. The recorder itself is constructed in run() (so a panic during NewVisor still leaves a session row); this file owns the wireup that connects an existing recorder to the rest of the visor — logserver routes, RPC accessor, close stack — once NewVisor has succeeded.

Package visor pkg/visor/init_voice.go c3-vis-core

Brings up the skychat 1:1 voice-call manager (pkg/skychat/call): it listens for inbound call signaling on skyenv.SkychatVoiceSignalPort over BOTH dmsg AND skynet (same port), and dials outbound calls over whichever network resolves. Media (RTP) rides the signaling conn (a Noise-encrypted skywire transport), never a raw-internet/ICE path — see docs/skychat-voice-rfc.md.

Package visor pkg/visor/lan_dmsg_discovery.go c3-vis-core Auto-discovery of LAN DMSG servers from hypervisors.

Package visor pkg/visor/local_graph.go c3-vis-core

A local graph source is a set of transport entries this visor knows about beyond its own transport manager and the network-wide TPD snapshot. Today the one source is a hypervisor's view of its attached visors (Hypervisor.AttachedTransportEntries, #4750): every attached visor reports its transports in the summary the hypervisor already polls, so route calculation can use those edges without a TPD or route-finder query.

Package visor pkg/visor/memlimit.go c3-vis-core

Package visor pkg/visor/meshproxy.go c3-vis-core meshproxy — the RFC "real-origin" native browse path (see pkg/wasmhv/browseui/RFC-real-origin-browser.md). Instead of the WinBox browser fetching a page and re-implementing the network stack inside a sandboxed opaque srcdoc, this serves mesh (dmsg) sites from a REAL local origin so the BROWSER does native subresource loading, redirects, cookies, WASM, and streaming — skywire only proxies the transport (over dmsg), exactly like pkg/dmsgweb does for a real external browser via SOCKS5. Content flows through THIS visor's own transports; the listeners are loopback-only.

Two origin shapes (BrowseOrigin.Mode), both giving each mesh site its OWN isolated browser origin:

• "subdomain" (default): ONE listener; each site is the origin <vhost>.<base32pk><suffix> (suffix ".mesh.localhost" resolves to loopback in every target browser, so no public cert is needed; set a real domain + TLS for hosted/https parity). Routed by the Host header.
• "port": each site gets its OWN 127.0.0.1:<port> origin from a small pool. No DNS/wildcard dependency (works anywhere), weaker isolation (cookies are domain-scoped, not port-scoped). A "portal" on Addr resolves a mesh host to its per-site port via GET /open?host=<resolver-host> → 302.

Optional TLS (BrowseOrigin.TLSCert/TLSKey) serves either mode over HTTPS with a real or locally-trusted cert — for local https parity with the hosted <pk>.<domain> origin (same scheme, secure context, real-domain cookies).

It is a SEPARATE listener from the hypervisor UI (:8000) on purpose: untrusted mesh content must never share an origin with the control surface, and these listeners serve ONLY the reverse proxy — no /api, no UI.

Package visor pkg/visor/node_health.go c3-vis-core

Package visor pkg/visor/notifyhub.go c3-vis-core

The visor-global notification hub — the "where" half of the notification system whose "whether" half lives in each app (see pkg/app/appserver/notify.go).

An app publishes a NotifyReq and stops caring. The hub owns the one decision an app cannot make for itself: which delivery path can actually reach the user right now. It walks a fixed priority chain and stops at the first tier that can deliver, so a single event surfaces exactly once:

(a) an attached UI holding a fresh capability lease — a UI that will really
    put this in front of the user (it also knows what is focused and muted),
    so the hub must not double up. No consumer ships today: the lease is the
    designed-in slot for the hypervisor manager UI's notification bell, and
    it stays false until something calls MarkUICapable.
(b) subscribed host apps — the Android foreground service (and later the
    manager UI) reading the SSE stream, which post native notifications
    through per-app channels.
(c) the host OS notification center via pkg/osnotify — the desktop default.
(d) nothing: on a headless visor (server, router, daemon) there is no UI, no
    subscriber and no desktop session, so the event drops. That is the
    normal case for most of the fleet, not an error.

Why the tiers are ordered this way: each one is strictly "closer" to a user who is actually looking. A capable UI beats a background service beats a desktop toast. Suppression is always DERIVED at publish time (is anyone subscribed right now?), never stored — a cached "phone is attached" flag plus a dropped connection would mute the desktop permanently.

Package visor pkg/visor/options.go c3-vis-core

Package visor pkg/visor/pairing.go c3-vis-core

Visor-level wrapper around the cmd/apps/skychat/pairing package.

The visor owns one pairing.Manager (initialized in init_pairing.go) and an in-memory ring of recently-received messages. RPC clients call PairAdd / PairRemove / PairList to manage their contact list, PairSend to dispatch a message into the corresponding pair feed, and PairPoll to drain inbound messages. The poll model is intentionally simple — long-poll / SSE delivery to apps can layer on later (PR-4) without changing the Visor surface.

Package visor pkg/visor/pairing_hv.go c3-vis-api

Hypervisor pairing (#4484 stage 5). A peer that holds a same-origin transport to this visor (a desk tab the hypervisor serves) or that tried the transport RPC without being whitelisted is a PENDING hypervisor: listed by fingerprint for `skywire cli visor hv pair`, and approved either there or with a one-time code the operator makes on the board and types into the tab. Approval is the existing AddHypervisor path, so the host dials the peer as its hypervisor and lets it drive RPC and pty — and nothing else grants that.

Package visor pkg/visor/peer_whitelist.go c3-vis-core

peerWhitelist is the visor's single source of truth for "which peer PKs may manage this visor". Every management surface consults it live, per-connection: the dmsgpty host, dmsgscp, the /pty web terminal, and the transport-RPC / dmsg-gRPC / dmsg visor-RPC servers. Because they all hold the same mutable reference, a runtime addition propagates to all of them at once.

Transitive trust: a visor configured with hypervisor H connects to H and serves its RPC to it. On accept, H pushes its OWN configured hypervisors to the visor via AddPtyWhitelist, so a super-hypervisor SH that manages H can also reach the visor — trust flows up the hypervisor chain without the operator re-listing SH on every visor.

Package visor pkg/visor/ping.go c3-vis-core

Package visor pkg/visor/policy_loader.go c3-vis-core for routing-policy backends. A single config field (`routing.policy_per_dial`, per-app `routing_policy`, or the runtime `app start --routing-policy <path>` flag) accepts both `.star` (Starlark) and `.wasm` (WASM) artifacts; this helper inspects the path and instantiates the matching Loader, returning the shared policy.Engine interface so callers don't branch on backend.

Package visor pkg/visor/policy_provider.go c3-vis-core implementation of pkg/router/policy.Provider. Surfaces the visor's transport-tracker state, embedded geoip database, service-discovery snapshot, operator-configured trust list, and configured hypervisor PKs to the operator's Starlark routing policy script.

Geo resolution is layered:

1. SD snapshot (PK→country built from public proxy/vpn/visor entries). Covers multihop intermediates that advertise themselves as a service — without this, every non-neighbor PK would return "??" because the visor has no direct IP for off-path hops. Refreshed on a TTL so it's not in the dial hot path more than once every refreshTTL.
2. Direct-transport IP → embedded geoip. Catches direct neighbors that don't advertise as a service.
3. AR-resolve IP → embedded geoip. Catches AR-registered intermediaries that are neither advertised as a service nor directly connected — the common geo-avoid hop. The AR Resolve hits the network, so it runs OFF the dial hot path: a miss fires a single background resolve (deduped) and caches the result (including negatives) per-PK on a TTL; geo-avoid converges over a couple of selections.
4. "??" — the policy script's filter falls through.

SD snapshot source is the CXO subscription manager (zero network cost when running) with an HTTP fallback (the existing servicesFromHTTP path used by VPNServers/ProxyServers/etc.) when CXO isn't installed or returns empty.

Package visor pkg/visor/profile.go c3-vis-core

The visor half of skychat profiles: read and write this visor's own published identity, and fetch a peer's.

Thin, like pkg/visor/group.go is thin — every rule about what a profile may contain lives in pkg/skychat/profile, and the transport lives on the group manager's describe port. What is here is the RPC-facing shape and the decision of which of the two answers (local store, remote round trip) a given public key deserves.

Package visor pkg/visor/proxied_visor_api.go c3-vis-core

proxiedVisorAPI lets the hypervisor's HTTP layer talk to a visor that isn't directly connected to it — instead reaching it through a sub-hypervisor that is. The hypervisor walks ProxiedVia from HVListVisors output, finds the sub-hypervisor that has the target visor in its own remoteVisors map, and constructs a proxiedVisorAPI that re-routes each VisorAPI method through the sub-hypervisor's HVxxx RPC method (using the target visor's PK as the first arg).

The HVxxx surface on the sub-hypervisor's API is partial — only the ~30 most operator-facing methods have counterparts today. Other methods on proxiedVisorAPI return ErrProxyNotSupported via the embedded proxyDefaultAPI's stubs (generated from api.go's API interface). The hvui falls back to its existing offline-row rendering for fields it can't fetch.

Package visor pkg/visor/proxy_default_api.go c3-vis-core

Generated by /tmp/gen_proxy_stubs.go from pkg/visor/api.go.

proxyDefaultAPI implements the full API interface by returning ErrProxyNotSupported (or the zero value for non-error returns) from every method. proxiedVisorAPI embeds it and overrides the methods that have HVxxx counterparts on the sub-hypervisor's API.

To regenerate after API changes:

go run /tmp/gen_proxy_stubs.go > pkg/visor/proxy_default_api.go

Package visor pkg/visor/pty_forwarding.go c3-vis-pty

Package visor pkg/visor/reach_card.go c3-vis-core

Reach cards: a visor tells peers itself how to dial it. It serves the records the address resolver holds for it, signed, on GET /reach over dmsg and skynet, and a dialer asks the peer for its card before it asks the resolver. The resolver is left telling a visor what to put in its card, and answering for peers that do not serve one.

Package visor pkg/visor/reward_push.go c3-vis-core

Visor-side survey PUSH: periodically send this visor's node-info survey to the reward system over dmsg, so reward eligibility no longer depends on the reward system pulling the survey on its own (online-gated, silent-drop-prone) schedule.

Design: a conditional PUT. Each cycle the visor GETs the sha256 the reward system currently holds for its PK (/node-info/stored-checksum, scoped to the authenticated sender) and only POSTs the full survey when it differs — so a steady-state survey costs one tiny checksum round-trip, and a changed survey (or one the reward system has lost/aged-out) is re-sent. The survey regenerates ~daily (a fresh timestamp), which naturally yields a daily re-assert. The reward system's accept/reject verdict is recorded in v.survey so the hypervisor UI can show reward eligibility (a rejected push → red mark, distinct from the hyphen for no reward address). No-op until a reward address is set and reward_system_dmsg is configured.

Package visor pkg/visor/rewards_ui_native.go c3-vis-core

Package visor pkg/visor/routeviz_embed.go c3-vis-core

Package visor pkg/visor/rpc.go c3-vis-core

Package visor pkg/visor/rpc_apps.go c3-vis-core

Package visor pkg/visor/rpc_ar.go c3-vis-core

Package visor pkg/visor/rpc_bridge.go c3-vis-core

TCP→{dmsg,skynet} bridge for the CLI's `--via <scheme>://<pk>` flow. Multiplexed onto the visor's existing CLI RPC port (v.conf.CLIAddr, default localhost:3435) via cmux: any conn starting with the 6-byte magic bridgeMagic is routed here, everything else falls through to gRPC or net/rpc.

Header (sent by the CLI after cmux matched the magic prefix):

6 bytes — magic ("SKYBRI"). cmux peeks this but doesn't
          consume it, so we read all 42 bytes ourselves.
1 byte  — scheme: 0 = dmsg, 1 = skynet
33 bytes — target visor PK
2 bytes — little-endian uint16. Dmsg port for scheme=0
          (typically DmsgVisorRPCPort = 57). Ignored for
          scheme=1.

Total: 42 bytes.

After header is read, the visor opens the appropriate stream using ITS OWN identity (dmsg client for scheme=0, transport-RPC mux for scheme=1), then bidirectionally io.Copy's between the TCP conn and the stream. CLI's rpc.Client runs on the TCP conn; remote's rpc.Server runs on the other side of the stream; both speak gob, no protocol translation. CLI inherits the visor's whitelist eligibility on the remote without needing its own keypair.

Package visor pkg/visor/rpc_client.go c3-vis-core

Package visor pkg/visor/rpc_client_serve.go c3-vis-core

Package visor pkg/visor/rpc_cxo_feeds.go c3-vis-core

RPC adapter for the CXO user-feed registry. The handlers are thin wrappers over Visor.RegisterCXOFeed / UnregisterCXOFeed / ListCXOFeeds; per-feed lifecycle management lives in cxo_user_feeds.go.

Package visor pkg/visor/rpc_dmsg.go c3-vis-core

Package visor pkg/visor/rpc_embedded_services.go c3-vis-core

Package visor pkg/visor/rpc_group.go c3-vis-core

RPC adapter for the chat-group feed manager. Thin wrappers over the Visor methods in group.go. Mirrors rpc_pairing.go shape.

Package visor pkg/visor/rpc_hostbridge.go c3-vis-wasm

Package visor pkg/visor/rpc_hypervisor_proxy.go c3-vis-core

RPC methods that proxy through the hypervisor's DMSG connections to remote visors. These enable CLI/TUI access to remote visor data without needing direct transport connections.

Package visor pkg/visor/rpc_hypervisors.go c3-vis-core

Package visor pkg/visor/rpc_mail.go c3-vis-core

Package visor pkg/visor/rpc_network.go c3-vis-core

Package visor pkg/visor/rpc_pairing.go c3-vis-core

RPC adapter for the chat-pair feed manager. Thin wrappers over the Visor methods in pairing.go.

Package visor pkg/visor/rpc_ping.go c3-vis-core

Package visor pkg/visor/rpc_profile.go c3-vis-core

RPC adapter for skychat profiles. Thin wrappers over the Visor methods in profile.go. Mirrors rpc_group.go shape.

Package visor pkg/visor/rpc_proxies.go c3-vis-core

Package visor pkg/visor/rpc_routing.go c3-vis-core

Package visor pkg/visor/rpc_services.go c3-vis-core

Package visor pkg/visor/rpc_tps.go c3-vis-core

Package visor pkg/visor/rpc_transport.go c3-vis-core

Package visor pkg/visor/rpc_transport_proxy.go c3-vis-core

TransportRPCProxy enables CLI access to a remote visor's RPC through the local visor's transport. The CLI connects to the local visor (localhost:3435 as usual), calls ProxyRPC with the remote PK, and the local visor opens a VStream to the remote visor over their shared transport. The remote visor serves RPC on that VStream (authenticated via the hypervisor/dmsgpty whitelist).

Usage from CLI:

skywire cli --rpc localhost:3435 visor tp-rpc <remote-pk> <method> [args]

The local visor must: 1. Have a transport to the remote visor 2. Be in the remote visor's hypervisor/dmsgpty whitelist

Package visor pkg/visor/rpc_visor.go c3-vis-core

Package visor pkg/visor/rpc_voice.go c3-vis-core

Package visor pkg/visor/servedversion.go c3-vis-core

Package visor pkg/visor/service_registry.go c3-vis-core

ServiceRegistry maps port numbers to connection handlers so the sky-forwarding server (and future transports) can dispatch incoming connections to the correct service without needing a localhost TCP bounce. Each handler is a function that owns a net.Conn for its lifetime — it reads requests, writes responses, and closes the conn when done.

This replaces the old isPortRegistered / allowed-ports / localhost TCP dial pattern. Registration IS the access control: if a port isn't in the registry, the forwarding server refuses it. Services that shouldn't be exposed (RPC, hypervisor) simply don't register.

Package visor pkg/visor/skymail.go c3-vis-core

The visor's own mailbox (pkg/skymail). It listens for SMTP on port 25 over dmsg and skynet, like every dual-listened visor port, and sends by dialing the recipient visor's port 25 directly: no MTA, no queue, no certificate, so it runs as-is in a browser tab. It is on by default everywhere; the size and age limits keep an open mailbox from filling the storage it lives in. Enable and every limit are live settings (MailSetSettings), kept in settings.json beside the mail.

Package visor pkg/visor/skynet_first_dialer.go c3-vis-core

SkynetFirstUIDialer wraps a dmsg-based dmsgpty UIDialer and tries to reach the peer over the skywire router first. The visor's dmsgpty host already dual-listens on dmsg and skynet at the same port (see init_dmsg_skywire.go's startSkywirePtyListener), so the peer-side accept loops are symmetric — the only thing missing was the hypervisor's dial-side preference for the fast path.

Behavior:

• Try appnet.DialContext(skynet, peer:port) with a short timeout. Success returns that conn; the pty stream flows over whatever transport the router selected (stcpr / sudph / dmsg).
• On any error from the skynet dial (no route, networker not registered, timeout), fall back to dmsg.Client.Dial which has been the original behavior.

The skynet path needs a route to the peer, which means the visor has to be sharing a transport with the hypervisor (or vice versa). pkg/visor/init_hypervisor_transport.go's auto-upgrade goroutine establishes that route from the visor side; the hypervisor uses any transport the visor advertised in the address resolver.

Package visor pkg/visor/skynet_relay_dial.go c3-vis-core

Relay tier for the SKYNET dialer (DialSkynet), i.e. `.skynet` hosts only. When there's no direct transport to a destination, reach it through a 1-hop relay — a peer we share a direct (non-dmsg) transport with that also has one to the destination — using VStreamMux.DialThroughRelay (route ID 0, PK-addressed forwarding, no route-finder, no setup-node). It slots between the direct-transport fast path and the existing multihop-route (RF) fallback: direct → relay → route.

This does NOT touch the `.dmsg` path: dmsg is a relay layer and is never route-finder-routed. Making dmsg-addressed / deployment targets reachable via the visor-relay is a separate, relay-only integration (no RF fallback).

Package visor pkg/visor/skynet_relay_graph.go c3-vis-core

Package visor pkg/visor/static_embed.go c3-vis-core

Package visor pkg/visor/status_board.go c3-vis-core

Package visor pkg/visor/survey.go c3-vis-core

Package visor pkg/visor/svc_fetch_cache.go c3-vis-core

Package visor pkg/visor/systray.go c3-vis-core

Package visor pkg/visor/temp_loglevel.go c3-vis-core

Package visor pkg/visor/tpd_announce_stats.go c3-vis-core

Package visor pkg/visor/transport_list.go c3-vis-core

Package visor pkg/visor/transport_list_fetch.go c3-vis-core

Package visor pkg/visor/transport_rpc.go c3-vis-core

TransportRPC serves the visor's RPC interface over skywire transports using VisorRPCPacket (route ID 0) virtual streams. This allows remote management without DMSG or routes — only a direct transport is needed.

Access is controlled by the visor's hypervisor PK whitelist: only PKs listed in the config's `hypervisors` field (or the dmsgpty whitelist) are permitted to open RPC streams.

Package visor pkg/visor/udp_client_forward.go c3-vis-core faithful-UDP port forwarding (#2607 stage-4d). The server side (init_udp_forwarding.go) bridges inbound datagram routes to a local service; this is the mirror: it dials a remote forwarded_ports.udp service via DialPacket and bridges it to a local UDP socket the operator's UDP app talks to.

Package visor pkg/visor/visor.go c3-vis-core

Package visor pkg/visor/voice.go c3-vis-core

Visor-side RPC surface for skychat 1:1 voice (the manager lives in pkg/skychat/call, brought up by init_voice.go). Place a call, hang up, and list active calls; media rides an encrypted skywire transport.

Package visor pkg/visor/voice_ringback.go c3-vis-core

Keeps this visor's ringback tone — what a caller hears while it rings — across restarts. The call manager holds it in memory; this is the copy on disk, beside the rest of the visor's local state.

Package visor pkg/visor/wasmmodule.go c3-vis-core

Package visor pkg/visor/wasmserve.go c3-vis-core

ServeWasm mounts the standalone wasm-visor PWA (the same surface as `skywire cli hv serve`) as an HTTP server. Extracted here so BOTH the CLI command and the visor daemon can serve it from the one binary / one process: `skywire visor --wasm-serve :8443 [--wasm-serve-tls] [--wasm-serve-harness]` brings the harness up alongside the visor, and the operator's rebuild-restart loop re-embeds + re-serves the latest wasm every restart (no separate process to remember).

Package visor pkg/visor/wasmserve_bootreport.go c3-vis-core