Introduction
Bowline gives every machine and coding agent the same ~/Code tree, so source, env, and project state follow you while Git stays your tool.
Bowline makes your developer code folder appear and stay useful across every
machine and coding agent you authorize. Your source, configuration, .env
files, opaque Git state, and in-progress work follow your workspace
automatically, with no daily ceremony around Git, dashboards, or manual sync.
The promise: cd ~/Code/acme && pnpm dev works the same on your laptop, your
desktop, and a remote agent host. The code is just there.
What Bowline is
Bowline is a developer workspace sync engine. You accept one workspace root
(normally ~/Code), and Bowline keeps that whole tree available on every
authorized device:
- Bowline discovers the workspace, materializes the selected project first, and continues the rest in the background. A project marked ready is an ordinary local directory with readable files.
- Dev junk stays out of the way. Generated folders, dependencies, and caches
are classified and skipped, so you sync source-like state, not
node_modules. - Your environment follows the code.
.env,.env.local, and.env.*files are imported, encrypted, synced, and rematerialized where your tools expect them. - Agents get a usable workspace. A trusted coding agent works in the real project directory with its own native tools, or in an isolated work view when you want review before apply.
Bowline is not a Git wrapper, a decentralized forge, or a cloud devbox. Git stays your tool for commits, branches, and remotes. Bowline syncs the workspace underneath.
Who it's for
Bowline is for developers who work across more than one machine and for the
coding agents they run. If you have ever copied .env files between machines,
rebuilt a stale worktree on a fresh box, re-granted secrets to an agent host, or
lost uncommitted work that never made it into a commit, Bowline removes that
work.
Core concepts
Bowline's model comes from a small set of ideas. Each maps to a concept page.
| Concept | What it is |
|---|---|
| Workspace model | Snapshots, heads, and overlays: how project state advances safely. |
| Sync and continuity | Near-continuous snapshots that capture work as you go, not last-writer-wins file sync. |
| Conflicts | How Bowline preserves both sides when work diverges, and how you repair it. |
| Env sync | How .env files are imported, merged by key, and rematerialized. |
| Path policy | The .bowlineignore file for including and excluding paths from sync. |
| Setup recipes | The .bowlinesetup file for preparing a fresh machine or agent. |
| Git and source control | Why .git/ syncs as opaque state and Bowline never runs Git for you. |
| Device trust | How a new machine or agent host earns workspace decryption access. |
| Recovery keys | Word-based recovery when no authorized device is available. |
| Work views | Isolated, review-before-apply project views under ~/Code/.work. |
| Coding agents | How agents work in your real project directories and work views. |
| Status and health | What healthy, attention, and limited mean, and when Bowline notifies you. |
| Architecture | The daemon, control plane, byte plane, and encryption model. |
How it fits together
A typical first session has a few steps.
- Install Bowline and run
bowline setup --root ~/Code. Bowline observes your existing workspace without changing it, then reports concrete state. - Approve the device. A new machine authenticates your account, then requests workspace decryption access that an existing trusted device or a Recovery Key grants.
- Work normally. Bowline materializes your selected project, restores dependencies, and writes its env before reporting it usable. Your edits sync as you go while the remaining workspace continues in the background.
- Add another machine or a remote agent host. Each one gets the same
~/Codetree after one approval. - Hand work to an agent. Point it at the project directory, or at a work view when you want its output held for review before it reaches the main project.
Next steps
Pick the path that matches how you want to start.
- Getting started: install Bowline, walk through your first session, and add a second machine.
- Concepts: understand the workspace model, device trust, and env sync.
- CLI reference: start with the CLI overview and the full command reference.
- For agents: read the agent-native contract for driving Bowline from a coding agent.