Skip to content

quickstart.en.md

Latest commit

 

History

History
258 lines (180 loc) · 10.7 KB

quickstart.en.md

File metadata and controls

258 lines (180 loc) · 10.7 KB

Quick start

This section describes six ways to run CoPAW:

  • Option A — Script install: run on your machine with no Python setup required.
  • Option B — pip install: if you prefer managing Python yourself.
  • Option C — Desktop Application (Beta): download and run desktop app with no command-line required, suitable for users unfamiliar with terminals. See Desktop Application Guide.
  • Option D — ModelScope Studio: one-click cloud deploy, no local install needed.
  • Option E — Docker: use official images from Docker Hub (ACR also available for users in China); tags include latest (stable) and pre (PyPI pre-release).
  • Option F — Alibaba Cloud ECS: one-click deploy on Alibaba Cloud, no local install.

📖 Read Introduction first; after install see Console.

💡 After install & start: Before configuring channels, you can open the Console (http://127.0.0.1:8088/) to chat with CoPAW and configure the agent. When you're ready to chat in DingTalk, Feishu, QQ, etc., head to Channels to add a channel.

Option A: Script install

No Python required — the installer handles everything automatically using uv.

Step 1: Install

macOS / Linux:

curl -fsSL https://copaw.agentscope.io/install.sh | bash

Then open a new terminal (or source ~/.zshrc / source ~/.bashrc).

Windows (CMD):

curl -fsSL https://copaw.agentscope.io/install.bat -o install.bat && install.bat

Windows (PowerShell):

irm https://copaw.agentscope.io/install.ps1 | iex

Then open a new terminal (the installer adds CoPaw to your PATH automatically).

⚠️ Special Notice for Windows Enterprise LTSC Users

If you are using Windows LTSC or an enterprise environment governed by strict security policies, PowerShell may run in Constrained Language Mode, potentially causing the following issue:

  1. If using CMD (.bat): Script executes successfully but fails to write to Path

    The script completes file installation. Due to Constrained Language Mode, it cannot automatically update environment variables. Manually configure as follows:

    • Locate the installation directory:
      • Check if uv is available: Enter uv --version in CMD. If a version number appears, only configure the CoPaw path. If you receive the prompt 'uv' is not recognized as an internal or external command, operable program or batch file, configure both paths.
      • uv path (choose one based on installation location; use if step 1 fails): Typically %USERPROFILE%\.local\bin, %USERPROFILE%\AppData\Local\uv, or the Scripts folder within your Python installation directory
      • CoPaw path: Typically located at %USERPROFILE%\.copaw\bin.
    • Manually add to the system's Path environment variable:
      • Press Win + R, type sysdm.cpl and press Enter to open System Properties.
      • Click “Advanced” -> “Environment Variables”.
      • Under “System variables”, locate and select Path, then click “Edit”.
      • Click “New”, enter both directory paths sequentially, then click OK to save.

  2. If using PowerShell (.ps1): Script execution interrupted

Due to Constrained Language Mode, the script may fail to automatically download uv.

  • Manually install uv: Refer to the GitHub Release to download uv.exe and place it in %USERPROFILE%\.local\bin or %USERPROFILE%\AppData\Local\uv; or ensure Python is installed and run python -m pip install -U uv.
  • Configure uv environment variables: Add the uv directory and %USERPROFILE%\.copaw\bin to your system's Path variable.
  • Re-run the installation: Open a new terminal and execute the installation script again to complete the CoPaw installation.
  • Configure the CoPaw environment variable: Add %USERPROFILE%\.copaw\bin to your system's Path variable.

You can also pass options:

macOS / Linux:

# Install a specific version
curl -fsSL ... | bash -s -- --version 0.0.2

# Install from source (dev/testing)
curl -fsSL ... | bash -s -- --from-source

# With local model support (see Local Models docs)
bash install.sh --extras llamacpp    # llama.cpp (cross-platform)
bash install.sh --extras mlx         # MLX (Apple Silicon)
bash install.sh --extras ollama      # Ollama (cross-platform, requires Ollama service)

Windows (PowerShell):

# Install a specific version
.\install.ps1 -Version 0.0.2

# Install from source (dev/testing)
.\install.ps1 -FromSource

# With local model support (see Local Models docs)
.\install.ps1 -Extras llamacpp      # llama.cpp (cross-platform)
.\install.ps1 -Extras mlx           # MLX
.\install.ps1 -Extras ollama        # Ollama

To upgrade, simply re-run the install command. To uninstall, run copaw uninstall.

Step 2: Init

Generate config.json and HEARTBEAT.md in the working directory (default ~/.copaw). Two options:

  • Use defaults (no prompts; good for getting running first, then editing config later): 
    copaw init --defaults
  • Interactive (prompts for heartbeat interval, target, active hours, and optional channel and Skills setup): 
    copaw init
    See CLI - Getting started.

To overwrite existing config, use copaw init --force (you will be prompted). After init, if no channel is enabled yet, follow Channels to add DingTalk, Feishu, QQ, etc.

Step 3: Start the server

copaw app

The server listens on 127.0.0.1:8088 by default. If you have already configured a channel, CoPaw will reply there; otherwise you can add one after this step via Channels.

Option B: pip install

If you prefer managing Python yourself (requires Python >= 3.10, < 3.14):

pip install copaw

Optional: create and activate a virtualenv first (python -m venv .venv, then source .venv/bin/activate on Linux/macOS or .venv\Scripts\Activate.ps1 on Windows). This installs the copaw command.

Then follow Step 2: Init and Step 3: Start the server above.

Option C: Desktop Application (Beta)

If you're not comfortable with command-line tools, you can download and use CoPaw's desktop application without manually configuring Python environments or running commands.

Features

  • ✅ Zero configuration: Download and double-click to run, no need to install Python or configure environment variables
  • ✅ Cross-platform: Supports Windows 10+ and macOS 14+ (Apple Silicon recommended)
  • ✅ Visual interface: Automatically opens browser interface, no need to manually enter addresses
  • ⚠️ Beta stage: Features are continuously being improved, feedback welcome

Download and Usage

  1. Download the installer Go to GitHub Releases to download the version for your system:

    • Windows: CoPaw-Setup-<version>.exe
    • macOS: CoPaw-<version>-macOS.zip

  2. Install and Launch

    • Windows: Double-click the .exe file to install following the wizard, then double-click the desktop shortcut to launch
    • macOS: Extract the .zip to get CoPaw.app, first time requires right-click and select "Open" to bypass system security restrictions

  3. First Launch Note The first launch may take 10-60 seconds (depending on your system configuration), as the application needs to initialize the Python environment and load dependencies. Please wait patiently for the browser window to open automatically.

Complete Guide

Desktop applications involve system permissions, security prompts, debug mode, and other details. Please see the Complete Desktop Application Guide to learn about:

  • Windows two launch modes (Normal vs Debug)
  • macOS how to bypass system security restrictions (3 methods)
  • Common issues and solutions
  • Log viewing and issue reporting

Option D: ModelScope Studio one-click setup (no install)

If you prefer not to install Python locally, you can deploy CoPaw to ModelScope Studio's cloud:

  1. First, sign up and log in at ModelScope;
  2. Open the CoPaw Studio and complete the one-click setup.

Important: Set your Studio to non-public, or others may control your CoPaw.

Option E: Docker

Images are on Docker Hub (agentscope/copaw). Image tags: latest (stable); pre (PyPI pre-release). Also available on Alibaba Cloud ACR for users in China: agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/copaw (same tags).

Pull and run:

docker pull agentscope/copaw:latest
docker run -p 127.0.0.1:8088:8088 \
  -v copaw-data:/app/working \
  -v copaw-secrets:/app/working.secret \
  agentscope/copaw:latest

Then open http://127.0.0.1:8088/ in your browser for the Console. Config, memory, and skills are stored in the copaw-data volume; model provider settings and API keys are in the copaw-secrets volume. To pass API keys, add -e DASHSCOPE_API_KEY=xxx or --env-file .env to docker run.

Option F: Deploy on Alibaba Cloud ECS

To run CoPaw on Alibaba Cloud, use the ECS one-click deployment:

  1. Open the CoPaw on Alibaba Cloud (ECS) deployment link and fill in the parameters as prompted;
  2. Confirm the cost and create the instance; when deployment finishes, you can get the access URL and start using the service.

For step-by-step instructions, see Alibaba Cloud Developer: Deploy your AI assistant in 3 minutes.

Verify install (optional)

After the server is running, you can call the Agent API to confirm the setup. Endpoint: POST /api/agent/process, JSON body, SSE streaming. Single-turn example:

curl -N -X POST "http://localhost:8088/api/agent/process" \
  -H "Content-Type: application/json" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"Hello"}]}],"session_id":"session123"}'

Use the same session_id for multi-turn.

What to do next

  • Chat with CoPAW — Channels: connect one channel (DingTalk or Feishu is a good first), create the app, fill config, then send a message in that app.
  • Run a scheduled "check-in" or digest — Heartbeat: edit HEARTBEAT.md and set interval and target in config.
  • More commands — CLI (interactive init, cron jobs, clean), Skills.
  • Change working dir or config path — Config & working dir.