agentfy-remote-framebuffer-protocol

A small RFB (Remote Framebuffer) protocol server in Obj-C++ for Apple platforms. Implements the RFC 6143 subset described in docs/PROTOCOL.md. About 2,000 lines of code, single static library, no GPL dependencies. The C symbol prefix is agfy_rfb.

When to use this

• You're building an Apple-platform app and want to embed a small RFB server for remote debugging or observation
• You need a CI test fixture that spawns a real RFB endpoint
• You're shipping a kiosk or appliance device that wants to expose a screen feed
• You'd otherwise reach for libvncserver but its GPL-2.0+ license is incompatible with your distribution model (proprietary app, permissively-licensed product, App Store, etc.) — this library is Apache-2.0 and links cleanly into any of them

Quickstart

# macOS 14+ / iOS 14+ SDK, CMake 3.20+, libjpeg-turbo, zlib
brew install jpeg-turbo cmake
git clone https://github.com/Agentfy-io/agentfy-remote-framebuffer-protocol.git
cd agentfy-remote-framebuffer-protocol
make                # builds libagfy_rfb.a + the example
./build/synthetic_server

In another terminal, point any RFB client at 127.0.0.1:5900 (password demopw). You should see a colour ramp with a white box drifting across it.

Embedding

#include <agfy_rfb.h>

static void on_pointer(int mask, int x, int y,
                       agfy_rfb_client_t *cl, void *user) {
    /* forward to your input system */
}
static void on_key(uint8_t down, uint32_t keysym,
                   agfy_rfb_client_t *cl, void *user) {
    /* forward to your input system */
}

int main(void) {
    agfy_rfb_server_t *s = agfy_rfb_create(1920, 1080, AGFY_RFB_PIXFMT_BGRA8888);

    static uint8_t fb[1920 * 1080 * 4];   /* your 1920x1080 BGRA buffer */
    agfy_rfb_set_frame_buffer(s, fb, 1920 * 4);
    agfy_rfb_set_desktop_name(s, "my-app");
    agfy_rfb_set_password(s, "your-password");
    agfy_rfb_set_pointer_event_hook(s, on_pointer, NULL);
    agfy_rfb_set_keyboard_event_hook(s, on_key, NULL);

    agfy_rfb_listen(s, 5900, 0);
    agfy_rfb_run_async(s);

    /* in your render loop, when a region of the framebuffer changes: */
    agfy_rfb_mark_dirty(s, x, y, x + w, y + h);

    /* on shutdown: */
    agfy_rfb_stop(s);
    agfy_rfb_destroy(s);
    return 0;
}

Linking with CMake

find_package(agfy_rfb REQUIRED)
target_link_libraries(your_target PRIVATE agfy_rfb::agfy_rfb)

Documentation

• docs/PROTOCOL.md — implemented RFC 6143 subset and tested clients
• docs/BUILDING.md — full build details and platform notes
• docs/API.md — C API reference
• example/ — runnable synthetic-frame server

Status

v0.1.0 is the first public release. The core protocol path (handshake, Raw / CopyRect / Tight encoding, VncAuth, DesktopSize) is in production use. The cursor pseudo-encodings (Cursor, RichCursor) are reserved API but not pushed to clients yet. POSIX transport for Linux / Windows is on the roadmap; today the transport layer requires Network.framework.

Contributing

PRs welcome. See CONTRIBUTING.md. Bug fixes, performance work, platform support and documentation are easy to land. Protocol-level changes (new encodings, new auth types, wire-format extensions) need prior discussion in an issue using the protocol change proposal template.

All commits must carry a Signed-off-by: trailer (git commit -s) asserting the Developer Certificate of Origin.

Reporting issues

Bug reports go through GitHub issues. For anything that lets an unauthenticated client crash, hang or take over the server, please email support@agentfy.io instead of opening a public issue, so we can ship a fix before the details are widely known.

License

Apache-2.0. See LICENSE and NOTICE.

The repo and all symbol prefixes use "RFB" rather than "VNC" because VNC is a trademark of RealVNC Limited; RFB is the protocol name from RFC 6143 and is descriptive. This project is unaffiliated with RealVNC.