Trust

Security

Terminals and previews make Helmlane remote access to your computers. This is how it is protected: what stays on your machines, how you prove it is you, what is recorded, what is refused, and what is encrypted.

The shape of it#

• Your computers only dial out. The Helmlane agent on each computer opens a connection to the control plane. Nothing on your network has to accept connections, and there is no port to open.
• Only the folders you share. A computer serves the folders you approved on that computer and nothing else. It refuses to share the root folder or any folder containing its own credential, and a path outside the placement is refused whatever any rule says.
• Apps never reach your computer directly. Phones, the web app and connected agents talk only to the control plane. They never learn a computer’s address, an agent’s credentials, or the agent’s own conversation identifiers.
• The computer’s credential stays in the keychain. On a Mac it lives in the login keychain, readable only by Helmlane’s signed helper. On Linux it lives in your keyring, or in an encrypted file bound to the machine where there is no keyring.

Signing in#

• Passwords are stored only as a salted scrypt hash, and a new account confirms its email address first.
• Passkeys sign you in without a password. A passkey that verifies you on the device counts as a second factor on its own. Sign-in answers the same way for an address that has an account and one that does not, so it cannot be used to find out who uses Helmlane.
• Authenticator codes (TOTP) and one-time recovery codes work as a second factor. Recovery codes are stored only as hashes.
• Sessions are listed per device in the app, where you can rename them, sign one out, or sign out everywhere else. Access tokens last fifteen minutes and are refreshed; an unused session ends after ninety days.
• No IP addresses or locations in your device list. To tell you whether a device is new, Helmlane keeps only a device identifier, its platform, and when it first appeared on your account.

Step-up: confirm it’s you#

A signed-in phone is not enough for the most sensitive actions. These always ask you to prove it is you again, and no setting can turn that off:

• opening a terminal;
• pushing to a branch your command rules protect;
• changing a computer’s command rules;
• creating a token that enrolls a new computer;
• adding or removing a passkey, setting up or turning off an authenticator, creating new recovery codes, changing your password, changing these step-up settings;
• signing out another session, or all of them.

You can add more: opening a preview, exporting the audit log, approving a held command, removing a computer, rotating its credential, and pairing a new phone.

How you prove it. If your account has a passkey or an authenticator, step-up asks for one of those — or a recovery code — and a password is not accepted. An account without a second factor confirms its password, so step-up can never lock you out. Five wrong attempts spend the challenge.

What a confirmation is good for. Each one produces a single-use receipt bound to your session, to the operation, and to the exact request — its method, path and body — so it cannot be replayed or used for a different command. Afterwards your session stays elevated for a short window (ten minutes unless you change it, between one and sixty), during which terminals, protected pushes, previews, approvals, exports and device actions do not ask again. Credential changes and rule changes always ask.

The audit log#

Every command that reaches one of your computers produces an entry: who asked (you, from which session and device, and how that session signed in — or which schedule or mission, and who set it up), which computer and folder, what was asked for, which rule decided, what the decision was, and how it ended.

• It records what was attempted, never what was said. There is no room in an entry for file contents, diffs, prompts, agent replies, environment variables or credentials.
• A decision is never silent. Every command is allowed, denied or held for approval, and that is recorded — including when no rule matched and the default applied.
• Tamper-evident. Entries form a hash chain: changing or removing one breaks every entry after it, and the app can verify the chain. Anyone holding an earlier chain head can also tell if the end of the log was cut off.
• Retention is recorded. Entries are kept for 180 days by default. Removing old entries writes an entry of its own, so a trimmed log still verifies.
• Exportable. Download the log as NDJSON, with the chain head at the end.

Command rules#

Each computer has rules that decide, before anything runs, whether a command is allowed, denied, or held for your approval. Commands are sorted into classes — force-push, recursive delete, privilege escalation and so on — and the lowest-numbered matching rule decides. The control plane checks every command, and the agent on the computer checks it again with the same rules, so a computer that has not yet received your latest rules still applies the defaults rather than nothing.

The defaults

• main and master are protected branches by default; pushing to one also needs step-up.
• Held commands wait five minutes for your decision by default, then lapse. You can approve inline, from the Needs you list, or from a notification after unlocking the phone; a rule can require step-up for the approval itself.
• A new kind of command is asked about, never allowed silently. The fallback decision is “ask”.
• Unattended work is held to a stricter standard. Nobody is at the phone at 3 a.m., so schedules and missions are denied what a person would be asked about.
• You can change the rules per computer, and try a command against them before saving. Saving requires step-up.

Preview origins#

A preview puts a dev server running on your computer on your phone. The dev server’s own code is untrusted, so each preview is isolated:

• Its own origin. Every preview gets a random 128-bit address under a separate preview domain. Its code cannot read Helmlane’s storage or another preview’s.
• A cookie only that preview can see. Access uses an HttpOnly, host-only cookie tied to the one preview and to the session that opened it. Neither the cookie nor any Helmlane credential ever reaches your dev server.
• A ticket that works once. Opening a preview exchanges a ticket that lives sixty seconds, works once, and is stored only as a hash. A copy found later in history or a log has already been spent.
• Not every port. The computer itself refuses a preview of system ports (below 1024) and of local services a link must never reach — browser and Node.js debugging ports, databases such as PostgreSQL, MySQL, Redis and MongoDB, the Docker API, and Helmlane’s own endpoints — whatever your rules say. The refusal is in the audit log.
• It ends by itself. A preview lasts at most four hours. Closing it, or signing out the device that opened it, cuts every connection within seconds.
• No framing by other sites. Only the preview itself and the Helmlane web app may embed it.

Encryption#

• In transit: every connection between apps, computers and the control plane uses HTTPS or secure WebSockets.
• At rest, per account: chat messages, drafts, prompts, review comments, commands sent to your computers, device tokens and uploaded files are sealed with AES-256-GCM under a data key that belongs to your account alone. Account keys are themselves wrapped by server keys kept outside the database, so a database dump or backup on its own reveals nothing readable. Destroying an account’s keys makes its sealed data unreadable for good.
• Search without plaintext: history search matches keyed hashes of words, under a key unique to your account. The server can tell that two of your messages share a word, but not which word.
• Secrets you never see again — session tokens, API tokens, recovery codes, enrollment tokens — are stored only as hashes. Webhook signing secrets are derived when needed and never stored.

Notifications#

Apple and Google deliver push notifications, so their text is written to say as little as possible: it is built only from the kind of event, the agent, and a number such as a percentage. Project and chat names, prompts, replies, file paths and computer names never appear in a notification — the details are behind the tap, where the app is signed in. Lock-screen actions require the phone to be unlocked, and approvals that need step-up open the app first.

Tokens and connected apps#

• Enrollment tokens for new computers are single-use, expire within fifteen minutes, carry a checksum character, and are stored as hashes.
• API tokens for the MCP server are created only through a device authorization you approve, with a read or read-and-dispatch scope and an expiry. Each request is checked against an explicit list of allowed actions — security settings, sessions, terminals, port forwards and removing computers are never on it — and every use is recorded. Revoking a token takes effect on the next request.

Untrusted content#

Anything that comes from outside — a webhook payload, a pull-request comment, a CI log, a file an agent read — is treated as data, not instructions. It keeps its origin attached so the app can mark it, and it can never choose the computer, folder or agent that runs the work: those come only from settings you made.

What it does not protect against#

• The agents themselves. A coding agent runs as you, with your permissions, in the folders you shared. Command rules decide what Helmlane sends; they do not sandbox what an agent does on its own. Use each agent’s own permission settings too.
• A compromised computer. Anyone with control of your computer, or root on a Linux box, can reach what the agent can.
• A compromised control plane. See the notes on the audit chain and on encryption above.

Report a vulnerability#

Please write to support@helmlane.com with the details and how to reproduce it. Do not open a public issue for a security problem.