# Quickstart (/docs/getting-started/quickstart)



This quickstart takes you from a fresh install to a working `~/Code` tree. You'll
log in, let Bowline observe your workspace, approve the device, and run a project
without copying env files or rebuilding worktrees by hand.

This guide assumes you've already [installed Bowline](/docs/getting-started/installation).

## 1. Log in and choose a workspace root [#1-log-in-and-choose-a-workspace-root]

Start by logging in and pointing Bowline at the folder you want as your workspace
root. Most people use `~/Code`.

```bash title="Terminal"
bowline login --root ~/Code
```

First contact is deliberately safe. Bowline observes your existing workspace
without changing it, then reports concrete state. A few things to know:

* If `~/Code` already exists, Bowline mounts it as your workspace root and reads
  what's there. It never silently moves projects from other folders into
  `~/Code`.
* If the root doesn't exist, Bowline can create that empty root or mount an
  existing workspace there.
* `--headless` runs login without opening a browser, which is useful on remote
  hosts.

## 2. Approve the device [#2-approve-the-device]

Logging in proves your account identity. It does not, by itself, hand a new
machine the keys to decrypt your workspace; that's a separate, deliberate step.

On your very first device, Bowline establishes trust during login. On any later
device, Bowline raises a [Device Approval Request](/docs/concepts/device-trust)
that an already-authorized device or a
[Recovery Key](/docs/concepts/recovery) grants. Check pending requests at any
time:

```bash title="Terminal"
bowline status
```

When a request is pending, both devices show a short matching code so you can
confirm you're approving the right machine. Approve it from a trusted device:

```bash title="Terminal"
bowline approve
```

## 3. Watch the workspace appear [#3-watch-the-workspace-appear]

Once the device is trusted, your whole `~/Code` tree becomes visible before
every byte is local. Bowline shows the structure immediately and hydrates file
contents the moment you touch a project.

```bash title="Terminal"
bowline status
ls ~/Code
```

`bowline status` defaults to the current project when you're inside one, with a
compact summary of the whole workspace when another project needs attention. Run
it with `--workspace` to see the whole tree, or `--watch` to stream changes as
they happen.

## 4. Open a project and run it [#4-open-a-project-and-run-it]

Now work the way you always do. Change into a project and run it. Bowline
hydrates the project on touch, restores dependencies, applies any
[Setup Recipe](/docs/concepts/setup-recipes), and materializes the project's
[env files](/docs/concepts/env-sync) where your tools expect them.

```bash title="Terminal"
cd ~/Code/acme/web
pnpm dev
```

That's the whole promise: `cd ~/Code/acme/web && pnpm dev` works here exactly
like it does on your other machines. The code, the dependencies, and the `.env`
are just there.

<Callout type="info">
  Your edits sync as you go. New files, uncommitted changes, and folders with no
  Git remote all follow your workspace automatically through encrypted snapshots,
  no commit required. Git stays your tool for commits and branches. See
  [Git and source control](/docs/concepts/git-and-source-control).
</Callout>

## 5. Explore safe next actions [#5-explore-safe-next-actions]

When something needs your attention, Bowline tells you what to do next instead of
making you guess. Ask for the safe next actions for your current state:

```bash title="Terminal"
bowline actions
```

You can also open the terminal UI for an interactive view of workspace health,
pending approvals, and conflicts:

```bash title="Terminal"
bowline tui
```

## Next steps [#next-steps]

* [Add a machine](/docs/getting-started/add-a-machine): get the same tree on a
  second device.
* [Connect remote hosts](/docs/getting-started/connect-remote-hosts): bring up
  a remote agent host over SSH.
* [Workspace model](/docs/concepts/workspace-model): understand snapshots,
  heads, and overlays.
* [Status and health](/docs/concepts/status-and-health): what `healthy`,
  `attention`, and `limited` mean.