Client/Server Mode
/glyphmap-client-server-modeThe default: a local database and dashboard, plus watchers for initialized projects. A straightforward setup for one development machine.
THE LOCAL GUIDE
Install it, connect your agent and keep your projects separate.
Install the universal extension, then run Glyphmap: Init. For a native installation, run these commands from your project folder after starting the shared server:
glyphmap-server start
glyphmap init
glyphmap service start
glyphmap context refresh
glyphmap context get
glyphmap statusInitialization refuses to replace an existing project binding. Open the local dashboard at http://127.0.0.1:47770/; on your first visit, create a password with at least eight characters. Native start and stop do not require systemd or a permanently open terminal.
Stop only a project's watcher with glyphmap service stop. Stop the shared local backend with glyphmap-server stop. Both preserve retained user data.
/glyphmap-client-server-modeThe default: a local database and dashboard, plus watchers for initialized projects. A straightforward setup for one development machine.
/glyphmap-client-modeProject watchers connect to your configured local or HTTPS LAN server. No local backend or dashboard listener starts.
/glyphmap-server-modeRun the database and dashboard on a machine in your environment. Project watchers and agent hooks stay off on that installation.
Use these slash commands in supported agent hosts, or prefix them with glyphmap in a terminal. /glyphmap-mode reports the current selection. The equivalent commands are available in VS Code.
On the server, configure the listener and TLS in its private config/config.json. Non-loopback listeners require TLS. Set up the dashboard password locally, then create a separate client key for each trusted machine in Settings > LAN access.
On a client, use Glyphmap: Configure Local or LAN Server or edit only these fields in its existing private configuration, preserving other settings. This is a template: replace the angle-bracket entries before saving. Use the actual HTTPS address and listener port of your server; Glyphmap does not create a DNS name for it:
{
"mode": "client",
"serverUrl": "<paste your server's full HTTPS URL here>",
"serverToken": "<your client access key>",
"serverCaFile": null
}Use a trusted certificate covering the actual address clients use. If it uses your own certificate authority, replace serverCaFile's null with the real path to that CA certificate on the client. Do not disable certificate verification or put credentials in a URL. A remote connection failure remains an error; Glyphmap does not fall back to a different local database.
The extension installs Glyphmap-owned native hooks and supported MCP settings while preserving your custom hooks, commands and project instructions. The host's normal review and trust steps remain yours.
Run glyphmap mcp from a bound project to expose native context, status, preflight, receipts, lifecycle and verification tools. Ask for scoped project context before broad rediscovery, check live files when editing, and preserve returned uncertainty and policy outcomes.
Observe and Scaffold modes are advisory. Enforcement applies to tools/events the host actually exposes; an MCP connection alone does not intercept every action. Glyphmap never expands the user's authorization or replaces the host's approval system.
Read the agent guide >~/Library/Application Support/Glyphmap%LOCALAPPDATA%\Glyphmap~/.local/share/glyphmapRuntime settings are in the private application directory's config/config.json. Per-project bindings stay in .glyphmap/config.json. Configure runtime settings in the file, not through arguments or environment overrides. Never commit or publish credentials.
The database is separate from installed binaries. Updates use transactional schema migrations, preserving records rather than replacing the database. Project and conversation scope rules continue to apply; a self-hosted server owner is trusted with the data it stores.
Your selected model or agent host may send prompts to its own provider. Keeping Glyphmap local does not make that separate service local.
Use the same OS user who owns your Glyphmap data. Client Mode does not need a local backend. These steps start the shared server, not every project watcher; initialized watchers start when supported agent or editor activity needs them.
brew services start glyphmapThis starts the server now and registers it to start when you sign in after a restart. Stop it and remove that login registration with:
brew services stop glyphmapThe extension starts its service when an initialized project is used. To start independently at sign-in, create a LaunchAgent for the actual server installed by the extension:
mkdir -p "$HOME/Library/LaunchAgents"
cat > "$HOME/Library/LaunchAgents/com.glyphmap.server.plist" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>com.glyphmap.server</string>
<key>ProgramArguments</key><array><string>$HOME/Library/Application Support/Glyphmap/bin/glyphmap-server</string><string>service</string></array>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
</dict></plist>
EOF
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.glyphmap.server.plist"Choose one startup method. To remove this LaunchAgent:
launchctl bootout "gui/$(id -u)/com.glyphmap.server"
rm "$HOME/Library/LaunchAgents/com.glyphmap.server.plist"systemctl --user daemon-reload
systemctl --user enable --now glyphmap-server.serviceThe package supplies this user service. It starts with your user session. To start at boot before sign-in, an administrator can enable lingering for your user:
sudo loginctl enable-linger "$(id -un)"To stop automatic startup:
systemctl --user disable --now glyphmap-server.serviceOn Linux without systemd, use glyphmap-server start or your existing user-session startup manager. The native start command detaches; it does not create a boot registration.
From normal PowerShell, register a task under your own account. For a native or winget installation, first confirm glyphmap-server.exe is on your command path:
$server = (Get-Command glyphmap-server.exe).Source
$action = New-ScheduledTaskAction -Execute $server -Argument 'start'
$trigger = New-ScheduledTaskTrigger -AtLogOn
$principal = New-ScheduledTaskPrincipal -UserId ([Security.Principal.WindowsIdentity]::GetCurrent().Name) -LogonType Interactive -RunLevel Limited
Register-ScheduledTask -TaskName 'Glyphmap Server' -Action $action -Trigger $trigger -Principal $principal -Description 'Start the current user Glyphmap server at sign-in'For an extension-only installation, use this first line instead, then the remaining task commands:
$server = Join-Path ([Environment]::GetFolderPath("LocalApplicationData")) "Glyphmap\bin\glyphmap-server.exe"The task starts the server when you sign in after a restart, not before sign-in. It uses the same private profile and avoids a separate LocalSystem database. To remove it:
Unregister-ScheduledTask -TaskName 'Glyphmap Server' -Confirm:$falseThe local extension upgrades registered workspaces on activation. Glyphmap: Upgrade Local Installation retries it; the native equivalent is:
glyphmap /glyphmap-upgradeThe migration preserves project IDs, local retained data, Observe/Scaffold behavior and custom integration settings. It replaces the old hosted binding and removes activation and subscription requirements without contacting the previous hosted API.
Cloud-only records are not automatically downloaded. Arrange an export/import before retiring an old hosted installation. Do not delete your existing .glyphmap directory to upgrade. Older distributed-network experiment profiles are a different product and are not imported.