---
title: Usage
description: Wrap your local agent, work through the overlay, and bridge cloud sessions into local tools.
status: draft
sidebar:
  order: 1
---

## Install and run

```sh
curl -fsSL https://norisessions.com/install.sh | bash
nori-handroll claude       # or codex, gemini
```

The first run asks to log in (Google or email) and installs the session hook
for your agent. Then your agent runs exactly as before — handroll sits
invisibly in front of it. Updates are checked once a day; `nori-handroll`
offers to update itself when a new version ships.

## The overlay

Press **Ctrl-B** to open the overlay while a session runs:

| Action | What it does |
|---|---|
| Attach / Detach | switch between running sessions, or leave one running in the background |

Detached sessions keep running; reattach with `nori-handroll attach --latest`
or pick one with `nori-handroll attach --ui`.

:::note
Overlay **Handoff** and mid-run **Remote control** are disabled in release
builds (debug-only experiments), and the broker rejects hand-off-style
acquisition. Remote control works in release only when enabled at launch:
`nori-handroll <agent> --remote-control`.
:::

## Cloud sessions from your terminal

Local → cloud hand-off is not available today. What works:

- **Bridge a cloud session into a local ACP client**: `nori-handroll acp
  --type cloud` acquires a cloud session and speaks ACP over stdio; the
  session is released when the client disconnects.
- **Snapshot workspace state**: `nori-handroll snapshot` pushes an orphan
  metadata branch (`nori/session/<name>/<timestamp>`) — requires a git remote.
- **Resume in the cloud**: reply in the session's thread or use `!resume`
  from Slack.

Details and the exact contract: [Handoff and
resume](/sessions/handroll/handoff-and-resume/).

Which broker handroll talks to, in priority order: `NORI_SESSIONS_URL`, then
`NORI_BROKER_URL`, then your configured org (`https://<org>.norisessions.com`),
then `http://localhost:19400`. Login is only required for non-local brokers.

## Subcommands

```
nori-handroll <agent>          run (default)
nori-handroll attach [target]  reattach to a running session
nori-handroll login|logout     manage auth (google or email)
nori-handroll acp              stdio ACP adapter (--type local|cloud)
nori-handroll snapshot         push workspace metadata for later resume
nori-handroll fleet status     pool counts (admins)
```