# Work with coding agents (/docs/guides/working-with-agents)



This guide walks through handing real work to a coding agent. You start a lease,
give the agent its prompt and context, let it work in your project, and then
review and accept the result. You'll also see how to keep an agent's output
isolated for review-before-apply and how to spin up a remote agent host. The
agent works in the same `~/Code` tree you use, so reviewing its output means
opening a folder and running tests, not learning a console.

## Before you start [#before-you-start]

You need an Authorized Device with a synced project. A lease requires a real
latest Workspace Snapshot, so confirm the project is synced first:

```bash
bowline status --root ~/Code --project ~/Code/acme/web
```

If the project hasn't synced yet, status reports that as attention, and lease
creation will tell you the same. Resolve any conflicts before handing off, since
a degraded workspace state stops risky agent actions.

## Hand a task to a local agent [#hand-a-task-to-a-local-agent]

Start a lease for the task, then give the agent the context and prompt the lease
generates. By default the agent writes to the real project directory, and a
non-conflicting result advances the Workspace Head automatically.

1. Start the lease and capture the returned next-step commands:

   ```bash
   bowline agent start ~/Code/acme/web \
     --task "fix auth callback race" \
     --hydrate-budget 500MB --json
   ```

2. Fetch the structured context and the rendered prompt for the run:

   ```bash
   bowline agent context --lease <id> --json
   bowline agent prompt --lease <id>
   ```

3. Let the agent work. If it needs more hydration budget mid-run, grant it
   explicitly:

   ```bash
   bowline agent budget --lease <id> --add 250MB
   ```

4. Review the result with normal tools, then signal completion:

   ```bash
   cd ~/Code/acme/web
   pnpm test
   bowline agent complete --lease <id>
   ```

<Callout type="info">
  Secret values never enter the prompt. `bowline agent prompt` emits env key
  names and grant identifiers; the runtime receives the actual values only when
  policy permits.
</Callout>

## Keep output isolated for review [#keep-output-isolated-for-review]

When you want to review before anything touches the main project, bind the lease
to a Work View with `--work-view`. The agent's writes stay in an isolated
overlay under `~/Code/.work` until you accept them.

1. Start a work-view lease:

   ```bash
   bowline agent start ~/Code/acme/web \
     --task "fix auth callback race" \
     --work-view
   ```

2. Inspect the isolated output once the agent finishes:

   ```bash
   cd ~/Code/.work/acme/web/<name>
   bowline diff <name>
   pnpm test
   ```

3. Apply it into the main view, or drop it if it's not good:

   ```bash
   bowline accept <name>
   # or
   bowline discard <name>
   ```

## Spin up a remote agent host [#spin-up-a-remote-agent-host]

To run an agent on another machine, bootstrap the host and hand off the task in
one step. `bowline connect` uses your SSH access as transport and Bowline device
trust for decrypt authority, then creates the remote lease for you.

```bash
bowline connect linux-server-1 \
  --project ~/Code/acme/web \
  --task "fix auth callback race" \
  --agent codex
```

This makes the host an Authorized Device with the same real `~/Code`, creates
the remote lease, and returns safe next actions pointing at the Work View, the
agent context, and the redacted prompt for the named agent. Treat the host as
trusted only when the command completes without blocked steps. SSH reachability
alone is not workspace trust.

## Review a review-ready lease [#review-a-review-ready-lease]

A completed lease whose output needs your review is a Review-Ready Agent Lease.
It appears in status and in the work list as soon as it's ready:

```bash
bowline status --root ~/Code --project ~/Code/acme/web
bowline work
```

Open the output, run the checks you care about, and apply or drop it. A
review-ready lease is work waiting for a decision, not a workspace failure.

<Callout type="warn" title="Important">
  Accepting agent output never commits, pushes, or opens a pull request, and it
  never makes policy, secret, or blocked-path changes on the agent's say-so.
  Publishing stays your Git workflow after the change reaches the main view.
</Callout>

## Next steps [#next-steps]

* [Agent leases](/docs/concepts/agent-leases): how a lease scopes authority,
  budget, and writes.
* [Work views](/docs/concepts/work-views): the review-before-apply mode used by
  `--work-view`.
* [Connect remote hosts](/docs/getting-started/connect-remote-hosts): more on
  `bowline connect` and device trust.
* [Agent-native contract](/docs/agents/contract): driving Bowline from the
  agent's side.
* [Agent workflows](/docs/agents/workflows): prompt recipes and primitive tools.