Four products for working with your agents across your computer and a VM. Install the parts you need; Hermes is required for the Hermes plugin, not for every MCP client.

openalan.com · Discord: help and community · Latest Workspace release

The two plugins target one shared config spec for persona, voice, proactivity, and identity. That contract belongs in alans-way-agents; this repo supplies the app and computer-use service. The draft schema at shared/config.schema.json and Grok scaffold are pending agents PR #157; see product boundaries and shared config for implementation status. Existing Hermes package names (alans-way, alans-way-computer) are implementation components of product 3, not additional products.

Existing installs retain their labeled legacy connections during the security migration. New SSH trust requires administrator provisioning of separate broker and bot accounts; the old combined connection wizard is disabled. See the credential upgrade guide.

Setting up Workspace with a Hermes agent? Paste this prompt so it reads the full setup instructions:

Set up Alan's Workspace. Repo: https://github.com/capthvnsen/alans-way
Fetch https://raw.githubusercontent.com/capthvnsen/alans-way/main/docs/setup-prompt.md and follow the text block in it exactly. Do not modify Hermes. Never print secrets.

Install the desktop app on the computer you want to use with your agents. Chat and real Chromium tabs share a workspace; agents have named cursors and assigned tabs, and you can take control. A remote desktop viewer lets you watch or control your VM. Telegram chat uses your existing bot conversation; other agents keep their own chat clients.

• Mac (Apple Silicon): download, open the signed/notarized app, and follow setup. The installed bundle is /Applications/alans-way-localapp.app. Source installation: sh scripts/install-mac.sh from a clone of this repo.
• iOS: follow ios/README.md for Xcode builds or the beta tester guide for an invitation. This source tree does not provide a public App Store install link. Voice calls additionally need the mobile voice bridge on the existing Hermes gateway; normal chat and the viewer have their own setup.
• Existing Windows/Linux support: Windows download (unsigned; SmartScreen may require More info → Run anyway), or build on Linux x64 with a desktop session, systemd, Node 22.12+ and git. Desktop guide · installation paths

For a remote host, install Tailscale on both computers and use SSH over Tailscale. With the VM browser and router configured, lid-close handoff rebuilds browser work on the VM; waking retires the local copy, and Move back is manual. This does not migrate a live Chromium process. Sign-in transfer is controlled by Carry sign-ins and restricted to Tailscale; storage, upload, and approval limits are in the handoff guide.

For native Mac app control, grant Alan's Workspace (alans-way-localapp) Accessibility and Screen Recording in System Settings → Privacy & Security. Browser tabs need neither. Keep the app running for local computer use.

Desktop usage and development · macOS VM guest · Hermes setup guide

workspace-mcp is the product name for the shared Node computer-use server. It stays here, at desktop/scripts/browser-mcp.cjs, using supporting code in desktop/src/.

Install it on its own with Node 22.12+ (see the install guide for client snippets and health checks):

npm install -g github:capthvnsen/alans-way

Or use the copy bundled in the Mac app:

/Applications/alans-way-localapp.app/Contents/Resources/app/scripts/browser-mcp.cjs

Or prepare a source checkout with Node 24 (the development/CI version):

git clone https://github.com/capthvnsen/alans-way.git
cd alans-way/desktop
npm ci

Configure your client's stdio MCP server entry, replacing the absolute paths and agent ID:

{
  "mcpServers": {
    "workspace-mcp": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/alans-way/desktop/scripts/browser-mcp.cjs",
        "--bot-id", "YOUR_AGENT_ID"
      ]
    }
  }
}

The outer configuration shape depends on your client; stock Hermes uses mcp_servers. The installed connector requires Node 22.12+; development and CI use Node 24. The app (or a configured VM browser host) must be running. Keep the whole checkout/bundle: the script imports sibling modules and the MCP SDK. Give each agent its own ID. The connector reads the local private connection file; do not copy its token into client JSON or share it in issues.

This exposes cua_alans_way_* browser tools and workspace_computer_* native tools. A generic MCP client can connect without loading a Hermes plugin. Remote routing, VM failover, and remote-agent provisioning currently use scripts in alans-way-agents; follow the remote-agent guide for SSH over Tailscale and approvals. The optional Python companion CLI is a separate support tool, not this Node server.

Install on the server/VM running your existing stock Hermes gateway, not into the desktop app. Keep Hermes as the conversation owner. The Python plugin, computer-use provider, bundled skills, and setup scripts live in capthvnsen/alans-way-agents.

Start with its installation guide or paste this repo's setup prompt to your Hermes agent. The existing checkout-based install is:

git clone https://github.com/capthvnsen/alans-way-agents.git
cd alans-way-agents
./setup.sh --bot-id YOUR_NUMERIC_BOT_ID --mac-ssh [email protected]_TAILNET.ts.net --restart

This configures the gateway and may install services/restart it; review the install guide first. The default plugin paths are ~/.hermes/plugins/alans-way/ and ~/.hermes/plugins/alans-way-computer/; profiles may use a different HERMES_HOME. Install Workspace for a local browser and CU MCP for tools. The plugin supplies Hermes-specific hooks, check-ins, and routing; the shared spec defines persona, voice, proactivity, and identity for both plugin products.

Agent setup · multi-profile identity · updates

Use the Grok Bot skill + settings package in capthvnsen/alans-way-agents, plus a CU MCP connection to your Workspace/VM. Do not run the Hermes plugin installer as a Grok Bot package installer: Grok Bot cannot load Python Hermes plugins.

The existing connection path is documented in remote agents: provision the restricted SSH router on your VM, then in Grok Bot use Settings → Add a custom connector with the generated client JSON. That establishes computer use; it does not install the Grok skill/settings package.

Pending agents PR #157: the Grok Bot scaffold is at alans-way-grok-bot/ and the shared draft schema is at shared/config.schema.json. These are draft artifacts: native Grok Bot loading is unverified and the Hermes shared-config reader is not implemented. See implementation status.

Start with CONTRIBUTING.md, the directory/product map, and MIT licensing and dependency notices. Issues and PRs identify one or more of the four products using the product labels. App and CU MCP changes belong here; plugin and shared config changes belong in alans-way-agents.

Get help on Discord, visit openalan.com, or open an issue. Report vulnerabilities privately via SECURITY.md. Never post credentials, connection files, private addresses, or raw session logs.

All four Alan's Way products—Alan's Workspace, Alan's CU MCP, Alan's Plugin for Hermes, and Alan's Plugin for Grok Bot—are licensed under the MIT License. Copyright (c) 2026 Alex Hansen. The shared config spec and supporting code use MIT too. Third-party software retains its own licenses; see dependency notices and desktop distribution constraints.

Independent community project. Not affiliated with Nous Research or xAI.