Quick start

For a first MOVO deployment, the complete Docker Compose stack is the preferred path. The root docker-compose.yml starts the employee Web, admin console, DSH Runtime, document processing, databases, cache, vector store and unified gateway.

Use ./movo as the recommended entry point. It is a lightweight wrapper around Docker Compose that validates Docker, starts the full stack, waits for health checks and prints the initial setup URL.

1. Prerequisites

Install Git, Docker Engine or Docker Desktop, and Docker Compose v2. Make sure Docker is running:

docker compose version
docker info

The first build downloads container images, project dependencies and document-processing models. Completion time depends on network and machine performance.

2. Get and start MOVO

git clone https://github.com/himovo/movo.git
cd movo
chmod +x movo
./movo up

./movo is intended for Bash environments on macOS, Linux or Windows WSL.

The launcher validates Docker, generates persistent random internal secrets, starts the complete stack, waits for health checks and prints:

http://localhost:3000/admin/setup

The native Compose command is also supported:

docker compose up -d

From Windows PowerShell without WSL, run the native Compose command and open the setup URL manually after the services become ready.

For a first deployment, prefer ./movo up because it also waits for readiness, handles compatibility migration and tells you what to do next.

3. Complete initial setup

Open http://localhost:3000/admin/setup. The current setup wizard contains:

Deployment check

Verify MongoDB, Redis, persistent storage, Chat API with DSH Runtime, document processing and Weaviate are ready.

Organization and accounts

Configure the organization, initial administrator and employee accounts, organization and employee token quotas, quota period and timezone. Administrator and employee usernames must be different.

Base chat model

Configure the default chat provider, model name, Base URL and API Key. This model is required and must pass its connection test. The API Key is encrypted before storage and does not need to be hardcoded or preloaded as a fixed environment variable.

Additional models (optional)

• Embedding for enterprise-knowledge vector learning and semantic retrieval.
• Rerank to improve knowledge-retrieval ordering.
• Vision for images, screenshots, scans and chart understanding.
• Image for generating illustrations and visual assets.

Skipping these models does not block basic text chat, but the related capability remains unavailable or uses an available fallback path.

Web search (optional)

Select and test a web-search provider. You can skip it and continue using ordinary chat, while web search and multi-source research remain unavailable.

Complete

The completion page provides the employee Web, admin console and MOVO Desktop enterprise-service URLs, plus a downloadable connection file.

4. Sign in and verify

Entry	URL	Purpose
Employee Web	http://localhost:3000/	Chat, research, knowledge, files and content generation
Admin console	http://localhost:3000/admin/	Organization, accounts, models, knowledge, Skills, tools and governance
Setup wizard	http://localhost:3000/admin/setup	First-time enterprise initialization only

Recommended first checks:

1. Send an ordinary chat request from the employee Web.
2. Confirm the default model is active in the admin console.
3. If Embedding is configured, upload a test document, wait for learning to finish and ask an internal-knowledge question.
4. If web search is configured, run a task that requires current public information.

5. Connect MOVO Desktop (optional)

Docker Compose deploys the MOVO backend and Web products. Chat, research, knowledge and content generation are available directly in the Web client. Browser Agent and Code Agent are available only in MOVO Desktop because they need access to your local browser, code directories, project terminal and Git workspace.

Download and install

1. Open the MOVO Desktop download page.
2. Open Apple menu > About This Mac and check Chip or Processor, then select the Apple silicon or Intel build.
3. Open the downloaded .dmg, drag MOVO into Applications and launch it. The installer is Developer ID signed and Apple notarized.

Connect to your MOVO service

1. Complete the backend deployment and initial setup described in sections 2–3.
2. On the MOVO Desktop sign-in page or in Settings, enter the enterprise-service URL shown on the setup completion page.
3. Sign in with the employee account created during initial setup.

When Desktop and the MOVO backend run on the same computer, use:

http://localhost:3000

When the backend runs on another machine or cloud server, enter an IP address or HTTPS domain reachable from the Desktop computer. Do not use the server's own localhost address.

After connecting, Browser Agent uses the local Chromium instance managed by Desktop together with its authenticated sessions. Code Agent works in the local code Workspace selected in Desktop, with access to the project terminal and Git.

Desktop derives the backend API and local-Agent connections from the enterprise-service URL. You do not need to enter a separate WebSocket URL.

6. Change the port or use an enterprise domain

A local deployment does not require .env. To change the public port or canonical URL:

cp .env.example .env

MOVO_PORT=8080
PUBLIC_BASE_URL=https://ai.company.com

• MOVO_PORT controls the host's public port.
• PUBLIC_BASE_URL generates employee Web, admin and Desktop connection URLs.
• DNS, TLS certificates and the external reverse proxy remain the deployment environment's responsibility.

Configure model API Keys in setup or the admin console. Do not hardcode them or preload a fixed vendor-specific model secret.

7. Operations

./movo status
./movo logs
./movo logs chat-api
./movo logs admin-api
./movo logs document-api
./movo logs dsh-runtime-host
./movo restart
./movo down

./movo down preserves persistent volumes. After updating the source:

git pull
./movo up --build

Delete all data

./movo down -v deletes MOVO persistent volumes and initial setup state. Do not run it unless you intentionally want to reset the deployment.

8. Troubleshooting

If Docker is unavailable, start Docker Engine or Docker Desktop and run ./movo up again.

If services do not become ready:

./movo status
./movo logs

The initial document-processing image build can take time. Check the unhealthy service and its logs.

If port 3000 is already used, create root .env with MOVO_PORT=8080, run ./movo up, then open http://localhost:8080/admin/setup.

Setup is a one-time workflow. After completion, /admin/setup redirects to the admin login page by design.

9. Source development mode

Use source mode only when developing or debugging MOVO itself:

# Complete source-development stack (recommended)
./dev_dsh.sh

dev_dsh.sh starts the pinned DSH Runtime Host on port 8101, then invokes dev.sh to start the user Web, admin Web, APIs and document-processing services.

./dev.sh remains supported, but it starts only the platform services and does not start DSH Runtime Host. Use it by itself only when working on Web/API code or when a DSH Runtime Host is already available at DSH_RUNTIME_HOST_URL.

Source mode requires Node.js 22.19+ or 24+, pnpm, Python 3.10+, Redis and the module dependencies. It is not a replacement for the complete self-hosted Docker Compose deployment.