Desktop, Server, or Core CLI: which to use
Wayland runs in three shapes. They share the same underlying agent engine and the same model providers, but each one serves a different context.
| Shape | What it is | Best for |
|---|---|---|
| Desktop app | Graphical Electron app for Mac, Windows, and Linux. | Day-to-day conversational work, teams, channels, GUI settings. |
| Server (self-hosted) | Headless web server you deploy on a Linux box or VPS. | Always-on access from a phone or any browser, shared household/team setups. |
| Wayland Core CLI | Rust CLI and embeddable engine (wayland-core). | Scripting, CI, JSON stream embedding, terminal-native workflows. |
Desktop app
Section titled “Desktop app”The desktop app is the full graphical surface. It bundles the engine and wraps it in a point-and-click interface.
Use the desktop app when you:
- Want a GUI for chat, assistants, and settings.
- Are connecting messaging channels (Telegram, Slack, WhatsApp, and others). Channel pairing and routing live exclusively in the app.
- Want to run multi-agent teams with specialist sub-panels.
- Want the Scheduler, voice input/output, or image generation UI.
- Want to reach your conversations from a phone through Remote Access.
- Are not comfortable with a terminal.
The desktop app requires a supported OS (macOS, Windows, Linux) with a display. Download it at https://getwayland.com/download.
Server (self-hosted)
Section titled “Server (self-hosted)”The server is the same agent packaged as the getwayland npm module and run headless on a Linux box or VPS. You reach it from any browser or phone by scanning a QR code printed in the terminal at first boot.
Use the server when you:
- Want always-on AI without leaving your laptop open.
- Want to share a single Wayland instance with family members or a small team, each with their own login.
- Are deploying on a cloud VPS (DigitalOcean, Render, Hetzner, etc.).
- Want to pair your phone and control Wayland without the desktop app.
The server needs a Linux x64 machine with roughly 2 GB of RAM and Node 18 or newer. It does not support macOS or Windows as a host. The web UI it serves is responsive, so it works on phones.
See Run Wayland on a Server for the three-step setup.
Wayland Core CLI
Section titled “Wayland Core CLI”Wayland Core (wayland-core) is the open-source Rust engine exposed as a standalone command-line tool. It is the same engine the desktop app bundles, but without the GUI wrapper.
Use Wayland Core when you:
- Are scripting Wayland in a shell or CI pipeline.
- Want a one-shot prompt:
wayland-core "summarize this file" < input.txt. - Are embedding the engine in another program via the JSON stream protocol.
- Are running on a headless server with no browser and want a terminal UI.
- Want to drive Wayland from code using the host-integration API.
Wayland Core is available via npm (@ferroxlabs/wayland-core), Cargo, and GitHub Releases. See Install Wayland Core (CLI).
Comparison table
Section titled “Comparison table”| Capability | Desktop app | Server | Core CLI |
|---|---|---|---|
| Graphical chat interface | Yes | Web UI (browser) | TUI only |
| Channel integrations (Telegram, Slack, …) | Yes | Planned | No |
| Multi-agent teams | Yes | Planned | Via CLI commands |
| Scheduler and cron UI | Yes | Planned | wayland-core cron |
| Voice input and output | Yes | No | No |
| Image generation UI | Yes | Partial | No |
| Remote access (phone / browser) | Via Remote Access feature | Native | No |
| Scripting / CI | No | No | Yes |
| JSON stream embedding | No | No | Yes |
| One-shot shell prompts | No | No | Yes |
| Headless Linux deployment | No | Yes | Yes |
| Shared multi-user access | No | Yes | No |
| Config file shared | Yes | Partial | Yes |
How to decide
Section titled “How to decide”Start with the desktop app if you are not sure. It is the most complete surface and requires no server setup.
Add the server if you want always-on access or want your phone to reach Wayland from anywhere.
Add the Core CLI when you have a specific automation job: a shell script, a CI step, or an embedding project.
All three can coexist. The desktop app, the server, and the Core CLI all read from compatible config formats, so a workflow you build in the desktop app can be driven from the CLI with the same provider keys.