Quick Start

Complete the installation, open the console, create a Waker, and send your first task. Covers system requirements, macOS / Linux / Windows installation, sign-in, service management, and FAQ.

Goal of this chapter: complete the installation, open the console, create a Waker, and send your first task. If you can already open the Web Console, skip ahead to Create your first Waker.

System requirements and pre-installation checks

Item	Recommendation
Operating system	macOS 13.0+, mainstream Linux distributions, Windows 10+
Memory	4 GB+ recommended
Disk space	At least 500 MB free
Network	Access to model services, code repositories, and connectors required; enterprise networks must allow relevant outbound HTTPS connections

Before installing, confirm that the current user can install programs, start background services, and access the target working directory.

Installation

macOS

macOS supports installation via either a package installer or the command line.

Option 1: Package installer

1. Open the QoderWake website.
2. Select “MacOS”, then choose “ARM64 (Apple Silicon)” or “X64 (Intel)” based on your chip.
3. Download and open the .dmg, then drag QoderWake into “Applications”.
4. Open QoderWake from “Applications”, complete account authorization when prompted, and wait for the service to start and the Web Console to open.

Option 2: Command line

Open a terminal and run:

curl -fsSL https://qoder-ide.oss-ap-southeast-1.aliyuncs.com/qoderwake/install.sh | bash

Do not close the terminal during execution. When the authorization page appears, complete authorization and return to the terminal to wait for completion.

Verification:

• The browser opens the Web Console, or the terminal prints the console address.
• Running qoderwake status in a new terminal returns the service status.

If the terminal reports that qoderwake is not found, open a new terminal. If it still doesn’t work, use the full path:

~/.qoderwake/bin/qoderwake login

Linux

Open a terminal and run:

curl -fsSL https://qoder-ide.oss-ap-southeast-1.aliyuncs.com/qoderwake/install.sh | bash

Do not close the terminal during execution. When the authorization page appears, complete authorization and return to the terminal to wait for completion.

Verification:

• The browser opens the Web Console, or the terminal prints the console address.
• Running qoderwake status in a new terminal returns the service status.

If the terminal reports that qoderwake is not found, open a new terminal. If it still doesn’t work, use the full path:

~/.qoderwake/bin/qoderwake login

Windows

1. Open the QoderWake website and download the Windows installer (.exe).
2. Double-click the installer and follow the wizard to complete installation and account authorization.
3. Wait for the service to start and the Web Console to open.

Verification: The browser opens the Web Console and the Waker management page loads normally. If the browser does not open automatically, run qoderwake portal from the command entry point.

Package names change with each version — always download from the official website. If installation already completed sign-in, started the service, and opened the Web Console, you do not need to repeat the sign-in and startup commands below. Proceed directly to creating a Waker.

Sign in, check account, and sign out

Browser authorization

Run the following commands:

qoderwake login
qoderwake whoami

Complete authorization in the browser. If the browser does not open, copy the address printed in the terminal. If authorization times out, run login again.

Verification: qoderwake whoami displays the current account, and cloud or remote features no longer prompt for sign-in.

Token-based sign-in

When no GUI desktop is available or browser authorization is not possible, sign in with a Personal Access Token (PAT):

QODER_PERSONAL_ACCESS_TOKEN="your-token" \
  ~/.qoderwake/bin/qoderwake login --method token

You can also read the token from a file:

qoderwake login --method file --token-file /path/to/token

After signing in, run qoderwake whoami.

Never save real tokens in screenshots, task messages, or repositories.

Switch accounts or sign out

To clear the current sign-in state:

qoderwake logout

To switch accounts, run logout, login, and whoami in sequence, then refresh the Web Console. When not signed in, local mode remains available; cloud and remote capabilities require a valid account.

Start the service and open the console

Start and open

If the service is not running:

qoderwake start --open

If the service is already running, open the Web Console:

qoderwake portal

portal reads the actual port. The default address is http://127.0.0.1:19820; if the port is occupied, it increments automatically.

To print the actual address without opening the browser:

qoderwake portal --no-open

Verification: The browser opens the Web Console, or the address printed by portal --no-open is accessible.

Check status, restart, and stop

qoderwake status
qoderwake restart --open
qoderwake stop
qoderwake stop --force

Command	When to use	Expected result
qoderwake status	Unsure whether the service is running	Returns the current service status and related information
qoderwake restart --open	Page is abnormal, or configuration/version was updated	Service restarts and reopens the console
qoderwake stop	Normal shutdown of the background service	Service stops, but sign-in state is preserved
qoderwake stop --force	Normal stop is not working	Force stops; running tasks may be interrupted

Before stopping or restarting, confirm whether any conversation tasks, automated tasks, or WakerFlows are in progress. A force stop may interrupt current execution.

Create your first Waker

1. Open Waker Management

   Run qoderwake portal and navigate to “Waker Management” → “New Waker”.

2. Select a role

   Choose the preset role closest to your target responsibilities. If no role fits, select “Custom Role”.

3. Fill in details

   Enter a name and description. Optionally upload an avatar and select a runtime environment.

4. Save and enable

   Click “Save and Enable”.

Verification:

• The new Waker appears in the “My Wakers” list.
• The card shows the correct name, description, environment, and status.

If “Save and Enable” is not clickable, check in order: whether a role is selected, a name is entered, and all required fields are completed.

Send your first conversation task

1. Enter the conversation

   Click “Create Conversation Task” on the new Waker card and confirm the correct Waker is shown at the top of Chat.

2. Select the working directory

   When working with files, select the correct working directory. Add attachments or use @ to reference context as needed.

3. Send a dry-run task

   Keep the model on “Auto” and send a read-only dry-run task, for example:

   Only read the README in the current directory — do not modify any files.
   Summarize the project's purpose and how to start it in 5 bullet points or fewer;
   if information is insufficient, state that clearly.
   
4. Handle authorization prompts

   Send the task. If an authorization or confirmation prompt appears, review the operation details before proceeding.

5. Verify the result

   Wait for the final reply and check that the result comes from the selected directory and does not exceed the scope of your request.

Verification:

• The Waker enters a processing state and eventually returns a result.
• The result comes from the selected directory or attachments and does not exceed the task scope.

After completing these steps, the installation, service, account, Waker, and Chat main flow are all verified.

Quick start FAQ

Symptom	Check first	Suggested fix
Terminal says qoderwake not found	Whether a new terminal has loaded the command path	Reopen the terminal; if needed, use ~/.qoderwake/bin/qoderwake
Browser did not open automatically	Whether the terminal printed an address	Copy the address to a browser, or run qoderwake portal --no-open
Default address is not accessible	Whether the service is running and the actual port has changed	Run qoderwake status and qoderwake portal
Cloud or remote capabilities unavailable	Whether the current account is valid	Run qoderwake whoami; re-sign-in if needed
Waker cannot access local files	Whether the correct working directory is selected	Go back to the input area, select the directory, and retry the task