---
title: "Installation & First Run"
description: "Choose Cetas JS (recommended) or the Native terminal, then connect your first model."
---

> Documentation Index
> Fetch the complete documentation index at: https://colmugx.github.io/cetas/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation & First Run

> **Note**
>
> Cetas JS is the recommended interactive client. Native is an optional Go/Bubble Tea implementation of the same MoonBit agent core; host-specific features differ.

## Option 1: Cetas JS via npm (recommended)

```bash
npm install -g @posoco/cetas
cetas --version
```

Requires Node.js 24 or newer ([nodejs.org](https://nodejs.org/)). This is the primary interactive terminal, including JS-specific integrations such as Board workflows. The current stable Cetas release publishes the JS distribution through npm rather than a `cetas-bun` executable ZIP.

## Option 2: Cetas Native (no Node.js required)

Native runs a Go/Bubble Tea v2 terminal backed by the same MoonBit Cetas/Posoco runtime. It is a second choice if you prefer a native CLI, not a promise of full feature parity with the npm build.

### Homebrew — macOS Apple Silicon or Linux x64

```bash
brew install colmugx/tap/cetas
```

### Scoop — Windows x64

```powershell
scoop bucket add cetas https://github.com/colmugx/scoop-bucket
scoop install cetas/cetas
```

### Direct installation / download

You can also use the repository's interactive [Unix installer](https://github.com/colmugx/cetas/blob/main/install.sh) or [PowerShell installer](https://github.com/colmugx/cetas/blob/main/install.ps1). Both show the detected OS, selected version, destination and install files, then ask for confirmation before downloading binaries. Noninteractive installation needs explicit `--yes` (Unix) or `-Yes` (PowerShell).

Alternatively, choose a `cetas-v*` tag on the [GitHub Releases page](https://github.com/colmugx/cetas/releases); Memoh has its own release series. The Native archives currently cover macOS ARM64, Linux x64, and Windows x64. On Windows, `cetas-windows-x64.zip` includes `cetas.exe`, `cetas-acp.exe`, `cetas-run.exe` and `cetas_moon.dll`; **keep the DLL next to the executable**.

## Only need an editor agent or a one-off runner?

These are still available as **independent** downloads in each Cetas release:

| Use case | Release assets |
| --- | --- |
| Lody, Zed, or another ACP client | `cetas-acp-darwin-arm64.tar.gz`, `cetas-acp-linux-x64.tar.gz`, `cetas-acp-windows-x64.zip` |
| One task from a script or CI | `cetas-run-darwin-arm64.tar.gz`, `cetas-run-linux-x64.tar.gz`, `cetas-run-windows-x64.zip` |

You do not need to download the entire Native terminal for these use cases. Verify the selected archive using the `SHA256SUMS` file from the same release.

## When JS and Native are both installed

Both may install a `cetas` command. Your shell launches whichever is first on `PATH` — check `command -v cetas` on Unix or `Get-Command cetas` in PowerShell. Configuration lives in the shared [Cetas home](/cetas/en/configuration/cetas-home/), but features, approval UI, and session flows can differ between hosts.

## From install to your first message

Four steps.

### 1. Run it in your project directory

```bash
cd /path/to/your/project
cetas
```

Everything it reads, edits, or executes is relative to this directory. No
project yet? A freshly created empty folder works just as well.

### 2. Sign in with a provider

Cetas ships no model of its own — it calls a provider (a company that supplies
models, like DeepSeek or OpenAI). Register on the provider's site, create an
API key, then:

```text
/login
```

Pick the provider, paste the key (or use browser sign-in where it is offered),
done. Seeing fewer options than expected? See
[Providers](/cetas/en/configuration/providers/).

### 3. Pick a model

```text
/model
```

The list comes from the provider you just signed in with. Pick one and you are
set.

### 4. Say the first thing

```text
Explain how authentication works in this repository.
```

No repository? Any sentence works — a streaming reply means you are through.
Keys worth knowing on day one:

- `@path` attaches a workspace file, <kbd>Tab</kbd> completes;
- <kbd>Esc</kbd> interrupts the running turn; typing while it runs queues a
  follow-up;
- before you fully trust it, `/permission readonly` drops the session to
  read-only — see [Permissions](/cetas/en/configuration/permissions/);
- `/help` lists the commands this build actually has.

Sessions are kept automatically: `/sessions` reopens one, `/rewind` walks back
to before a mistake — there is no "save" step.

## Using your company's own endpoint?

Cetas supports self-hosted OpenAI-compatible endpoints natively; the
walkthrough is at [Custom models](/cetas/en/configuration/custom-models/).

## Stuck?

| Symptom | Fix |
| --- | --- |
| Node version too old at install | Upgrade Node, or use the released binaries |
| `/login` or `/model` list is empty | Run `/login` again, then `/model`; still stuck, see [Providers](/cetas/en/configuration/providers/) |
| The first message errors out | The sign-in usually never finished — run `/login` again |
| Everything gets refused | The session is read-only; `/permission workspace_write` allows writes |

Credentials, your model pick, and past sessions all land in one home directory
automatically — nothing to manage day to day. Curious what it looks like or
how to back it up? See [Cetas Home](/cetas/en/configuration/cetas-home/).

Next: [Custom models](/cetas/en/configuration/custom-models/),
[Permissions](/cetas/en/configuration/permissions/), or the
[command reference](/cetas/en/reference/commands/).

Source: https://colmugx.github.io/cetas/en/getting-started/installation/index.mdx