Forem: Rıza Emre ARAS

Claude KVM — VNC Üzerinden AI ile Uzak Masaüstü Kontrolü

Rıza Emre ARAS — Sat, 21 Feb 2026 20:33:09 +0000

Claude KVM, VNC protokolü üzerinden uzak masaüstü ortamlarını kontrol eden bir MCP aracıdır. İnce bir JS proxy katmanı (MCP server) ve MacOS sisteminizde çalışan platformunuza native bir Swift VNC daemon'dan oluşur.

GitHub: ARAS-Workspace/claude-kvm

Canlı Test Ortamı

Not:
Testler GitHub Actions üzerinde CI ortamında şeffaf biçimde yürütülmektedir — her adım aşama aşama görülebilir. Her testin sonunda, entegrasyon başarılı ya da başarısız olsun, ajanın oturum boyunca attığı her adımın ekran görüntüleri ve oturumun tamamını yansıtan .mp4 video kaydı yer almaktadır. Bu kayıtları ve görüntüleri inceleyerek ajanın sistem komutundaki görevi hangi aşamalardan geçerek ne kadar sürede tamamladığını gözlemleyebilir, MCP sunucusunu kendi ortamınızda kullanırken buradaki örneklerden faydalanarak sistem komutunuzu veya talimatlarınızı şekillendirebilirsiniz.

Uyarı:
Bu çalıştırmalara ait artifact'ların süresi GitHub'ın artifact saklama politikası nedeniyle dolmuş olabilir. Kalıcı kopyalar Persist Artifacts workflow'u aracılığıyla hazırlanmıştır ve run ID ile press-kit branch'indeki artifacts/ dizininden her zaman erişilebilir.

Mimari

Katmanlar

Katman	Dil	Görev	İletişim
MCP Proxy	JavaScript (Node.js)	Claude ile MCP protokolü üzerinden iletişim, daemon yaşam döngüsü yönetimi	stdio JSON-RPC
VNC Daemon	Swift/C (Apple Silicon)	VNC bağlantısı, ekran yakalama, fare/klavye giriş enjeksiyonu	stdin/stdout PC (NDJSON)

PC (Procedure Call) Protokolü

Proxy ve daemon arasındaki iletişim NDJSON üzerinden PC protokolünü kullanır:

İstek:    {"method":"<isim>","params":{...},"id":<int|string>}
Yanıt:    {"result":{...},"id":<int|string>}
Hata:     {"error":{"code":<int>,"message":"..."},"id":<int|string>}
Bildirim: {"method":"<isim>","params":{...}}

Koordinat Ölçekleme

VNC sunucusunun doğal çözünürlüğü --max-dimension (varsayılan: 1280px) sınırını aşmayacak şekilde ölçeklenir. Claude ölçeklenmiş koordinatla daha fazla uyum içerisinde çalışır — daemon arka planda dönüşüm yapar:

Doğal:       4220 x 2568  (VNC sunucu framebuffer)
Ölçeklenmiş: 1280 x 779   (Claude'un gördükleri ve hedefledikleri)

mouse_click(640, 400) → VNC alır (2110, 1284)

Ekran Stratejisi

Claude, kademeli doğrulama yaklaşımıyla token maliyetini minimize eder:

diff_check       →  changeDetected: true/false     ~5ms    (yalnızca metin, görüntü yok)
detect_elements  →  OCR metin + sınırlayıcı kutular ~50ms  (yalnızca metin, görüntü yok)
cursor_crop      →  imleç etrafında kare kesit      ~50ms   (küçük görüntü)
screenshot       →  tam ekran yakalama              ~200ms  (tam görüntü)

detect_elements cihaz üzerinde OCR için Apple Vision framework kullanır. Ölçeklenmiş koordinat uzayında metin içeriği ve sınırlayıcı kutu koordinatları döndürür — görüntü token'ı tüketmeden hassas tıklama hedeflemesi sağlar.

Kurulum

Gereksinimler

macOS (Apple Silicon / aarch64)
Node.js (LTS)

Daemon

brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

Not:
claude-kvm-daemon, CI (GitHub Actions) üzerinde derlenir ve code-sign edilir. Derleme çıktısı iki formatta paketlenir: Homebrew dağıtımı için .tar.gz arşivi ve notarizasyon için .dmg disk imajı. DMG paketi aynı akış içerisinde Apple sunucularına gönderilir ve notarize edilir — süreç CI loglarından takip edilebilir. Notarize edilmiş DMG, CI Artifacts üzerinde yer alır; arşivlenen .tar.gz ise repo üzerinde release olarak da yayınlanır. Homebrew kurulumu bu release'i takip eder.

Release · Kaynak Kod

LibVNC Build · LibVNC Branch

Homebrew Tap

MCP Yapılandırması

Proje dizinine .mcp.json dosyası oluşturun:

{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
        "CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
      }
    }
  }
}

Not:
Araç, CI üzerinden uçtan uca test edilmektedir — Claude, VNC üzerinden görevleri yürütürken bağımsız bir görüş modeli sonuçları gözlemleyip doğrular. Canlı workflow çalıştırmaları, sistem komutları ve demo kayıtları için Entegrasyon Testi sayfasına bakınız.

Yapılandırma

MCP Proxy (ENV)

Parametre	Varsayılan	Açıklama
`VNC_HOST`	`127.0.0.1`	VNC sunucu adresi
`VNC_PORT`	`5900`	VNC port numarası
`VNC_USERNAME`		Kullanıcı adı (ARD için zorunlu)
`VNC_PASSWORD`		Şifre
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Daemon binary yolu (PATH'te ise gerek yok)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Daemon'a ek CLI argümanları

Daemon Parametreleri (CLI)

CLAUDE_KVM_DAEMON_PARAMETERS üzerinden daemon'a iletilen ek argümanlar:

"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"

Parametre	Varsayılan	Açıklama
`--max-dimension`	`1280`	Ekran ölçekleme maksimum boyutu (px)
`--connect-timeout`		VNC bağlantı zaman aşımı (saniye)
`--bits-per-sample`		Piksel başına bit sayısı
`--no-reconnect`		Otomatik yeniden bağlanmayı devre dışı bırak
`-v, --verbose`		Ayrıntılı loglama (stderr)

Çalışma Zamanı Yapılandırması (PC)

Tüm zamanlama ve ekran parametreleri configure metodu ile çalışma zamanında yapılandırılabilir. Mevcut değerleri görmek için get_timing kullanılır.

Zamanlama ayarla:

{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}

{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}

Ekran ölçekleme değiştir:

{"method":"configure","params":{"max_dimension":960}}

{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}

Varsayılanlara sıfırla:

{"method":"configure","params":{"reset":true}}

{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

Mevcut değerleri al:

{"method":"get_timing"}

{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

Parametre	Varsayılan	Açıklama
`max_dimension`	`1280`	Maks ekran görüntüsü boyutu
`cursor_crop_radius`	`150`	Cursor crop yarıçapı (px)
`click_hold_ms`	`50`	Tıklama basılı tutma süresi
`double_click_gap_ms`	`50`	Çift tıklama arası bekleme
`hover_settle_ms`	`400`	Hover yerleşme bekleme
`drag_position_ms`	`30`	Sürükleme öncesi pozisyon bekleme
`drag_press_ms`	`50`	Sürükleme basılı tutma eşiği
`drag_step_ms`	`5`	İnterpolasyon noktaları arası
`drag_settle_ms`	`30`	Bırakma öncesi yerleşme
`drag_pixels_per_step`	`20`	Piksel başına nokta yoğunluğu
`drag_min_steps`	`10`	Minimum interpolasyon adımı
`scroll_press_ms`	`10`	Scroll basın-bırak arası
`scroll_tick_ms`	`20`	Tick'ler arası gecikme
`key_hold_ms`	`30`	Tuş basılı tutma süresi
`combo_mod_ms`	`10`	Modifier yerleşme gecikmesi
`type_key_ms`	`20`	Yazma sırasında tuş basılı tutma
`type_inter_key_ms`	`20`	Karakterler arası gecikme
`type_shift_ms`	`10`	Shift tuş yerleşme süresi
`paste_settle_ms`	`30`	Pano yazma sonrası bekleme

Araçlar

Tek bir vnc_command aracı üzerinden tüm işlemler gerçekleştirilir:

Ekran

Aksiyon	Parametreler	Açıklama
`screenshot`		Tam ekran PNG görüntüsü
`cursor_crop`		İmleç etrafında crosshair'li kesit
`diff_check`		Baseline'a göre ekran değişim algılama
`set_baseline`		Mevcut ekranı diff referansı olarak kaydet

Fare

Aksiyon	Parametreler	Açıklama
`mouse_click`	`x, y, button?`	Tıklama (left\
`mouse_double_click`	`x, y`	Çift tıklama
`mouse_move`	`x, y`	İmleci taşı
`hover`	`x, y`	Taşı + yerleşme bekleme
`nudge`	`dx, dy`	Göreceli imleç hareketi
`mouse_drag`	`x, y, toX, toY`	Başlangıçtan bitişe sürükleme
`scroll`	`x, y, direction, amount?`	Scroll (up\

Klavye

Aksiyon	Parametreler	Açıklama
`key_tap`	`key`	Tekli tuş basımı (enter\
`key_combo`	`key` veya `keys`	Modifier kombinasyonu ("cmd+c" veya ["cmd","shift","3"])
`key_type`	`text`	Karakter karakter metin yazma
`paste`	`text`	Pano üzerinden yapıştırma

Algılama

Aksiyon	Parametreler	Açıklama
`detect_elements`		OCR metin algılama ve sınırlayıcı kutular (Apple Vision)

Ölçeklenmiş koordinat uzayında metin elementlerini sınırlayıcı kutu koordinatlarıyla döndürür:

{"method":"detect_elements"}

{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}

Yapılandırma

Aksiyon	Parametreler	Açıklama
`configure`	`{<params>}`	Zamanlama/ekran parametrelerini çalışma zamanında ayarla
`configure`	`{reset: true}`	Tüm parametreleri varsayılanlara sıfırla
`get_timing`		Mevcut zamanlama + ekran parametrelerini al

Kontrol

Aksiyon	Parametreler	Açıklama
`wait`	`ms?`	Bekleme (varsayılan 500ms)
`health`		Bağlantı durumu + ekran boyutları
`shutdown`		Daemon'u düzgün kapatma

Kimlik Doğrulama

Desteklenen VNC kimlik doğrulama yöntemleri:

VNC Auth — şifre tabanlı challenge-response (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS, ARD auth type 30 kimlik bilgisi isteği üzerinden otomatik algılanır. Algılandığında Meta tuşları Super'e yeniden eşlenir (Command tuşu uyumluluğu).

Bu dökümanı GitHub üzerinde görüntüle

Claude KVM -Control Remote Desktops with AI Over VNC

Rıza Emre ARAS — Sat, 21 Feb 2026 20:30:57 +0000

Claude KVM is an MCP tool that controls remote desktop environments over VNC. It consists of a thin JS proxy layer (MCP server) and a platform-native Swift VNC daemon running on your macOS system.

GitHub: ARAS-Workspace/claude-kvm

Live Test Runs

Note:
Tests are conducted transparently on GitHub Actions — each step is visible in the CI environment. At the end of every test, whether the integration passes or fails, you'll find screenshots of each step the agent took during the session, along with an .mp4 video recording that captures the entire session. By reviewing these recordings and screenshots, you can observe how the agent progressed through each stage, how long the task took, and what decisions were made based on the system prompt. You can use these examples as a reference when crafting your own system prompts or instructions for the MCP server in your own environment.

Warning:
Artifacts attached to these runs may have expired due to GitHub's artifact retention policy. Persistent copies are prepared via the Persist Artifacts workflow and can always be accessed by run ID from the artifacts/ directory on the press-kit branch.

Architecture

Layers

Layer	Language	Role	Communication
MCP Proxy	JavaScript (Node.js)	Communicates with Claude over MCP protocol, manages daemon lifecycle	stdio JSON-RPC
VNC Daemon	Swift/C (Apple Silicon)	VNC connection, screen capture, mouse/keyboard input injection	stdin/stdout PC (NDJSON)

PC (Procedure Call) Protocol

Communication between the proxy and daemon uses the PC protocol over NDJSON:

Request:      {"method":"<name>","params":{...},"id":<int|string>}
Response:     {"result":{...},"id":<int|string>}
Error:        {"error":{"code":<int>,"message":"..."},"id":<int|string>}
Notification: {"method":"<name>","params":{...}}

Coordinate Scaling

The VNC server's native resolution is scaled down to fit within --max-dimension (default: 1280px). Claude works more consistently with scaled coordinates — the daemon handles the conversion in the background:

Native:  4220 x 2568  (VNC server framebuffer)
Scaled:  1280 x 779   (what Claude sees and targets)

mouse_click(640, 400) → VNC receives (2110, 1284)

Screen Strategy

Claude minimizes token cost with a progressive verification approach:

diff_check       →  changeDetected: true/false     ~5ms    (text only, no image)
detect_elements  →  OCR text + bounding boxes      ~50ms   (text only, no image)
cursor_crop      →  crop around cursor              ~50ms   (small image)
screenshot       →  full screen capture             ~200ms  (full image)

detect_elements uses Apple Vision framework for on-device OCR. Returns text content with bounding box coordinates in scaled space — enables precise click targeting without consuming vision tokens.

Installation

Requirements

macOS (Apple Silicon / aarch64)
Node.js (LTS)

Daemon

brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

Note:
claude-kvm-daemon is compiled and code-signed via CI (GitHub Actions). The build output is packaged in two formats: a .tar.gz archive for Homebrew distribution and a .dmg disk image for notarization. The DMG is submitted to Apple servers for notarization within the same workflow — the process can be tracked from CI logs. The notarized DMG is available as a CI Artifact; the archived .tar.gz is also published as a release on the repository. Homebrew installation tracks this release.

Release · Source Code

LibVNC Build · LibVNC Branch

Homebrew Tap

MCP Configuration

Create a .mcp.json file in your project directory:

{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
        "CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
      }
    }
  }
}

Note:
The tool is end-to-end tested via CI — Claude executes tasks over VNC while an independent vision model observes and verifies the results. See the Integration Test for live workflow runs, system prompts, and demo recordings.

Configuration

MCP Proxy (ENV)

Parameter	Default	Description
`VNC_HOST`	`127.0.0.1`	VNC server address
`VNC_PORT`	`5900`	VNC port number
`VNC_USERNAME`		Username (required for ARD)
`VNC_PASSWORD`		Password
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Daemon binary path (not needed if already in PATH)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Additional CLI arguments for the daemon

Daemon Parameters (CLI)

Additional arguments passed to the daemon via CLAUDE_KVM_DAEMON_PARAMETERS:

"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"

Parameter	Default	Description
`--max-dimension`	`1280`	Maximum display scaling dimension (px)
`--connect-timeout`		VNC connection timeout (seconds)
`--bits-per-sample`		Bits per pixel sample
`--no-reconnect`		Disable automatic reconnection
`-v, --verbose`		Verbose logging (stderr)

Runtime Configuration (PC)

All timing and display parameters are configurable at runtime via the configure method. Use get_timing to inspect current values.

Set timing:

{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}

{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}

Change display scaling:

{"method":"configure","params":{"max_dimension":960}}

{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}

Reset to defaults:

{"method":"configure","params":{"reset":true}}

{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

Get current values:

{"method":"get_timing"}

{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

Parameter	Default	Description
`max_dimension`	`1280`	Max screenshot dimension
`cursor_crop_radius`	`150`	Cursor crop radius (px)
`click_hold_ms`	`50`	Click hold duration
`double_click_gap_ms`	`50`	Double-click gap delay
`hover_settle_ms`	`400`	Hover settle wait
`drag_position_ms`	`30`	Pre-drag position wait
`drag_press_ms`	`50`	Drag press hold threshold
`drag_step_ms`	`5`	Between interpolation pts
`drag_settle_ms`	`30`	Settle before release
`drag_pixels_per_step`	`20`	Point density per pixel
`drag_min_steps`	`10`	Min interpolation steps
`scroll_press_ms`	`10`	Scroll press-release gap
`scroll_tick_ms`	`20`	Inter-tick delay
`key_hold_ms`	`30`	Key hold duration
`combo_mod_ms`	`10`	Modifier settle delay
`type_key_ms`	`20`	Key hold during typing
`type_inter_key_ms`	`20`	Inter-character delay
`type_shift_ms`	`10`	Shift key settle
`paste_settle_ms`	`30`	Post-clipboard write wait

Tools

All operations are performed through a single vnc_command tool:

Screen

Action	Parameters	Description
`screenshot`		Full screen PNG capture
`cursor_crop`		Crop around cursor with crosshair overlay
`diff_check`		Detect screen changes against baseline
`set_baseline`		Save current screen as diff reference

Mouse

Action	Parameters	Description
`mouse_click`	`x, y, button?`	Click (left\
`mouse_double_click`	`x, y`	Double click
`mouse_move`	`x, y`	Move cursor
`hover`	`x, y`	Move + settle wait
`nudge`	`dx, dy`	Relative cursor movement
`mouse_drag`	`x, y, toX, toY`	Drag from start to end
`scroll`	`x, y, direction, amount?`	Scroll (up\

Keyboard

Action	Parameters	Description
`key_tap`	`key`	Single key press (enter\
`key_combo`	`key` or `keys`	Modifier combo ("cmd+c" or ["cmd","shift","3"])
`key_type`	`text`	Type text character by character
`paste`	`text`	Paste text via clipboard

Detection

Action	Parameters	Description
`detect_elements`		OCR text detection with bounding boxes (Apple Vision)

Returns text elements with bounding box coordinates in scaled space:

{"method":"detect_elements"}

{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}

Configuration

Action	Parameters	Description
`configure`	`{<params>}`	Set timing/display params at runtime
`configure`	`{reset: true}`	Reset all params to defaults
`get_timing`		Get current timing + display params

Control

Action	Parameters	Description
`wait`	`ms?`	Wait (default 500ms)
`health`		Connection status + display info
`shutdown`		Graceful daemon shutdown

Authentication

Supported VNC authentication methods:

VNC Auth — password-based challenge-response (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS is auto-detected via the ARD auth type 30 credential request. When detected, Meta keys are remapped to Super (Command key compatibility).

View this document on GitHub

Phantom-WG: Build a Censorship-Resistant WireGuard VPN on Your Own Server

Rıza Emre ARAS — Mon, 09 Feb 2026 13:13:11 +0000

What is Phantom-WG?

Your Server. Your Network. Your Privacy.

Phantom-WG is a modular tool for setting up and managing WireGuard VPN infrastructure on your own server.
Beyond basic VPN management, it provides censorship-resistant connections, multi-layer traffic routing, and advanced privacy scenarios.

Module / Usage Scenario	Description
Core	Client management, cryptographic key generation, automatic IP allocation, and service control
Ghost	Stealth mode that masks WireGuard traffic over WSS using wstunnel, bypassing DPI systems
Multihop	Traffic routing and exit chaining through external WireGuard servers
MultiGhost	Combination of Ghost and Multihop; maximum privacy and censorship resistance

Note: Phantom-WG is a configuration orchestration tool; it automates the configuration steps you would otherwise perform manually on your server. It does not include any web interface or externally exposed attack surface.

Reza's Story

Reza is a software developer living in Tehran. He works remotely for two different companies:

NovaBridge — A Fin-Tech company based in San Francisco. Reza works here as a Backend Developer.
MapleSoft — A SaaS company based in Toronto. Reza contributes here as a DevOps Engineer.

Reza, NovaBridge, and MapleSoft are fictional names used to strengthen the narrative.

Both companies use WireGuard configurations for access to their development environments. A WireGuard tunnel is a fundamental requirement in Reza's daily workflow to connect to CI/CD pipelines, internal services, and staging environments.

However, Iran has an advanced internet filtering and censorship infrastructure. DPI systems operating at the national gateways detect and block known VPN protocols, including WireGuard, through signature analysis, behavioral fingerprinting, and packet size correlation.

This situation directly affects Reza's access to his work environments.

Before Phantom-WG: Complex and Fragile Solutions

Reza tried various methods to connect to the NovaBridge and MapleSoft environments:

V2Ray / VMess / VLESS
SSH Tunneling
Shadowsocks
Proxy Chains

Each method brought either complex configuration, additional tool dependencies, or connection instability. Keeping the connectivity infrastructure running before connecting to NovaBridge or MapleSoft each day had become a job in itself.

Meeting Phantom-WG

When Reza discovered Phantom-WG, his scenario changed fundamentally.

Reza receives his payments from the companies he works for through crypto and alternative payment channels, and keeps his assets on a local exchange. This gives him the ability to purchase international services.

He rented a VPS from a provider in Turkey with crypto payment:

Debian 13 installed
Public IPv4 address
Turkey location — Low latency to Iran, direct connectivity to Europe and North America

🎰 Looking for a provider? If you can't decide which provider to go with, try Spin & Deploy — randomly select from privacy-focused, crypto-friendly VPS providers!

After installing Phantom-WG on this server, Reza's architecture took shape:

Ghost Mode — Tunnels WireGuard traffic over WSS using wstunnel through port 443 (HTTPS). DPI systems cannot distinguish this traffic from a standard web connection.
Multihop Exit: NovaBridge — Adds the San Francisco company's WireGuard configuration as an exit. One command to switch to the development environment.
Multihop Exit: MapleSoft — Adds the Toronto company's WireGuard configuration as an exit. Switching between environments takes a single command.
Direct Exit — When Multihop is disabled, traffic exits through Turkey to the internet. A standard Turkey-exit connection without WireGuard traffic being detected.

Installation

curl -sSL https://install.phantom.tc | bash

For configuration and usage details:

Resource	Link
GitHub	github.com/ARAS-Workspace/phantom-wg
Documentation	docs.phantom.tc
Website	www.phantom.tc

Reza's Internet Traffic Flow

Full architecture:

Reza's traffic flows from Tehran to the Phantom-WG server in Turkey, and from there to the target environments. But how does he switch between these environments in his daily work?

Who is it For?

Remote developers who, like Reza, need reliable access to company/organization VPNs
Privacy-focused users looking for a self-hosted solution without relying on third-party VPN providers
Users focused on core functionality who want to manage VPN traffic through their own infrastructure, without multi-user panels
Activists, journalists, and advocates who need communication security

License

Phantom-WG is open source under the AGPL-3.0 license.

WireGuard is a registered trademark of Jason A. Donenfeld. This project is not affiliated, associated, or endorsed by WireGuard.

Support

Phantom-WG is an open-source project. If you'd like to support the project:

Bitcoin (BTC):

bc1qnjjrsfdatnc2qtjpkzwpgxpmnj3v4tdduykz57

Monero (XMR):

84KzoZga5r7avaAqrWD4JhXaM6t69v3qe2gyCGNNxAaaJgFizt1NzAQXtYoBk1xJPXEHNi6GKV1SeDZWUX7rxzaAQeYyZwQ

Phantom-WG: Kendi Sunucunuzda Sansüre Dirençli WireGuard VPN Kurun

Rıza Emre ARAS — Mon, 09 Feb 2026 13:11:38 +0000

Phantom-WG Nedir?

Kendi Sunucun. Kendi Ağın. Kendi Gizliliğin.

Phantom-WG, kendi sunucunuzda WireGuard VPN altyapısı kurmanızı ve yönetmenizi sağlayan modüler bir araçtır.
Temel VPN yönetiminin ötesinde; sansüre dayanıklı bağlantılar, çok katmanlı trafik aktarımı ve gelişmiş gizlilik senaryoları sunar.

Modül / Kullanım Senaryosu	Açıklama
Core	İstemci yönetimi, kriptografik anahtar üretimi, otomatik IP tahsisi ve servis kontrolü
Ghost	wstunnel ile WireGuard trafiğini WSS üzerinden maskeleyerek DPI sistemlerini atlayan hayalet modu
Multihop	Harici WireGuard sunucuları üzerinden trafik aktarımı ve çıkış noktası zincirleme
MultiGhost	Ghost ve Multihop'un birleşimi; maksimum gizlilik ve sansür dayanıklılığı

Not: Phantom-WG bir konfigürasyon orkestrasyon aracıdır; sunucunuz üzerinde manuel olarak yapacağınız konfigürasyon adımlarını uygulayarak otomatize eder. Herhangi bir web arayüzü veya dışarıya açık saldırı yüzeyi bulundurmaz.

Reza'nın Hikayesi

Reza, Tahran'da yaşayan bir yazılım geliştiricisi. İki farklı şirkette uzaktan çalışıyor:

NovaBridge — San Francisco merkezli bir Fin-Tech şirketi. Reza burada Backend Developer olarak çalışıyor.
MapleSoft — Toronto merkezli bir SaaS şirketi. Reza burada DevOps Engineer olarak katkıda bulunuyor.

Reza, NovaBridge ve MapleSoft anlatımı güçlendirmek için kullanılan kurgusal isimlerdir.

Her iki şirket de geliştirme ortamlarına erişim için WireGuard konfigürasyonları kullanıyor. CI/CD süreçlerine, dahili servislere ve staging ortamlarına bağlanabilmek için WireGuard tüneli, Reza'nın günlük iş akışında temel bir gereksinim.

Ancak İran, gelişmiş internet filtreleme ve sansür altyapısına sahip. Ulusal ağ geçitlerinde çalışan DPI sistemleri, WireGuard
dahil bilinen VPN protokollerini imza analizi, davranışsal parmak izi ve paket boyutu korelasyonu yöntemleriyle tespit
edip engelliyor.

Bu durum, Reza'nın çalışma ortamlarına erişimini doğrudan etkiliyor.

Phantom-WG Öncesi: Karmaşık ve Kırılgan Çözümler

Reza, NovaBridge ve MapleSoft ortamlarına bağlanabilmek için çeşitli yöntemler denedi:

V2Ray / VMess / VLESS
SSH Tünelleme
Shadowsocks
Proxy Zincirleri

Her yöntem ya karmaşık yapılandırma, ya ek araç bağımlılığı, ya da bağlantı kararsızlığı getiriyordu. Her gün NovaBridge veya MapleSoft'a bağlanmadan önce altyapıyı ayakta tutmak başlı başına bir iş haline gelmişti.

Phantom-WG ile Tanışma

Reza, Phantom-WG'yi keşfettiğinde senaryosu kökten değişti.

Reza, çalıştığı şirketlerden ödemesini kripto ve alternatif ödeme kanalları aracılığıyla alıyor ve varlığını yerel bir borsada tutuyor. Bu da ona uluslararası hizmet satın alma imkanı tanıyor.

Türkiye'de bulunan bir sağlayıcıdan kripto ödeme yaparak bir VPS kiraladı:

Debian 13 kurulu
Public IPv4 adresine sahip
Türkiye lokasyonu — İran'a düşük gecikme süresi, Avrupa ve Kuzey Amerika'ya doğrudan bağlantı

🎰 Sağlayıcı mı arıyorsunuz? Hangi sağlayıcıyı seçeceğinize karar veremediyseniz Spin & Deploy aracını deneyin — gizlilik odaklı, kripto dostu VPS sağlayıcıları arasından rastgele seçim yapın!

Phantom-WG'yi bu sunucuya kurduktan sonra Reza'nın mimarisi şöyle oluştu:

Ghost Mode — wstunnel ile WireGuard trafiğini WSS üzerinden tünelleyerek port 443'ten (HTTPS) geçiriyor. DPI sistemleri bu trafiği standart bir web bağlantısından ayırt edemiyor.
Multihop Exit: NovaBridge — San Francisco'daki şirketin WireGuard konfigürasyonunu exit olarak ekliyor. Geliştirme ortamına tek komutla geçiş.
Multihop Exit: MapleSoft — Toronto'daki şirketin WireGuard konfigürasyonunu exit olarak ekliyor. Ortamlar arası geçiş tek komut.
Doğrudan Çıkış — Multihop devre dışıyken trafik Türkiye üzerinden internete çıkıyor. WireGuard trafiği tespit edilmeden standart bir Türkiye çıkışlı bağlantı.

Kurulum

curl -sSL https://install.phantom.tc | bash

Yapılandırma ve kullanım detayları için:

Kaynak	Bağlantı
GitHub	github.com/ARAS-Workspace/phantom-wg
Dokümantasyon	docs.phantom.tc
Web Sitesi	www.phantom.tc

Reza'nın İnternet Trafik Akışı

Tam akış mimarisi:

Reza'nın trafiği Tahran'dan Türkiye'deki Phantom-WG sunucusuna, oradan hedef ortamlara ulaşıyor. Peki günlük çalışmasında bu ortamlar arasında nasıl geçiş yapıyor?

Kimler İçin?

Reza gibi şirket/organizasyon VPN'lerine güvenilir erişim ihtiyacı olan uzaktan çalışan geliştiriciler
Üçüncü taraf VPN sağlayıcılarına bağımlı olmak istemeyen self-hosted çözüm arayan gizlilik odaklı kullanıcılar
VPN trafiğini kendi altyapısı üzerinden yönetmek isteyen, çoklu kullanıcı paneline değil temel fonksiyonlara odaklı kullanıcılar
İletişim güvenliğine ihtiyaç duyan aktivistler, gazeteciler ve fikir savunucuları

Lisans

Phantom-WG, AGPL-3.0 lisansı altında açık kaynak olarak sunulmaktadır.

WireGuard, Jason A. Donenfeld'in tescilli ticari markasıdır. Bu proje WireGuard ile bağlantılı, ortaklı veya onaylı değildir.

Destek

Phantom-WG açık kaynak bir projedir. Projeyi desteklemek isterseniz:

Bitcoin (BTC):

bc1qnjjrsfdatnc2qtjpkzwpgxpmnj3v4tdduykz57

Monero (XMR):

84KzoZga5r7avaAqrWD4JhXaM6t69v3qe2gyCGNNxAaaJgFizt1NzAQXtYoBk1xJPXEHNi6GKV1SeDZWUX7rxzaAQeYyZwQ