# Introduction (/docs)



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 [#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:

* You see the full tree before every byte is local. Cold projects hydrate the
  moment you touch them; hot projects behave like ordinary local directories.
* 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 under a lease that scopes its authority, budget, and audit.

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 [#who-its-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 [#core-concepts]

Bowline's model comes from a small set of ideas. Each maps to a concept page.

| Concept                                                         | What it is                                                                             |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Workspace model](/docs/concepts/workspace-model)               | Snapshots, heads, and overlays: how project state advances safely.                     |
| [Sync and continuity](/docs/concepts/sync-and-continuity)       | Near-continuous snapshots that capture work as you go, not last-writer-wins file sync. |
| [Conflicts](/docs/concepts/conflicts)                           | How Bowline preserves both sides when work diverges, and how you repair it.            |
| [Env sync](/docs/concepts/env-sync)                             | How `.env` files are imported, merged by key, and rematerialized.                      |
| [Path policy](/docs/concepts/path-policy)                       | The `.bowlineignore` file for including and excluding paths from sync.                 |
| [Setup recipes](/docs/concepts/setup-recipes)                   | The `.bowlinesetup` file for preparing a fresh machine or agent.                       |
| [Git and source control](/docs/concepts/git-and-source-control) | Why `.git/` syncs as opaque state and Bowline never runs Git for you.                  |
| [Device trust](/docs/concepts/device-trust)                     | How a new machine or agent host earns workspace decryption access.                     |
| [Recovery keys](/docs/concepts/recovery)                        | Word-based recovery when no authorized device is available.                            |
| [Work views](/docs/concepts/work-views)                         | Isolated, review-before-apply project views under `~/Code/.work`.                      |
| [Agent leases](/docs/concepts/agent-leases)                     | Scoped, audited authority for coding agents working in your projects.                  |
| [Status and health](/docs/concepts/status-and-health)           | What `healthy`, `attention`, and `limited` mean, and when Bowline notifies you.        |
| [Architecture](/docs/concepts/architecture)                     | The daemon, control plane, byte plane, and encryption model.                           |

## How it fits together [#how-it-fits-together]

A typical first session has a few steps.

1. Install Bowline and run `bowline login --root ~/Code`. Bowline observes your
   existing workspace without changing it, then reports concrete state.
2. Approve the device. A new machine authenticates your account, then requests
   workspace decryption access that an existing trusted device or a Recovery Key
   grants.
3. Work normally. Open a project, and Bowline hydrates it on touch, restores
   dependencies, and materializes its env. Your edits sync as you go.
4. Add another machine or a remote agent host. Each one gets the same `~/Code`
   tree after one approval.
5. Hand work to an agent. A lease scopes what the agent can touch; its output
   becomes a new Workspace Snapshot or a review-ready change.

## Next steps [#next-steps]

Pick the path that matches how you want to start.

* **Getting started**: [install Bowline](/docs/getting-started/installation),
  walk through your [first session](/docs/getting-started/quickstart), and
  [add a second machine](/docs/getting-started/add-a-machine).
* **Concepts**: understand the
  [workspace model](/docs/concepts/workspace-model),
  [device trust](/docs/concepts/device-trust), and
  [env sync](/docs/concepts/env-sync).
* **CLI reference**: start with the
  [CLI overview](/docs/cli/overview) and the full
  [command reference](/docs/cli/commands).
* **For agents**: read the
  [agent-native contract](/docs/agents/contract) for driving Bowline from a
  coding agent.