Skip to main content

Installation

From a bare machine to a running, signed-in NeoAgent service.

NeoAgent can run as a per-user background service on macOS, Windows, and Linux. Use a machine that remains online when automations, messaging, or remote access should keep working.

🚀 Install NeoAgent​

Run the repository installer. It clones NeoAgent directly from GitHub and requires Git, Node.js 20+, and npm for dependencies:

bash <(curl -fsSL https://raw.githubusercontent.com/NeoLabs-Systems/NeoAgent/main/install.sh)

The first run detects an existing, incomplete, or damaged installation and offers the appropriate status, resume, or repair action.

🧩 Choose a setup mode​

  • Quickstart is selected by default. It chooses a private data directory, free port, and per-user autostart, installs the working core, and continues to protected first-account creation.
  • Full setup covers installation and network choices, account ownership, providers, integrations, voice, and optional browser/media capabilities. Optional sections can be completed in the app after the core is running.

Equivalent CLI commands are:

neoagent setup --quick
neoagent setup --full
neoagent setup --resume

The configured port is preserved. New installations choose an available port, and the app receives the exact address from the setup engine. Nearby instances are advertised through _neoagent._tcp.local and verified with the setup handshake. Manual addresses are available under the advanced connection option.

🎬 First run​

  1. Create the first user account.
  2. Configure a hosted provider or local Ollama from the admin dashboard's AI Providers page, with neoagent env, or during neoagent setup.
  3. Select a model and send a message in Chat.
  4. Open Settings > Tool Permissions and review the approval policy before enabling browser, shell, file-write, desktop, or Android actions.

The first account requires the one-time claim generated by the local installer. The claim is short-lived, stored hashed by the server, and never placed in a normal URL. Each additional person should use a separate account.

Optional capabilities

Docker, browser isolation, voice, integrations, and media extraction are optional. Their absence does not block core setup or sign-in.

✅ Check the installation​

neoagent status
neoagent doctor
neoagent logs

status reports configuration, release channel, service state, and server health. doctor performs read-only structured checks. Automation can add --json; each output line follows the versioned setup event schema. Use logs from the machine hosting the selected NeoAgent instance.

➡️ Next steps​