> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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

<Tabs>
  <Tab title="macOS">
    macOS supports installation via either a package installer or the command line.

    ### Option 1: Package installer

    1. Open the [QoderWake website](https://qoder.com.cn/qoderwake).
    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:

    ```bash theme={null}
    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:

    ```bash theme={null}
    ~/.qoderwake/bin/qoderwake login
    ```
  </Tab>

  <Tab title="Linux">
    Open a terminal and run:

    ```bash theme={null}
    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:

    ```bash theme={null}
    ~/.qoderwake/bin/qoderwake login
    ```
  </Tab>

  <Tab title="Windows">
    1. Open the [QoderWake website](https://qoder.com.cn/qoderwake) 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.
  </Tab>
</Tabs>

<Note>
  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.
</Note>

## Sign in, check account, and sign out

### Browser authorization

Run the following commands:

```bash theme={null}
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):

```bash theme={null}
QODER_PERSONAL_ACCESS_TOKEN="your-token" \
  ~/.qoderwake/bin/qoderwake login --method token
```

You can also read the token from a file:

```bash theme={null}
qoderwake login --method file --token-file /path/to/token
```

After signing in, run `qoderwake whoami`.

<Warning>
  Never save real tokens in screenshots, task messages, or repositories.
</Warning>

### Switch accounts or sign out

To clear the current sign-in state:

```bash theme={null}
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:

```bash theme={null}
qoderwake start --open
```

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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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              |

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

## Create your first Waker

<Steps>
  <Step title="Open Waker Management">
    Run `qoderwake portal` and navigate to "Waker Management" → "New Waker".
  </Step>

  <Step title="Select a role">
    Choose the preset role closest to your target responsibilities. If no role fits, select "Custom Role".
  </Step>

  <Step title="Fill in details">
    Enter a name and description. Optionally upload an avatar and select a runtime environment.
  </Step>

  <Step title="Save and enable">
    Click "Save and Enable".
  </Step>
</Steps>

**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

<Steps>
  <Step title="Enter the conversation">
    Click "Create Conversation Task" on the new Waker card and confirm the correct Waker is shown at the top of Chat.
  </Step>

  <Step title="Select the working directory">
    When working with files, select the correct working directory. Add attachments or use `@` to reference context as needed.
  </Step>

  <Step title="Send a dry-run task">
    Keep the model on "Auto" and send a read-only dry-run task, for example:

    ```text theme={null}
    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.
    ```
  </Step>

  <Step title="Handle authorization prompts">
    Send the task. If an authorization or confirmation prompt appears, review the operation details before proceeding.
  </Step>

  <Step title="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.
  </Step>
</Steps>

**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 |