# Quick start — your first task in 5 minutes

> From download to a finished task: sign in, pick a model slot, attach a file, approve a tool call. Includes the four permission modes and the answers to the questions people ask first.

NearWork is an AI agent that runs on your own computer: it reads files, runs commands, browses the web and writes documents, turning one sentence into a delivered result. This walkthrough takes you from zero to a real task in about five minutes.

## 1. Install the desktop app

- **Windows**: download the `.exe` installer and run it; the install path is up to you.
- **Linux**: download the `.deb` (Debian / Ubuntu) or `.rpm` (Fedora / CentOS family).
- **macOS**: use whatever build the [download section](/#download) currently offers.

If you would rather skip the desktop app, there is a CLI (**Node.js 22+ required** — older versions exit with an upgrade message):

```bash
npm install -g @lingxi-agent/core
lingxi
```

On first launch the app creates a data directory called `LINGXI_HOME` (default `~/.LingXi`; on Windows `C:\Users\<you>\.LingXi`). Configuration, sessions, memory, the knowledge base and logs all live there — copy that folder to move everything to another machine.

## 2. Sign in (required)

**NearWork requires an account.** The first launch walks you through sign-in; without it you cannot create a session or send a message. The entry point sits at the bottom-left of the desktop app; in the CLI, `/login` opens a browser window for authorization. The resulting session is stored in `auth.json` inside the data directory and is shared by the desktop app and the CLI, so you sign in once.

After signing in, models can come from two places, switchable at any time:

| Model source | Who it suits | How it works |
|---|---|---|
| NearWork credits | Anyone who wants it to just work | Requests go through the official relay and are billed against your plan; the free tier includes rolling credits |
| Your own API key | People who already have provider accounts | Enter the key under Settings → Models & Providers; the provider bills you directly |

One thing to be clear about: bringing your own key changes *who serves the model and who bills you* — it does not replace signing in.

## 3. Pick a model: seven slots, one job each

Instead of scrolling a 200-model list every time, NearWork splits model choice into seven slots. Open any provider under Settings → Models & Providers to see the seven model ID fields:

| Slot | What it is for |
|---|---|
| Fast | Everyday Q&A, rewriting, small scripts — latency first |
| Think | Complex reasoning, planning, stubborn bugs — allow it to think longer |
| Vision | Reading screenshots, charts and scanned pages |
| Image edit | Generating and editing images |
| Speech generation | Text to speech: read replies aloud, voice-over |
| Speech recognition | Speech to text: voice input, meeting transcripts |
| Embedding | Semantic retrieval for memory and the knowledge base |

In chat you only touch the first two: switch Fast / Think above the input box and adjust reasoning depth (low / medium / high). The rest are consumed automatically by the matching feature — images go to Vision, generation goes to Image edit, voice in and out go to the two speech slots, retrieval goes to Embedding.

With an official NearWork account the seven slots are pre-filled from the models your plan can reach; with your own key you type the model IDs yourself. An empty slot means **that capability is unavailable**, not silently substituted — attach an image without a vision model and NearWork tells you so.

## 4. Run your first task

Create a session, choose a working directory, then just say what you want. Copy any of these:

```text
Turn this meeting recording into minutes: decisions, disagreements, action items with owners and dates
```

```text
Scan the current folder, find every image over 5 MB, compress each below 1 MB, and back the originals up into backup/
```

```text
Read this project's README and package.json, then tell me how to run it locally and what dependencies are missing
```

You will see the full run: think, call a tool (read a file, run a command, search the web), inspect the result, continue — until it delivers. Anything that writes files or executes commands raises a confirmation prompt; that is the permission system doing its job.

## 5. Four permission modes

You set the boundary, from "ask me every step" to "hands off":

| Mode | Behaviour |
|---|---|
| `normal` (default) | Read-only runs automatically; writes and commands need confirmation |
| `strict` | Everything needs confirmation |
| `auto` | Fully automatic; dangerous commands are still blocked |
| `full_access` | Nothing is confirmed |

Stay on `normal` at first: you get the speed of automatic read-only work without letting anything change files behind your back. Raise it once you are comfortable.

## Frequently asked questions

### The window is blank after installing. What now?

Re-download the installer to rule out a truncated download, then check whether antivirus software is blocking the renderer process. On Windows, try running it once as administrator so first-run dependency files can be written. If it persists, send the most recent log from `<LINGXI_HOME>/log` to support.

### Do I really have to sign in?

Yes. Every client — desktop and CLI — requires a NearWork account before it can create sessions or send messages. A personal API key changes where inference is billed, not whether you need an account.

### Can I sign in but still use only my own key?

Yes. Add a provider entry under Settings → Models & Providers, fill in your key and the seven model IDs, and make that entry the default. Official credits are spent only when you actively pick an official model.

### How are free credits calculated?

The free tier grants credits on rolling windows (total, 7-day and 5-hour caps, whichever runs out first). Usage is metered in 灵力 (credits): text and embeddings per token, images per image, speech per weighted character or per second of audio. Current numbers live on the [pricing page](/en/pricing).

### Can we self-host, or keep the enterprise knowledge base on our own servers?

Yes. The engine, the model gateway and the enterprise knowledge base can all be deployed inside your own network for offline or data-residency requirements; scope and pricing depend on scale. There is no self-service checkout for this — use the contact button at the bottom-right of any page and mention self-hosting.

## Next steps

- Want external tools? Read the [MCP guide](/en/docs/features/mcp).
- Wondering where your data goes? Read [Data and privacy](/en/docs/faq/data-privacy).
- Want to know what it can actually do? See the [tool inventory](/en/docs/features/tools).
