# Getting Started

Nana is a free terminal for Windows 10 and newer that runs AI coding agents
side by side, each on its own git worktree. Install it with the `.msi` or one
PowerShell command, then open a project and start your agents.

## Requirements

| Part | Runs on |
| --- | --- |
| Desktop app | Windows 10 or newer on x86_64 |
| `nana` CLI and server | Windows 10 or newer on x86_64. On a [remote server](https://nana.areshk.dev/docs/features/remote-servers.md): macOS 14 or newer, or Linux with glibc 2.35 or newer, on x86_64 or ARM64. musl is unsupported. |

See [Windows desktop app](#windows-desktop-app) for the package. A source build
is described in the [root README](https://github.com/Areshkew/nana/blob/main/docs/README.md#install).

## Windows desktop app

Download the native package from the
[latest release](https://github.com/Areshkew/nana/releases/latest):

1. Download `Nana-<version>-x86_64.msi` and open it. It installs for your user
   only — no administrator — into `%LOCALAPPDATA%\Programs\nana-desktop`, or
   `nana-desktop-beta` for the beta, with a **Nana** (or **Nana Beta**) entry in
   the Start menu.
2. Leave the **Command line tool on PATH** feature selected to open a project
   with `nana <folder>` from any terminal.

Every release installs as a versioned installation: `current` is a junction the
installer points at one `versions\<version>` directory, and the app's own
updater unpacks the new version beside the running one, points `current` at it
and restarts into it, so the app, the `nana` command and the server are always
from one build. Notifications are filed under
the app's identity (`com.nana.app`, `com.nana-beta.app` for a beta), which the
installer registers together with the shortcut.

A managed machine, or a policy that blocks MSI files, can use the installer
directly. Set `VERSION` to the version without its leading `v`:

```powershell
$version = '0.1.0'
$installer = "$env:TEMP\install-desktop-windows.ps1"
Invoke-WebRequest "https://github.com/Areshkew/nana/releases/download/v$version/install-desktop-windows.ps1" -OutFile $installer
pwsh -File $installer install -Version $version -AddToPath
```

The installer selects `x86_64`, downloads the release zip over HTTPS, checks its
SHA-256 against the release's metadata, verifies every file in the package
against its manifest and every executable's own build identity, and then
installs. It does not open the app. Nothing else is needed: the package carries
the app, the `nana` command, the server and the default-terminal proxy, needs no
Visual C++ redistributable, and does not use Python.

Open **Nana** or **Nana Beta** from the Start menu.

## Updates and recovery (Windows)

The app checks automatically, and **Check for Updates** checks immediately.
Stable installs receive stable releases; beta installs receive betas. The
updater verifies the archive checksum, the package manifest and the matching
build of the app, the command and the server before replacing anything, keeps
the running version while the app runs, and restarts into the new one. Settings,
projects and sessions live in Nana's own profile under `%LOCALAPPDATA%` and are
not part of an update.

## Uninstall (Windows)

Quit the app and stop its local server first. Then either remove **Nana** (or
**Nana Beta**) in **Settings → Apps → Installed apps**, or run the installed
installer:

```powershell
pwsh -File "$env:LOCALAPPDATA\Programs\nana-desktop\installer\install.ps1" uninstall -Root "$env:LOCALAPPDATA\Programs\nana-desktop"
```

For the beta, replace `nana-desktop` with `nana-desktop-beta`. Removal refuses
while an installed app, command or server is running, and removes only the
versioned installation, its own shortcut, its notification identity and the PATH
entry it added. Settings, projects, sessions and kibbles are kept.

## Windows terminal integration

Nana can be the terminal Windows hands a new console session to, and it adds
**Open in Nana** to Explorer's folder menu. Both live in
[Terminal](https://nana.areshk.dev/docs/features/terminal.md#windows-default-terminal), and the reasons
behind the unpackaged per-user design are in
[Decisions](https://github.com/Areshkew/nana/blob/main/docs/tech/decisions.md#d13-the-server-is-the-windows-default-terminal).

## CLI and server only

For a Linux computer or Mac you reach as a remote server. This installs `nana`
and `nana-server` from the native release packages.

Nana's native packages and the install script below must be published under
`Areshkew/nana` first; the repository's existing Electron releases are not
native Rust builds. On a computer you reach as a
[remote server](https://nana.areshk.dev/docs/features/remote-servers.md), use the install script:
SSH sessions often don't have a package manager on `PATH`.

### Install script

Set `VERSION` to the newest version on the
[releases page](https://github.com/Areshkew/nana/releases/latest), without the
leading `v`:

```bash
VERSION=0.1.0
curl -fsSL "https://github.com/Areshkew/nana/releases/download/v$VERSION/install-nana.sh" \
  | sh -s -- --version "$VERSION"
export PATH="$HOME/.local/bin:$PATH"
```

The script picks the build for your OS and architecture, verifies its checksum,
and installs both commands into `~/.local/bin`. Add the `export` line to your
shell's startup file to keep them on `PATH`.

- **Update:** run it again with the new version and `--replace`.
- **Another folder:** add `--install-dir PATH`.

### Check it

Run `nana --version` and `nana-server --version`, then `nana server start`
to start the [server](https://nana.areshk.dev/docs/features/server.md). Updating them never restarts a
running [server](https://nana.areshk.dev/docs/features/server.md#lifetime); stop it to switch to the new
version.

## Beta

The beta gets new features first. It installs as a separate app, **Nana Beta**,
next to Nana, keeps its own settings and data, and updates to each new beta.
Download it from the newest `v<version>-beta.<N>` pre-release on the
[releases page](https://github.com/Areshkew/nana/releases). For the CLI and
server, give the install script a beta version, such as `0.1.0-beta.3`.

## First steps

1. **Add a project.** Choose **Add Project** at the bottom of the sidebar, or
   press `Ctrl+Shift+O`, and pick a folder.
2. **Open a terminal.** `Ctrl+Shift+T` opens a tab in the project.
   `Ctrl+Shift+N` opens one in Home.
3. **Split it.** `Ctrl+Shift+D` splits right, `Ctrl+Shift+Alt+D` splits down.
4. **Quit freely.** Terminals keep running in the background. Reopen Nana and
   everything is where you left it.

## Next

- [How Nana works](https://nana.areshk.dev/docs/features/server.md): the server, sessions, and history.
- [Projects](https://nana.areshk.dev/docs/features/projects.md), [Terminal](https://nana.areshk.dev/docs/features/terminal.md), and
  [Keyboard shortcuts](https://nana.areshk.dev/docs/user-guide/keyboard-shortcuts.md).
- [Remote servers](https://nana.areshk.dev/docs/features/remote-servers.md).
- [Settings](https://nana.areshk.dev/docs/user-guide/settings.md) and [Troubleshooting](https://nana.areshk.dev/docs/user-guide/troubleshooting.md).