animawake docs

Guides

Desktop app setup

Download and install the desktop app on macOS, Windows, or Linux, pair it with your workspace, and deploy an entity to it.

This guide pairs a computer with your workspace as a device. Read Devices and the desktop app first to decide whether you need one.

#Requirements

  • macOS on Apple Silicon or Intel, Windows, or Linux (x86_64).
  • The command-line agent for the engine your entity uses: Claude Code for claude, or Codex for codex. Hermes entities are provisioned by the app. See Engines.
  • For the Voice Server add-on: an NVIDIA GPU with CUDA and at least 6 GB of memory.

#1. Download

  1. In the portal, open Devices in the sidebar.
  2. Choose the download link. The download page (/<workspace>/players/download) detects your system and offers the matching build. Use Show other platforms for the rest.
System File Install
macOS, Apple Silicon .dmg (aarch64) Open it and drag the app to Applications.
macOS, Intel .dmg (x86_64) Open it and drag the app to Applications.
Windows setup.exe Run the installer.
Linux .AppImage Make it executable with chmod +x, then run it.

The macOS builds are signed. The Windows installer is not signed yet, so Windows may show Windows protected your PC. Click More info, then Run anyway.

#2. Sign in and pair

  1. Open the desktop app and click Sign in with Google. Use the same account you use in the portal.
  2. The app registers the computer as a device in your workspace and starts syncing.
  3. If the app shows that the device is awaiting approval, open Devices in the portal and accept the new device. You can name it there.

The device now appears on the Devices page. It shows as online once its first heartbeat arrives, within a minute.

If you own more than one workspace, a new device joins the workspace you created first.

#3. Deploy an entity

  1. On the Devices page, open the device's panel.
  2. Choose Deploy Entity and pick the entity.

The app fetches the entity's key and starts it. The entity's Chat tab now works while the device is online.

#4. Optional add-ons

The app's Add-ons section installs optional services:

Add-on What it does Needs
Voice Server Speaks the entity's chat replies aloud. CUDA with at least 6 GB of GPU memory
Qwen TTS Local text-to-speech with voice cloning. At least 4 GB of GPU memory

See Voice.

#Keep it running

  • Leave the app running for scheduled work and chat. Closing it takes the device offline.
  • Signing out of the portal signs the desktop app out as well. Sign in again in the app afterward.
  • Updates install automatically. See Updates.

#Troubleshooting

  • "Windows protected your PC": expected on the unsigned Windows build. Click More info, then Run anyway.
  • The device does not appear in the portal: make sure you signed in to the app with the same Google account as the portal, and that the computer can reach api.animawake.com. If you own several workspaces, check the one you created first.
  • The device shows offline: the app must be running. Devices count as offline six minutes after the last heartbeat.
  • Chat says the device is offline: deploy the entity to a device that is online, or start the app on the device it is deployed to.
  • Linux does not update: run the AppImage from a folder you can write to, or download the new version from the Devices page.
  • An entity will not start on the device: check that the engine's command-line agent (claude or codex) is installed and signed in on that computer.