Skip to content
OpenCharly

plugin-vnc
Placement runtime (out-of-process over gRPC)
Source github.com/opencharly/charly/candy/plugin-vnc
Version 2026.178.1200
Candy plugin-vnc

This plugin is not listed in charly/charly.yml’s compiled_plugins:. It is not part of the shipped binary: charly builds and loads it out-of-process over gRPC when a plan references one of its words (the coexist path).

Providers

Section titled “Providers”

The reserved words this plugin serves:

  • vnc — verb class

What it does

Section titled “What it does”

OUT-OF-TREE charly plugin serving the vnc RFB/VNC check verb — a standalone Go module (go.mod + main.go) that drives a live deployment’s VNC desktop over the RFB protocol (RFC 6143: the custom stdlib-only VNC client — VeNCrypt/TLS + ZRLE decode), served OUT-OF-PROCESS over go-plugin gRPC via the charly plugin SDK (github.com/opencharly/sdk). charly’s loader fetches this candy’s repo, go-builds the provider binary on the HOST, and serves it via LocalTransport — so the RFB client lives HERE, out of charly’s core check surface (the latest external dep-shed after candy/plugin-cdp; nothing VNC-specific remains in core — the former charly check vnc vm CLI is subsumed into the declarative vnc: verb against a vm target). Since the schema-compaction cutover an authored vnc: step desugars to the internal plugin/plugin_input envelope, and every vnc-exclusive modifier (method/x/y/text/key/artifact/http_method/params) lives in the plugin’s OWN #VncInput (schema/vnc.cue); the verb dispatches through the provider registry exactly like a built-in (ResolveVerb → grpcProvider → invokeVerbProvider hands it the full #Op). The plugin resolves the deployment’s VNC endpoint via the generic cc.ResolveGraphicsEndpoint reverse-leg (the host owns the podman / venue / libvirt / port-mapping machinery) — a container’s published port 5900, or a VM’s libvirt-discovered listener bridged/tunneled to a host-reachable TCP address — plus the resolved password, so this plugin needs no container inspection at all. Provides status/screenshot/click/mouse/ type/key/rfb. The R10 consumer is a wayvnc-bearing pod bed whose check composes this plugin (e.g. sway-browser-vnc via sway-desktop-vnc).

Parameter schema

Section titled “Parameter schema”

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/vnc.cue

Section titled “schema/vnc.cue”
// The `vnc` plugin's OWN CUE schema — the typed plugin_input for the `vnc`
// RFB/VNC check verb. It is the SINGLE SOURCE for this plugin's params, used two
// ways (the same contract core `spec` and the http plugin use):
//
//  1. GENERATE the Go param struct — `cue exp gengotypes` (driven by the cue:gen
//     pipeline, which wraps this with `package params` + `@go(params)`) emits
//     ../params/cue_types_gen.go, so the provider decodes plugin_input into a
//     TYPED struct, never a hand-parsed map.
//  2. VALIDATE authored input AT RUNTIME — the plugin serves this source over the
//     Describe channel; the host splices it onto the base (base ++ plugin) and
//     validates every authored `vnc:` step's plugin_input against #VncInput.
//
// Since the schema-compaction cutover the per-verb fields LEFT core #Op: an
// authored `vnc: <method>` step (scalar sugar) or `vnc: {method: …, x: …}` (map
// form) desugars to the INTERNAL plugin/plugin_input envelope, and every
// vnc-exclusive modifier lives HERE — the former core #VncMethod enum is this
// def's `method` field, and the former shared #Op `method` modifier (which `rfb`
// used for the raw RFB sub-method) is RENAMED `http_method` (the input's
// `method` key is the VERB method), mirroring the cdp `raw` rename. The shared
// assertion matchers (exit_status/stdout/stderr) and the general `timeout` stay
// on core #Op, read off the step Op by the provider.
//
// SELF-CONTAINED: it references NO base def, so it compiles standalone
// (gengotypes + the load-gate compile) AND splices onto the base (base ++ plugin
// is a def-name collision check, not a base-reference resolver).
#VncInput: {
  // method — the vnc method to dispatch (the former core #VncMethod enum; also
  // the scalar-sugar primary: `vnc: <method>`).
  method: "status" | "screenshot" | "click" | "mouse" | "type" | "key" | "rfb"
  // x / y — desktop-absolute coordinates (click/mouse).
  x?: int @go(,type=int)
  y?: int @go(,type=int)
  // button — the mouse button for click (left/right/middle; default left).
  button?: string
  // text — the text `type` types.
  text?: string
  // key — the named key `key` presses.
  key?: string @go(KeyName)
  // http_method — the raw RFB sub-method `rfb` sends (key/pointer/cut-text/
  // fbupdate-request; RENAMED from the former shared #Op `method` modifier —
  // `method` here is the VERB method), mirroring the cdp `raw` rename.
  http_method?: string @go(HttpMethod)
  // params — the JSON params blob `rfb` passes to the sub-method.
  params?: string
  // artifact — the host path `screenshot` writes the PNG to.
  artifact?: string
  // artifact_min_bytes / artifact_min_dimensions / artifact_not_uniform — the
  // post-run artifact-reality assertions (sdk.RunArtifactValidators).
  artifact_min_bytes?:      int & >=0                    @go(ArtifactMinBytes,type=int)
  artifact_min_dimensions?: string & =~"^[0-9]+x[0-9]+$" @go(ArtifactMinDimensions)
  artifact_not_uniform?:    bool                         @go(ArtifactNotUniform)
}

See also the candy reference for this candy’s install surface.