Device trust

Bowline keeps two things apart: proving who you are, and releasing the keys that decrypt your workspace. Signing in proves your identity through your account provider. A separate Device Approval Request grants one specific machine or agent host the keys to decrypt your accepted workspace root. This page explains that split, the approval lifecycle, how an Authorized Device gets access, and how you approve or revoke devices.

Identity is not decryption access

Account authentication and workspace decryption are two separate steps. WorkOS/AuthKit handles account identity, and it proves you're you. It does not, by itself, hand a new device the keys to read your code.

A device that has authenticated your account but has no approved grant can see that a workspace exists, but it cannot decrypt your files. Decryption access comes only from an existing Authorized Device or a Recovery Key.

The Device Approval Request lifecycle

A Device Approval Request is a pending trust decision that lets a signed-in device or agent host receive workspace decryption access. It moves through a short lifecycle.

1. A new device runs bowline login --root ~/Code, authenticating your account.
2. Bowline creates a pending Device Approval Request and shows a short matching code on the new device.
3. An Authorized Device approves the request, encrypting a device grant to the new device's public key.
4. The new device accepts the grant and stores the workspace key locally. It's now an Authorized Device.

The request is durable status first and a notification second. It stays visible in bowline status until it's approved, denied, or revoked, so you never depend on a popup to act on it.

The short matching code

Every Device Approval Request shows a short matching code on both the requesting device and the approving device. The code lets you confirm you're approving the device you think you are before any keys are released.

Check that the code on the new device matches the code shown next to the pending request on your Authorized Device. If they don't match, deny the request with bowline devices deny <id>.

What an Authorized Device gets

Once approved, a device becomes an Authorized Device for the whole accepted workspace root, normally ~/Code. Bowline does not create default per-project or per-path device permissions.

• An Authorized Device decrypts the accepted workspace root like any other trusted device.
• There are no partial, project-scoped, or limited devices. Trust is for the root.
• Agent leases, not device grants, scope what an agent can touch. Device trust answers "can this host decrypt the workspace"; a lease answers "what may this agent task do."

Delegated Device Approval

You don't have to be physically at an Authorized Device to approve a new one. Delegated Device Approval lets an already authorized local session create the encrypted grant, including an agent acting from a trusted device after explicit user intent.

This is what powers Remote Bootstrap. bowline connect <host> installs Bowline on a reachable remote host over SSH and completes device trust through Delegated Device Approval. The authorized local session creates the grant; the remote host becomes a full Authorized Device for the accepted root, not a one-project or lease-scoped device.

Where approval requests surface

Pending Device Approval Requests appear on every platform through the CLI and TUI, with ambient mirrors where the OS supports them. The CLI and TUI are always complete, including on headless hosts.

Approving a new device

To grant a new machine or agent host access, confirm the codes and approve from an Authorized Device. These steps assume you still have at least one Authorized Device. If you don't, see Recover access to your workspace.

1. On the new device, run bowline login --root ~/Code. It authenticates your account and creates a Device Approval Request with a short matching code.
2. On an Authorized Device, run bowline status to see the pending request, including the device name, request age, and matching code. You can also run bowline devices list.
3. Confirm the matching code is identical on both devices.
4. Run bowline approve to approve the first pending request, or bowline approve <request> for a specific one. Add --yes to skip the prompt and --json for scriptable output.
5. Bowline encrypts a device grant to the new device's key, and the new device accepts it. Verify with bowline status on the new device, which now reports an Authorized Device and a healthy status.

Revoking a device

When a device is lost, decommissioned, or no longer trusted, revoke it. Revocation removes its workspace decryption authority right away.

Run bowline revoke <device> to revoke a device. A revoked device can no longer decrypt the workspace, and it cannot create work views or leases. Use --dry-run to preview the change and --idempotency-key <key> to make a retry safe.

Next steps

• Recovery keys: word-based access when no Authorized Device is available.
• Recover access to your workspace: the task guide for both approval and recovery.
• Add a machine: bring a second device into your workspace.
• Connect remote hosts: Remote Bootstrap over SSH.
• Agent leases: how a lease scopes an agent's authority on a trusted host.
• CLI commands: full reference for bowline devices, approve, and revoke.