Desktop app

Clowld Space Desktop is available for macOS, Windows, and Linux. It uses the same account and workspace data as the web app, but it manages the daemon on your machine automatically and keeps a separate set of tabs for each workspace.

Desktop and web

Web is more convenient for a quick look or on a shared computer.

You can be signed in to both at the same time. As long as they connect to the same Clowld Space service, the data they show is shared.

Installation

Pick the installer that matches your OS and CPU architecture from the Clowld Space downloads page:

After installing, select Continue in browser. An existing browser session authorizes Desktop and returns immediately; otherwise the web page offers email or Google sign-in. Desktop then starts the daemon, detects local AI coding tools, and installs the official clowld command under ~/.clowld-space/bin/.

Desktop tabs

Desktop saves tabs per workspace. For example, if you open three issues in workspace A and switch to workspace B, you see B's own tabs; switch back to A and the three earlier tabs are still there.

A given resource opens only once in the current workspace. Tabs can be reordered, pinned, and closed, and each keeps its own forward/back history and scroll position. Clicking or pasting an app link for this deployment opens it directly in a tab instead of jumping to the browser.

Logging out clears every tab saved on the machine, so the next person to sign in never sees pages left behind by the previous account.

Built-in daemon

After sign-in, Desktop creates a dedicated CLI profile for the current Clowld Space service and uses it to start the daemon. The profile lives at:

~/.clowld-space/cli/profiles/desktop-<host>/

For the same service, the terminal default profile follows the current Desktop account, while the terminal and Desktop daemon still use separate credentials. Desktop asks before switching that account and removes only the terminal credential it created when you sign out. A default profile for another service and every named profile are left unchanged.

While management is active, clowld daemon status/start/stop/restart on the default profile inspects or wakes Desktop instead of creating a second terminal daemon. Business commands such as clowld issue list still call the backend API directly and do not require Desktop to be running. Advanced users can run an independent daemon with an explicit named profile, for example clowld --profile self-host daemon start.

You can check runtime status and logs in Desktop's settings. If a tool isn't detected, first confirm it runs in a regular terminal and is logged in, then restart Desktop's daemon.

Updating Desktop

Auto-update is on by default. The app checks for and downloads new versions in the background; once a download finishes you can restart to install immediately or let it install on the next quit. You can also turn off automatic checks or check for new versions manually under Settings → Updates.

The official terminal CLI managed by Desktop is updated together with Desktop. In this mode, clowld update asks Desktop to check for an update instead of maintaining a separate terminal-daemon version.

Updates are distributed per OS and CPU architecture:

• Windows arm64 and macOS x64 (Intel) each use their own update feed;
• all other architectures use the default feed;
• the app matches the update feed automatically — no manual selection needed;
• on Linux, auto-update only works for .AppImage; update .deb and .rpm by installing a new package over the old one;
• if auto-update fails, likewise install over the top with the matching installer from the downloads page.

Uninstalling Desktop

On Windows, the uninstaller asks whether to keep the Desktop-installed CLI as an independent CLI or remove it. Removal is allowed only when both the canonical path and checksum match the management record. Neither choice deletes named profiles, configuration, or workspace data. On macOS and Linux, removing Desktop makes the existing CLI fall back to independent mode.

Connecting to a self-hosted instance

Desktop connects to Clowld Space by default. To connect to a self-hosted instance, create desktop.json inside the .clowld-space directory of your home directory:

These are the default locations — if your home directory has been moved or redirected, use its actual path.

{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com"
}

apiUrl is the backend's public address; it is required and must use http or https. The other two URLs can be omitted — Desktop derives them automatically:

• wsUrl: swaps the apiUrl scheme to ws or wss and appends /ws to the path;
• appUrl: strips the api. prefix when the host starts with api. and has at least three labels (api.example.com → example.com); otherwise it stays the same as apiUrl.

Usually apiUrl alone is enough. Override explicitly only when the derivation doesn't match your deployment; the three common cases:

• the web app and the API are on different domains;
• WebSocket is deployed separately;
• the host doesn't fit the prefix-stripping convention (two-label hosts like api.local keep their prefix).

{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com",
  "appUrl": "https://app.example.com",
  "wsUrl": "wss://ws.example.com/socket"
}

Restart Desktop after saving — the file is read once at startup. The two failure modes look different, which is the fastest way to tell them apart:

• File not found (wrong directory, or a filename that isn't exactly desktop.json) — Desktop uses the default Cloud configuration and shows no error. So if Desktop still reports a Cloud address and no configuration error, the file is not where Desktop is looking.
• File found but invalid JSON, version, or URLs — Desktop shows a configuration error and does not fall back to Cloud.

Delete the file and restart to return to the default Cloud configuration.

Windows: check the filename and encoding

Two Windows editor defaults silently produce a file Desktop can't use:

• Notepad appends .txt. Saving as desktop.json can produce desktop.json.txt, which Desktop treats as not found. Turn on file name extensions in Explorer, or pick All files in the save dialog. To see the real filename, run Get-ChildItem "$env:USERPROFILE\.clowld-space" -Filter "desktop.json*" in PowerShell — the Name column must read exactly desktop.json.
• PowerShell redirection writes UTF-16 or a BOM. > desktop.json and Out-File can produce an encoding that fails to parse, which surfaces as a configuration error.

To avoid both, create the file from PowerShell in one step:

$dir = "$env:USERPROFILE\.clowld-space"
New-Item -ItemType Directory -Force $dir | Out-Null
$json = @'
{
  "schemaVersion": 1,
  "apiUrl": "https://api.example.com"
}
'@
[System.IO.File]::WriteAllText("$dir\desktop.json", $json)

Windows Defender flags Clowld Space as a virus

Symptom: Windows Security reports a threat such as Trojan:Script/Wacatac.B!ml and quarantines a file inside the Desktop installation. The affected item is normally the bundled CLI, not the app executable:

C:\Users\<you>\AppData\Local\Programs\Clowld Space\resources\app.asar.unpacked\resources\bin\clowld.exe

This is a false positive. The !ml suffix means the verdict came from Defender's machine-learning heuristics rather than a malware signature. Clowld Space's Windows builds are not Authenticode code-signed yet, and a freshly published unsigned binary that starts background processes and opens network connections is exactly the profile those heuristics score as suspicious. Every Windows artifact is built by GitHub Actions from the public source in this repository.

Verify it yourself — each GitHub release publishes a checksums.txt covering every CLI archive:

Get-FileHash .\clowld-cli-<version>-windows-amd64.zip -Algorithm SHA256

Open the public Clowld CLI release manifest, follow its checksums.txt asset URL, and compare the matching hash.

How to fix:

1. Restore the quarantined file — Windows Security → Virus & threat protection → Protection history → select the Clowld Space item → Actions → Restore.

2. Add an exclusion so it isn't quarantined again — Virus & threat protection → Manage settings → Exclusions → Add an exclusion → Folder, and add both:

   • %LOCALAPPDATA%\Programs\Clowld Space
   • %APPDATA%\Clowld Space

   Both paths matter: when the bundled CLI goes missing, Desktop downloads a replacement into %APPDATA%\Clowld Space\bin, so excluding only the install folder leaves you in a loop where the replacement gets quarantined too.

3. Report the false positive to Microsoft at Microsoft Security Intelligence — submit a file, choosing Software developer and Incorrectly detected as malware. That is what gets the detection withdrawn for every user, usually within a few days.

Next steps

• Quickstart — the first-connection flow.
• Daemon and runtimes — how the built-in daemon works.
• Troubleshooting — diagnosing connection issues.

Appearance and keyboard shortcuts

In Settings → Preferences, choose light, dark or system appearance. The Translucent sidebar switch appears only in Desktop windows that support the native material; it is not a Web setting and does not apply to separate issue windows.

In Settings → Keyboard shortcuts, search for an action, press a new combination, or restore defaults. Custom shortcuts are saved on this device. Defaults use Cmd on macOS and Ctrl elsewhere: Cmd/Ctrl+B toggles the left sidebar; Cmd/Ctrl+/ toggles the current detail page’s right sidebar. These sidebar shortcuts do not fire while typing in an editable field.

Desktop additionally uses Cmd/Ctrl+1 through 8 to select the corresponding tab in the current workspace, and Cmd/Ctrl+9 for its last tab. An absent tab position does nothing.