README.md

# pisol

Working-directory Landrun isolation and configuration, with a terminal interface
written in Chez Scheme.

`pisol` combines command isolation with an editor for the local trusted
`.isolate` shell fragment. Outbound TCP is denied by default. The editor manages
extra writable/executable directories and the destination TCP ports commands
may connect to.

## Run

You need Bash, [Landrun](https://github.com/Zouuup/landrun), Chez Scheme 10.4 or
newer, and Ninja. Install `fzf` for fuzzy directory selection. Without it, the
editor uses direct path entry. Install `emacs` to run `ninja fmt`.

```sh
ninja tui
ninja test
```

After installation, open the editor in the working directory:

```sh
pisol
```

Run a command in that directory sandbox:

```sh
pisol -- your-command --with arguments
```

The command receives the caller environment, `PROMPT_ENV_INDICATOR=isolated`,
and `ISOLATE_ENV` set to the canonical working directory. Calling `pisol -- ...`
inside an existing pisol sandbox prints a warning and directly executes the
command rather than creating a nested Landlock domain.

## TUI commands

```text
a          fuzzy-find or enter a writable directory path
r          choose and remove a writable directory
p PORT     allow outbound TCP connections to a destination port
d          enter and remove an outbound TCP port
c          show global and local configuration file contents
s          save
sx         save and exit immediately (xs also works)
?          help
x          exit (discards any unsaved changes)
```

After selecting `a`, enter a base path such as `/home/miro`, or press Enter to
open the picker in your home directory. `fzf` then lists that path and its
immediate child directories only. Press Enter to drill down into a directory,
Alt+Enter or Ctrl-S to select it, or Escape to use the typed path directly.
The baseline writable tree cannot be added redundantly.

Set `NO_COLOR=1` to disable colour. `COLUMNS` and `LINES` are respected by the
terminal environment. Set `ISOLATE_EXTRA_CONFIG` to use a config path other
than `CURRENT_DIRECTORY/.isolate`.

## Configuration and trust

`.isolate` is sourced as trusted Bash by the launcher. A generated file looks
like this:

```bash
args+=(
  --rwx '/home/example/shared work'
  --connect-tcp 443
)
```

A global init file at `~/.config/pisol/init` is sourced before the local
`.isolate` when it exists. Put shared grants there; the project-specific file
builds on top of it. Override the path with `PISOL_INIT_CONFIG`.

A permissive example init based on the legacy `isolate` script is included at
`config/pisol/init`. Copy it to `~/.config/pisol/init` and edit to taste;
remove `--unrestricted-network` to keep outbound TCP denied by default.

The TUI also evaluates existing custom `.isolate` logic. It extracts the
resulting `--rwx` and `--connect-tcp` entries and preserves other resulting
Landrun arguments. Saving custom logic requires confirmation because the source
is replaced by a canonical argument array; comments and dynamic logic are not
retained. Default grants from the global init are shown but not edited in the
TUI; add or remove project-specific entries instead.

The minimal default policy grants the working tree read/write/execute access,
temporary storage write access, read access to system configuration/data, and
read/execute access to standard runtime and absolute `PATH` directories. It
also grants the standard null, zero, random, and controlling-terminal devices,
but does not grant unrestricted networking. A Wayland socket is added when
`WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` are set.

## Build and install

```sh
ninja build
ninja test
ninja fmt
ninja install
ninja copy-config
```

`ninja fmt` reindents the Scheme sources in place with `emacs` scheme-mode. Run
it after editing Scheme files; it is a no-op on already-formatted files.

`ninja install` defaults to `/usr/local` and asks for `sudo` only when needed.
Set `PREFIX`, `DESTDIR`, `BINDIR`, `LIBEXECDIR`, `MANDIR`, or `SCHEME` to
override the defaults. See `pisol(1)` after installation.