# pisol
Run commands in a Landrun sandbox and manage each project's isolation settings.
The terminal interface is written in Chez Scheme.
`pisol` uses a trusted local `.isolate` Bash file. It denies outbound TCP by
default. Use the editor to add writable and executable directories, and allow
connections to specific TCP ports.
## Run
You need Bash, [Landrun](https://github.com/Zouuup/landrun), Chez Scheme 10.4
or later, and Make.
Install `fzf` to search for directories. Without it, enter a path directly.
```sh
make tui
make 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
```
Use `pisol -- COMMAND` when a command name conflicts with a pisol option.
The command receives your environment, `PROMPT_ENV_INDICATOR=isolated` and
`ISOLATE_ENV`, set to the resolved working directory. If you run `pisol COMMAND`
inside an existing pisol sandbox, it warns you and runs the command directly.
## Terminal interface 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
? help
x exit (discards any unsaved changes)
```
After you select `a`, enter a base path such as `/home/miro`. Press Enter to
start in your home directory. `fzf` shows the path and its immediate child
directories. Press Enter to open a directory. Press Alt+Enter to select the
directory under the cursor. Press Ctrl-S to save the current directory. Press
Escape to use the path you entered.
You cannot add the baseline writable tree again.
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 trusted Bash code. The launcher sources it. A generated file
looks like this:
```bash
args+=(
--rwx '/home/example/shared work'
--connect-tcp 443
)
```
A global init file at `~/.config/pisol/init` runs before the local `.isolate`
file. Put shared grants there. Project settings build on those grants. Set
`PISOL_INIT_CONFIG` to use a different global init file.
The source tree includes a permissive example init at `config/pisol/init`.
Copy it to `~/.config/pisol/init` and change it for your needs. Remove
`--unrestricted-network` to deny outbound TCP by default.
The editor evaluates existing custom `.isolate` code. It manages the resulting
`--rwx` and `--connect-tcp` values and keeps the other Landrun arguments.
Saving custom code needs confirmation. It replaces the code with a static
argument array, so it removes comments and dynamic logic. The editor shows
global grants but does not let you change them. Add or remove project grants
instead.
The default policy gives the working tree read, write and execute access. It
also gives write access to temporary storage. System configuration and shared
data are read-only. Standard runtime and absolute `PATH` directories are
readable and executable.
The policy allows the standard null, zero, random and terminal devices. It does
not allow unrestricted networking. It adds a Wayland socket when
`WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` are set.
## Build and install
```sh
make build
make test
make install
make copy-config
```
`make install` defaults to `/usr/local`; use `sudo make install` only when your
chosen destination requires it.
Set `PREFIX`, `DESTDIR`, `BINDIR`, `LIBEXECDIR`, `MANDIR`, or `SCHEME` to
override the defaults. See `pisol(1)` after installation.
