The Ship's Manual

Everything you need to run your helm. For the story of why 1Helm exists, start here.

Quick start

1Helm turns one computer into your own always-on workspace — a crew of resident agents, each with a private computer, durable memory, and real skills, reachable from any device.

Dedicate a machine. A Mac mini, mini PC, or desktop tower — 8 GB of RAM and 200 GB of storage is plenty. It runs on macOS, Windows, and Linux, and works best when the machine is dedicated, because your crew works around the clock.
Install 1Helm and sign in with the AI providers you already pay for. Onboarding walks you through it.
Pick a workspace name — that becomes your address, like yourworkspace.1helm.com.
Tuck the machine somewhere quiet with power and internet. A closet with an ethernet cable is perfect.
Open your workspace URL from any device. Skipper is waiting in #main.

notePlatform specifics live in the guides: macOS, Windows, and Linux. As long as the helm computer has power and internet, your crew is never out of reach. Sleeping or shutting it down makes the workspace unavailable — it's your server.

The crew

The Captain You. The workspace owner and final human authority. You set outcomes, supply judgment and credentials when genuinely required, and manage the whole workspace.

Skipper Your chief of staff. Lives in your private #main, manages channels, residents, computers, and schedules — and can jump into any channel to unblock an agent.

Residents Permanent specialists. Every channel gets exactly one resident and one isolated, persistent Linux computer. New threads and model swaps never replace the identity.

Coworkers Human teammates. Each gets their own private #main with Skipper, plus a human-only Collab space. Their channels stay private until they invite you.

Channels

Create a channel for any durable area of responsibility — a product, a launch, an inbox, a household, a client, a research stream. The channel owns its resident, its computer, its /workspace, files, threads, memory, skills, and scheduled obligations.

Ask Skipper in plain language:

@skipper what channels exist
@skipper inspect #product-launch
@skipper sunset #ideas
@skipper inspect the computer fleet and due obligations

Archive is the safe sunset: it preserves the resident's whole world and disk while pausing workflows. Restore brings back that exact world. Permanent deletion requires the channel to be archived first, and #main can never be archived or deleted.

Talking to your crew

Mention the resident to start a job — @email-tracker can you… — then keep talking naturally; you don't need to repeat the mention in a one-on-one thread. Each thread is a durable work session inside the resident's larger identity, with its own status, summary, and usage. Threads lists them; Board organizes the same sessions into status lanes.

Replies stream into one stable message, and your draft text and scroll position stay put while updates arrive. If the agent hits something only you can decide — a real judgment call, a missing credential, an irreversible step — it stops and asks with structured options. Routine setup, installs, and retries are its job, not interview material.

the whole pointAsk a chatbot to "clean up these files and email the summary" and you get a to-do list. Ask a resident and it just does it — inspects, installs what it needs, retries, checks its own work, and reports back.

Files & Terminal

Files and Terminal are two views of the same channel computer. Agent commands and your terminal both start in the channel's persistent /workspace. The terminal survives network changes and app backgrounding — same shell, same variables, same scrollback.

Every resident's computer is fully isolated from your real machine:

Host	Isolation
macOS (Apple Silicon)	One Apple `container machine` per resident, no home-folder mount
Linux	One durable Podman OCI container per resident
Windows	The same Linux host, running inside a WSL 2 distribution: one durable Podman OCI container per resident

Different plumbing, same architecture: as far as the resident knows, one computer exists — its own. It can't see into yours.

Memory

Memory holds curated facts, decisions, corrections, preferences, and procedures — with provenance. It is not a transcript dump; your raw messages remain the authoritative archive, and each resident can search its own channel's past sessions semantically, by exact text or date, and then read one in full.

Each resident and Skipper has an isolated memory store. Guests and other channels' residents can't touch it.

facts vs. skillsA chatbot remembers that you like bullet points. A resident remembers how to do your job — work through your invoices together once and it writes itself the procedure. Train it once. It's trained.

Skills

Every resident starts with a focused operational core plus role-specific skills. It sees a compact inventory, loads a skill's full procedure only when it chooses to use it, and can ask Skipper for another procedure from the complete workspace catalog.

Beyond the built-ins, Settings → Skills searches the open SkillsMD registry. Installed skills are pinned to an immutable revision, scanned, hashed, and wrapped under 1Helm's runtime authority. And when no ready-made procedure exists, choose Learn a new skill: Skipper studies your local sources, links, and notes in a visible thread and authors a procedure specific to your workspace.

Models & providers

1Helm is model-agnostic. Connect multiple ChatGPT, Claude, Gemini, and xAI accounts, plus keyed OpenRouter, NVIDIA NIM, Cloudflare, GLM, or any OpenAI-compatible endpoint. Use a direct model, or a named fallback / round-robin route — when a model runs out of quota or errors, requests flow to the next one.

Model choice cascades like a waterfall — each level inherits from the one above unless you override it:

Global→ Channel→ Session→ Message

Five messages deep with one model, you can send the sixth with another. The session just continues. Swapping the model changes nothing else — the agent keeps its name, computer, files, memory, and everything it's learned. You're changing the engine, not replacing the employee.

Providers are member-owned: teammates connect their own accounts, which start private, and can explicitly share them with the workspace without giving anyone else control of the credential.

Connections

Gmail

Settings → Connections → Gmail owns the connection on the helm computer — or just ask @skipper can we set up Gmail. Gmail supports account inventory, search, read, and draft creation. Sending remains disabled. OAuth tokens live in host-owned storage and never enter chat or a resident's computer.

Photon / iMessage

Connections walks the Captain through Photon device authorization and phone registration. The configured Captain phone talks directly to Skipper: the first inbound text creates a private thread in #main → Texts, replies return to that conversation, and the context persists across connector restarts until the Captain sends /new. The same saved conversation can continue on desktop without replaying desktop-only turns to iMessage.

Workflows & follow-ups

A follow-up is a one-shot durable wake on an existing thread — "follow up on that order in three days." A workflow is a recurring obligation with an interval, next run, and run history — "check inventory every Monday morning."

Both survive restarts, and both can wake a sleeping resident computer. Close the laptop and walk away: when Monday comes, the ship wakes itself, does the job, and reports back. Skipper handles the fleet's care — CPU, RAM, and disk pressure, sleep and wake, repair, resize — so you never manually size a machine.

Updates & your data

Mac releases are signed, notarized, and verified before install — Profile → Check for updates downloads on the helm machine and offers Restart & install only when ready. Linux installs use a root-owned updater that verifies a release digest, installs into a versioned directory, switches atomically, health-checks, and rolls back if needed. A Windows host uses that same Linux updater, because a Windows host is a Linux host running inside a WSL 2 distribution.

Every update preserves your data root:

macOS:  ~/Library/Application Support/1Helm-OCI-v1
Linux:  /var/lib/1helm-oci-v1
Windows: /var/lib/1helm-oci-v1, inside the "1helm" WSL distribution

carefulThat directory holds databases, credentials, workspaces, and resident state. Never delete it during a reinstall or migration — and before removing 1Helm entirely, use the built-in removal flow and export irreplaceable channel files first. On Windows the whole data root lives on the WSL distribution's virtual disk, so unregistering that distribution destroys it.

Security

Resident computers have no access to your real machine — no home mount on macOS, and ownership-checked OCI storage on Linux, including the Linux inside a Windows host's WSL 2 distribution.
Credentials and connectors are host-owned and minimally brokered; tokens never enter chat or resident computers.
Channel membership gates files, terminals, messages, and live events. Private coworker channels aren't Captain-readable without invitation.
External skills are revision-pinned, bounded, scanned, hashed, and wrapped.
Operational history enters a SHA-256 hash chain — Settings → Audit verifies it and pinpoints tampering.
Mac artifacts are Developer ID signed, notarized, stapled, and Gatekeeper-verified, and Linux assets are digest-verified. Windows ships no artifact of its own; its installer verifies Microsoft's WSL package against a pinned digest and a valid Microsoft Authenticode signature, and the pinned Ubuntu root filesystem against its digest.

Troubleshooting

Windows printed "Restart required" and stopped

That's the expected halfway point of a Windows install, not a failure. Windows 11 ships with WSL and VirtualMachinePlatform turned off; the installer turns them on for you, and Windows can't use them until it restarts. Restart, sign back in as the same Windows user, open PowerShell, and run the same command again — it continues from where it stopped and skips what's already done. Nothing is lost.

Windows won't run install.ps1

If you downloaded the script, Windows blocks running .ps1 files and says running scripts is disabled. Run it as powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 instead. The irm https://1helm.com/install.ps1 | iex one-liner is unaffected, because it pipes a string into PowerShell rather than executing a file.

A "Welcome to WSL" window opened

That window is Microsoft's, not ours — WSL shows it the first time it sets itself up. It's harmless. Close it and let the install carry on.

Port 8123 is already in use on Windows

Windows and every WSL distribution share one network namespace, so anything already listening on 8123 — another distribution, or an ordinary Windows process — stops 1Helm binding it. The installer refuses to continue rather than half-install, and names the port. Stop whatever owns it, then run the command again.

macOS won't open the app

The Mac release is Developer ID signed, notarized, and stapled, so Gatekeeper should accept it once it's in Applications. If it doesn't, you likely have a partial or re-hosted download — get the DMG again from 1helm.com. Don't strip quarantine attributes or re-sign an ad-hoc build to get around a failed check.

The Linux installer refuses to run

It needs root, a running systemd host, apt, cgroup v2, and an x86-64 or arm64 CPU — and it installs Podman, not Docker. The error names the missing prerequisite. Check progress with sudo systemctl status 1helm and sudo journalctl -u 1helm -f.

Skipper reports only #main

Ask @skipper what channels exist — inventory comes from the native control plane and includes every channel in your scope, archived ones on request.

Terminal and Files disagree

Refresh Files after the command completes and confirm the prompt is inside /workspace. Both views share the channel computer; host paths are not a resident workspace.

A scheduled job didn't run

Check Workflows and Board, then ask Skipper to list obligations and reconcile the fleet. An archived channel intentionally pauses its workflows.

A model keeps using a disabled account

Confirm it's disabled under Providers, reproduce one request, and inspect Logs — disabled accounts should be absent from attempts entirely, not merely fail first.

Gmail asks repeated questions

Start from @skipper can we set up Gmail or Connections → Gmail. The native connector runs directly and must not open consecutive interviews.

FAQ

Do I really need a dedicated computer?

It'll run on a computer you already use — but your crew works around the clock, and your everyday machine sleeps, restarts, and leaves the house. A dedicated machine means the workspace is always reachable. Anything with 8 GB of RAM and 200 GB of storage is plenty to get started.

What operating systems does it run on?

All three, day one: macOS (signed Apple Silicon app), Windows 11 x64 (one PowerShell command that installs the Linux build into a WSL 2 distribution, with your browser as the interface), and Linux (native Podman with a systemd host and verified updater). Resident computers work the same way everywhere — one isolated computer per agent.

Do I need to install WSL before installing on Windows?

No — and there's nothing to download either. Open an ordinary PowerShell window (not "Run as Administrator") and run irm https://1helm.com/install.ps1 | iex. Expect three things: one Windows permission pop-up, which you click Yes to; a first run of about a minute that ends by printing "Restart required"; and then, after you restart and sign back in as the same user, the same command again, which takes about six and a half minutes and finishes by opening your browser at http://localhost:8123. About nine minutes in total. Because no Windows application ships, there's no installer to sign and SmartScreen never appears. Full detail is in the Windows guide.

How do I uninstall 1Helm?

Start with Settings → Admin → Prepare to remove 1Helm, which prepares resident machines for safe deletion — export anything irreplaceable first. Then: on macOS drag the app to the Trash; on Linux run sudo /opt/1helm/uninstall-host.sh; on Windows run irm https://1helm.com/uninstall.ps1 | iex from an ordinary PowerShell window. macOS and Linux deliberately leave your data root in place for recovery — delete it yourself if you truly want it gone. Windows is the exception: it unregisters the 1helm WSL distribution, and that deletes the virtual disk your whole data root lives on, so it asks you to type remove first and there is no undo.

Which AI models can I use?

The ones you already pay for. Connect ChatGPT, Claude, Gemini, and xAI accounts, plus OpenRouter, NVIDIA NIM, Cloudflare, GLM, or any OpenAI-compatible endpoint. Swap models mid-conversation — the agent keeps its identity, memory, and skills.

Can agents see my files?

No. Each resident lives in its own isolated Linux computer with no view into your real computer. On macOS that is an Apple container machine; on Linux and Windows it is a dedicated OCI container. It makes folders, saves files, and runs commands entirely inside its own world. Anything it needs beyond that is brokered explicitly, by you or by Skipper, with the narrowest possible grant.

What happens when I close the tab?

Nothing bad — that's the point. The workspace lives on your helm computer, not in the tab. Threads, memory, files, and scheduled work all persist. Open your workspace URL from any device and pick up exactly where you left off.

How is this different from my AI provider's "memory"?

Provider memory stores facts — "prefers bullet points" — shared across every conversation. A resident's memory is per-channel and includes procedures: how you like your invoices formatted, where the files live, what it learned last month. Facts versus skills.

Can my agent send emails on my behalf?

Not yet, by design. The Gmail connection supports inventory, search, read, and draft creation — a human presses send. iMessage replies via Photon go only to the exact conversation that texted in, and new destinations stay blocked until you grant them.

Is it open source? What does it cost?

Fully open source and free. You bring the models you already pay for and the computer it runs on. Your installation and all of its data run on your machine.

What if my helm computer dies?

Your data root (~/Library/Application Support/1Helm-OCI-v1 on macOS, or /var/lib/1helm-oci-v1 on Linux — including inside the 1helm WSL distribution on Windows) holds the control plane and resident worlds. Back it up as one coherent installation, reinstall 1Helm, and your crew comes back. Never delete that path during a move.

Why a crew instead of one big agent?

Isolation, specialization, and continuity. Your finances shouldn't share a filesystem with your travel plans, and an agent that owns one job gets genuinely good at that job. Each crew member has its own computer, memory, and skills.

Where do I start?

Download 1Helm, name your workspace, and say hello to Skipper in #main. Then ask for your first crew member — a task, a goal, anything you want a dedicated agent for. The story shows you how it goes.