helm // manual

FAQ

Install the host, pair a server, keep the token on that machine, and drive Cursor CLI from iPhone, iPad, or Mac.

cursor-agentpair ticket127.0.0.1:3000

Install

The host runs the agent. Helm is the Apple window onto it.

What has to be running on the host?

Cursor CLI (cursor-agent), already logged in on that machine. Then the session broker, then this app.

agent-session start

From this repo, copy .env.example to .env. AGENT_SESSION_URL is http://127.0.0.1:7788. AGENT_SESSION_TOKEN is the token file the broker wrote on the host. Then:

npm run host:start

The console listens on 127.0.0.1:3000. The Apple shell loads that origin. There is no separate cloud deploy.

How does the phone reach that host?

Open Settings in Helm and enter your server's https address. Helm opens that server and remembers it on this device.

The address has to be https, and it has to be the server's public name. A loopback or private address stays on that machine.

Then pair. On the server, run agent-session pair and paste the code.

From a computer, you can still forward the loopback port:

ssh -L 3000:127.0.0.1:3000

Point that SSH session at the host. Leave port 3000 off the public internet.

How do I install Helm on iPhone, iPad, or Mac?

Use a Mac with full Xcode. There is no App Store build and no PWA. The shell is a WKWebView that shows the Next.js UI from the host.

scripts/apple-install.sh ios

That checks out the latest origin/main, clean-builds the iPhone and iPad app, and installs it on a device already paired with that Mac — USB, or Wi-Fi on the same network.

scripts/apple-install.sh macos

That builds the Mac app into $HOME/Applications from the current checkout.

The phone is locked during install. What now?

A locked phone drops the developer tunnel. Build once, then retry until the phone is unlocked:

scripts/apple-install.sh ios --wait 1200

Pair

The host mints the code. Helm only redeems it.

How do I pair a server?

This app does not mint tickets. On your host, run agent-session pair. You get a one-time code that lasts about ten minutes.

Paste it into Pair on the Chats screen, or straight into the composer. Helm connects to that host.

Whose host does Helm connect to?

Yours. Each person runs their own host and pairs this app to it. A code from that machine does not reach anyone else's host.

Settings stores that server's https address on this device. The next launch opens it again.

If you run a second machine, a second code adds that host and leaves the first connected. The Space menu chooses where the next prompt goes.

How do I unpair?

/unpair drops the ticket for the focused host. Settings has the same action: Unpair this device.

Typing /pair in the console reprints how to mint a code on your host. It does not mint one.

Security

A pairing ticket is the gate. The host token stays on the host.

What does a paired device get?

A ticket scoped to one Space (pair:operator). Runs execute as the host user, inside that Space's workspace, with the same --yolo reach as the Telegram bridge.

Console runs send runner: "acp", so permission, plan, and question cards show here. Telegram stays on -p.

What never leaves the host?

AGENT_SESSION_TOKEN and the host bearer token. The phone redeems a code and stores a pairing ticket, not those secrets.

Unauthenticated chat routes are gone. Do not paste the host token into the browser, and do not publish port 3000.

Where do chats live?

The host session store is the transcript. This device keeps a copy in local storage so a thread reopens quickly.

Settings → Clear Data wipes that copy. Those chats do not come back when you reopen the app.

What should stay private?

The pairing code. It works once, it expires in about ten minutes, and it grants operator access to that Space.

An admin ticket is a stronger grant. Host CLI admin commands such as /login require it.

Cursor

Helm does not ship a model. Cursor CLI does the work.

Do I need Cursor?

Yes. Install cursor-agent on the host and log in there. Helm only sends prompts to that CLI.

If the CLI session has lapsed, an admin ticket can send /login, which runs cursor-agent login on the host. /logout and /cliupdate are the same kind of admin command.

Which models can I use?

Whatever that host already has. The list is cursor-agent --list-models on the machine. Pick one in the console, or use /model and /models.

Is there a Helm subscription?

No. This app does not bill you. Usage follows the Cursor account logged in on the host.

How do sessions resume?

Each thread maps to a cursor-agent chat id stored on the host. /resume and /continue pick one back up. /new starts a fresh thread in the Space you have focused.

Operate

After pairing, the console uses the same verbs as the Telegram bots.

How do I match Telegram?

Send while a run is busy and the prompt queues. /steer interrupts the run in progress. /plan and /askmode set CLI modes.

Menu, or /menu, opens Status, Queue, and Host CLI: /status, /queue, /dequeue, /clearqueue, /whoami, /about, /mcp, /repos. Type / for the full slash list.

Attach an image the same way you send a Telegram photo.

How do I tell chats apart?

Each saved conversation gets a neon glyph: a helm color, a scan pattern, and a CLI character. It shows in the sidebar and in the chat header, including when the sidebar is collapsed. The mark stays with that chat.