dap/readme.md

# dap

`dap` is a data access proxy for SSH-based machines. It scans your OpenSSH config, lists configured hosts, adds and edits SSH host blocks, connects to remote machines, proxies remote ports, and mounts remote folders into your local filesystem.

`dap` uses OpenSSH as the source of truth. Your `~/.ssh/config`, SSH agent, keys, `ProxyJump`, known hosts, and normal `ssh` behavior remain in control.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

Install globally:

```bash
pnpm install -g dap
```

Or install in a project:

```bash
pnpm install dap
```

## Quick Start

Open the interactive dashboard:

```bash
dap
```

List configured SSH hosts:

```bash
dap list
```

Add a host:

```bash
dap add production --hostname 203.0.113.10 --user root --identity-file ~/.ssh/id_ed25519
```

Connect to a host:

```bash
dap ssh production
```

Proxy a remote PostgreSQL port to your local machine:

```bash
dap proxy production --local 5433:127.0.0.1:5432
```

Mount a remote folder locally:

```bash
dap mount production:/var/www ./mounts/production-www
```

Check local system support:

```bash
dap doctor
```

## Commands

### `dap`

Starts the interactive dashboard.

```bash
dap
```

The dashboard can list hosts, add hosts, edit hosts, connect over SSH, start port proxies, mount remote paths, and run diagnostics.

### `dap list`

Lists hosts found in your SSH config.

```bash
dap list
```

`dap` reads the main config and included files.

### `dap add`

Adds a DAP-managed host block to the main SSH config.

```bash
dap add staging --hostname staging.example.com --user deploy --port 22 --identity-file ~/.ssh/id_ed25519
```

Generated block:

```sshconfig
# dap:begin staging
Host staging
  HostName staging.example.com
  User deploy
  Port 22
  IdentityFile ~/.ssh/id_ed25519
# dap:end staging
```

If required fields are missing, `dap add` asks for them interactively.

### `dap edit <host>`

Edits a host in the main SSH config.

```bash
dap edit production --user deploy --identity-file ~/.ssh/id_ed25519
```

Editable fields include:

- `HostName`
- `User`
- `Port`
- `IdentityFile`
- `ProxyJump`
- `LocalForward`
- `RemoteForward`

DAP-managed blocks are updated directly. Existing non-DAP host blocks are shown as a diff before writing unless `--yes` is passed.

### `dap ssh <host>`

Connects to a host using the system `ssh` binary.

```bash
dap ssh production
```

By default this starts a session bridge and temporarily places a `dap` command into the remote session `PATH`. The command is created in a temporary remote directory and removed when the SSH session exits.

Disable the bridge when you want a plain SSH call:

```bash
dap ssh production --no-bridge
```

Pass raw SSH arguments after `--`:

```bash
dap ssh production -- -A
```

### Remote Session `dap`

When you connect with `dap ssh <host>`, the remote shell receives a temporary `dap` command.

Inside the remote session:

```bash
dap info
```

Mount the current remote directory into a local path:

```bash
dap mount . ./dap-mounts/project
```

The remote command talks back to the local DAP session through an SSH reverse forward. The bridge uses a one-time token and only exposes explicit DAP actions.

The remote machine needs `curl` for bridged remote commands.

### `dap proxy <host>`

Starts an SSH local forward.

```bash
dap proxy production --local 5433:127.0.0.1:5432
```

This maps:

```text
localhost:5433 -> production:127.0.0.1:5432
```

Internally this uses:

```bash
ssh -N -L 5433:127.0.0.1:5432 production
```

### `dap mount <host>:<remotePath> <localPath>`

Mounts a remote path into your local filesystem.

```bash
dap mount production:/srv/project ./mounts/project
```

Backends:

- `sshfs`, preferred when available.
- `rclone mount`, used as a fallback with the documented `--sftp-ssh` option so OpenSSH host aliases can still be used.

Force a backend:

```bash
dap mount production:/srv/project ./mounts/project --backend sshfs
```

Linux requires FUSE. macOS requires macFUSE.

### `dap unmount <localPath>`

Unmounts a local mount path.

```bash
dap unmount ./mounts/project
```

On Linux, `dap` uses `fusermount3`, `fusermount`, or `umount`. On macOS, it uses `umount`.

### `dap doctor`

Checks the local system for required tools and platform support.

```bash
dap doctor
```

It checks:

- `ssh`
- `sshfs`
- `rclone`
- `~/.ssh/config`
- FUSE on Linux
- macFUSE on macOS

## SSH Config Handling

`dap` uses the main SSH config:

```text
~/.ssh/config
```

It also scans files referenced by `Include` directives.

When adding new hosts, `dap` writes managed blocks directly to the main config. Managed blocks are wrapped with markers:

```sshconfig
# dap:begin production
Host production
  HostName 203.0.113.10
  User root
  IdentityFile ~/.ssh/id_ed25519
# dap:end production
```

Before changing the main config, `dap` creates a timestamped backup:

```text
~/.ssh/config.dap-backup-2026-05-30T12-30-00-000Z
```

For existing non-DAP host blocks, `dap edit` shows a diff before writing.

## Mounting Notes

`sshfs` is the simplest backend because it maps directly to OpenSSH host aliases:

```bash
sshfs production:/srv/project ./mounts/project
```

`rclone mount` is available as a fallback. DAP invokes it with the external SSH option so your SSH config alias remains the connection entry point:

```bash
rclone mount :sftp:/srv/project ./mounts/project --sftp-ssh "ssh production" --sftp-shell-type none
```

## Safety Model

`dap` follows these rules:

- OpenSSH remains authoritative.
- The main SSH config is backed up before writes.
- DAP-created blocks are clearly marked.
- Non-DAP host edits require diff confirmation by default.
- Remote `dap` exists only for the current `dap ssh` session.
- The remote session bridge uses a one-time token.
- The bridge exposes explicit DAP actions, not arbitrary local shell execution.

## Platform Support

`dap` targets:

- Linux
- macOS

Windows is not part of the initial scope.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository [license.md](./license.md) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH<br>
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.