Security architecture

The Safety page describes what Halo guarantees. This page describes how those guarantees are enforced. You don't need it to use Halo.

The service cannot act on your machine

• The service only proposes. The Halo service reads your request and returns a proposed action.
• Signed for your request. The proposal is signed, and the signature binds it to the exact request you sent.
• Checked locally. Halo on your machine verifies the signature before using the proposal, and refuses any proposal that doesn't verify or was made for a different request.

Nothing the service sends can run on your computer without passing these local checks.

Effects are determined locally

Halo doesn't rely on the service's description of an action. Before anything runs, the client works out the action's real effect itself: which files it touches, how much data it moves, and which permissions it needs. That local result decides whether the action runs straight away, needs your approval, or is refused.

Exactly what was previewed

An approval is tied to the objects that were shown in the preview.

• Files that start matching after the preview are not added.
• If a previewed file changes before the action runs, Halo stops instead of acting on something you didn't see.

Commands run in a sandbox

When an action runs an external program, Halo runs it inside an operating-system sandbox limited to what that action needs: Seatbelt on macOS, bubblewrap on Linux.

• No sandbox, no run. If the sandbox cannot be set up, Halo does not run the command.
• Opting out per run. On a machine where no sandbox is possible, halo --unconfined offers to run a command without one. Each such run asks separately, every time.

Remembered permissions

• What can be remembered. You can allow some kinds of access permanently, such as reading outside the working folder. These choices are stored in ~/.halo/authorities.json and listed by /permissions.
• What never is. Stopping processes, system changes and administrator access are asked every time and never remembered.

Your account key

• Exchanged at connection. Halo presents your Memcode key when it connects, and the service exchanges it for a short-lived session.
• Identity only. The key identifies your account to the service. It grants nothing on your computer.
• Project .env files are never read. Halo doesn't read a .env file in the folder you are working in, so a project cannot sign Halo into a different account.

Releases

• Signed releases. Each release's checksums file is signed with Halo's release key.
• Upgrades always verify. halo upgrade checks the signature and the checksum before replacing itself, and changes nothing if either fails.

For the install script's behavior, see Advanced installation.