Host API

Each running VM exposes a Unix domain socket on the host for programmatic access to VM operations. This enables custom integrations and scripted automation.

Overview

When a VM starts, the GhostVMHelper process creates a Unix socket at:

~/Library/Application Support/GhostVM/api/<VMName>.GhostVM.sock

The socket name is derived from the VM name (e.g. a VM named “dev” gets dev.GhostVM.sock). Any process on the host can connect to this socket to query or control the VM.

Wire Protocol

The Host API uses standard HTTP/1.1 over the Unix socket. Send a normal HTTP request and read an HTTP response.

Request format
GET /health HTTP/1.1
Host: localhost
Content-Length: 0
Response format
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 15

{"status":"ok"}

Any HTTP client that supports Unix domain sockets works — curl --unix-socket, Python's requests_unixsocket, or a raw socket connection.

Endpoints

All requests are proxied through the vsock connection to the GhostTools agent running inside the guest.

MethodPathDescription
GET/healthCheck if the guest agent is reachable
GET/api/v1/clipboardGet guest clipboard contents
POST/api/v1/clipboardSet guest clipboard contents
GET/api/v1/filesList files queued by the guest
DELETE/api/v1/filesClear the guest file queue
POST/api/v1/openOpen a path in the guest Finder
POST/api/v1/execExecute a shell command in the guest
GET/api/v1/fs?path=<dir>List directory contents in the guest
GET/api/v1/appsList running applications in the guest
POST/api/v1/apps/launchLaunch an app by bundle ID
POST/api/v1/apps/activateActivate (bring to front) an app by bundle ID
POST/api/v1/apps/quitQuit an app by bundle ID
GET/api/v1/apps/frontmostGet the frontmost application's bundle ID

Example Usage

You can interact with the Host API using any Unix socket HTTP client. Here is an example using curl:

Check health with curl
curl --unix-socket ~/Library/Application\ Support/GhostVM/api/dev.GhostVM.sock \
  http://localhost/health
Run a command in the guest
curl --unix-socket ~/Library/Application\ Support/GhostVM/api/dev.GhostVM.sock \
  -X POST -H "Content-Type: application/json" \
  -d '{"command":"uname","args":["-a"]}' \
  http://localhost/api/v1/exec

Or with a simple Python script:

Python example
import socket, os, json

sock_path = os.path.expanduser(
    "~/Library/Application Support/GhostVM/api/dev.GhostVM.sock"
)

s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(sock_path)

request = "GET /health HTTP/1.1\r\nHost: localhost\r\nContent-Length: 0\r\n\r\n"
s.sendall(request.encode())

response = b""
while True:
    chunk = s.recv(4096)
    if not chunk:
        break
    response += chunk

print(response.decode())
s.close()

Connection Lifecycle

Each connection is single-request: send one request, read one response, then the connection is closed by the server. Open a new connection for each subsequent request.
GhostToolsArchitecture