Quick Start

Five ways to install and run CoPaw — pick the one that fits your setup.

This section describes five ways to run CoPAW:

Option A — One-line install (recommended): run on your machine with no Python setup required.
Option B — pip install: if you prefer managing Python yourself.
Option C — ModelScope Studio: one-click cloud deploy, no local install needed.
Option D — Docker: use official images from Docker Hub (ACR also available for users in China); tags include latest (stable) and pre (PyPI pre-release).
Option E — 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: One-line install (recommended)

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 (PowerShell):

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

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

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: ModelScope Studio one-click setup (no install)

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

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

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

Option D: 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 8088:8088 -v copaw-data:/app/working 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. To pass API keys, add -e DASHSCOPE_API_KEY=xxx or --env-file .env to docker run.

Option E: Deploy on Alibaba Cloud ECS

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

Open the CoPaw on Alibaba Cloud (ECS) deployment link and fill in the parameters as prompted;
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.