# Connect remote hosts (/docs/getting-started/connect-remote-hosts)



`bowline connect` is the agent-native happy path for putting your workspace on a
remote host. Over your existing SSH access, it installs Bowline, starts the
daemon, completes device trust, and leaves the host as a normal authorized
`~/Code` device, ready for you or an agent to work in.

## What `bowline connect` does [#what-bowline-connect-does]

`bowline connect <host>` runs a Remote Bootstrap. It uses your SSH configuration
as transport, then relies on Bowline device trust for decryption authority. In
one command it:

1. Installs Bowline and starts the daemon on the remote host.
2. Raises a Device Approval Request from the remote host.
3. Completes the approval as a
   [Delegated Device Approval](/docs/concepts/device-trust) from your authorized
   local session.
4. Mounts the workspace root and verifies sync is ready.
5. Optionally hands off into a project agent session.

<Callout type="warn" title="SSH is transport, not trust">
  A successful SSH connection, host login, or copied binary is never workspace
  trust on its own. The remote host becomes an
  [Authorized Device](/docs/concepts/device-trust) only when the bootstrap
  completes the encrypted device grant, not because SSH reached the host.
</Callout>

## Connect a host [#connect-a-host]

Point `connect` at a host you can already reach over SSH. Use the same address
you'd pass to `ssh`.

```bash title="Terminal"
bowline connect linux-server-1
```

By default the remote workspace root matches your local root. Override it with
`--root`, and preview the run without changing anything with `--dry-run`:

```bash title="Terminal"
bowline connect linux-server-1 --root ~/Code --dry-run
```

`bowline connect` reports each bootstrap step (`request`, `compare`, `approve`,
`accept`, `sync`) so you can see trust complete. Add `--json` for a structured
result you can check in scripts. Treat the host as trusted only when the command
finishes with no blocked steps.

## Hand off to an agent [#hand-off-to-an-agent]

When you want the remote host to start working immediately, pass a project, a
task, and an agent. Bowline completes the bootstrap, then starts an
[agent lease](/docs/concepts/agent-leases) for the task.

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

The agent receives a scoped lease on the same workspace reality you'd have:
fresh base, inherited project env, bounded hydration, and an explicit write
target. See [work with coding agents](/docs/guides/working-with-agents) for the
full workflow.

## Headless hosts [#headless-hosts]

Remote hosts are often headless. That's fine. The CLI and TUI are the source of
truth. Use `--headless` during login flows, and manage the host with
`bowline status`, `bowline actions`, `bowline tui`, and `bowline approve`. See
[Linux](/docs/platforms/linux) for service and notification details.

## Next steps [#next-steps]

* [Work with coding agents](/docs/guides/working-with-agents): drive agents on
  local and remote hosts.
* [Device trust](/docs/concepts/device-trust): how delegated approval keeps
  remote hosts safe.
* [Linux](/docs/platforms/linux): the systemd service and headless usage.