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 unprivileged LXC per resident
Windows	One private WSL 2 distribution per resident, drive mounts and interop disabled

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 you through Photon device authorization and conversation mapping. An allowlisted inbound text creates a real thread, invokes the mapped agent, and sends the reply back to that exact conversation. New outbound destinations stay blocked unless you explicitly grant them.

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.

Every update preserves your data root:

macOS:  ~/Library/Application Support/1Helm
Linux:  /var/lib/1helm

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.

Security

Resident computers have no access to your real machine — no home mount on macOS, unprivileged LXC on Linux, no drive mounts or interop on Windows.
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.
Releases are Developer ID signed, notarized, stapled, and Gatekeeper-verified before publication.

Troubleshooting

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 (signed x64 installer with one private WSL 2 world per agent), and Linux (systemd install with a verified updater). Resident computers work the same way everywhere — one isolated machine per agent.

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 on its own virtual machine with no view into your real computer. 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 on macOS, /var/lib/1helm on Linux) holds the workspaces, resident state, and credentials. Back it up, move it to a new machine, reinstall 1Helm, and your crew comes back. Never delete that directory during a move.

Is demo.1helm.com the product?

No — it's a public sandbox so you can poke around. The real product is the downloadable, self-hosted 1Helm runtime, and your installation's state stays on your machine.

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.