commit - 6dfb427fbfa52cbb037b31445b7e596c3f877075
commit + 36d14dc55db5ada1238a2d27232416ee1b997448
blob - f26d533171dc19fa023971ebbf7818c8298d912a
blob + bc848fb3ebf7040cd3892c92409f8f4555a6add3
--- README.md
+++ README.md
# pisol
-Run commands in a Landrun sandbox. Run `pisol` with no command to manage the
-current project's isolation settings.
+Run a command in a Landrun sandbox for the current directory.
-`pisol` reads trusted Bash from `.isolate` in the current directory. It denies
-outbound TCP by default.
+```sh
+pisol COMMAND [ARG...]
+pisol -- COMMAND [ARG...]
+```
+Run `pisol` with no arguments to edit `.isolate`.
+
## Requirements
-You need:
-
- Bash
- [Landrun](https://github.com/Zouuup/landrun)
- Chez Scheme 10.4 or later
- Make
-## Start
+## Build and use
-Build and run the editor:
-
```sh
+make build
make tui
+pisol COMMAND [ARG...]
```
-Run a command in the current project's sandbox:
+`make tui` opens the editor. Add writable directories and outbound TCP ports,
+then save with `x`.
-```sh
-pisol your-command --with arguments
-```
+The sandbox allows read, write and execute access to the current directory.
+It allows writable temporary storage and read access to system runtime files.
+Outbound TCP is denied unless configuration allows it.
-Use `pisol -- COMMAND` when the command name is also a pisol option.
-
-The command receives your environment and these variables:
-
-- `PROMPT_ENV_INDICATOR=isolated`
-- `ISOLATE_ENV`, set to the resolved project directory
-
-If `ISOLATE_ENV` is already set, pisol warns you and runs the command directly.
-It does not create a nested Landlock domain.
-
-## Use the editor
-
-The editor accepts these commands:
-
-```text
-a add a writable directory
-r remove a writable directory
-p PORT allow outbound TCP to PORT
-d remove an outbound TCP port
-c show configuration files
-? show help
-x save and exit
-```
-
-When you add a directory, the input starts at your home directory. Press Tab to
-complete a path. Press Tab twice to list matches. Press Enter to add the path.
-
-You cannot add the project's writable tree again.
-
## Configuration
-`.isolate` is trusted Bash code. Only use configuration files you trust.
+`.isolate` is trusted Bash. pisol loads it after the optional global init file.
-A generated file looks like this:
-
```bash
args+=(
- --rwx '/home/example/shared work'
+ --rwx "/path/to/shared"
--connect-tcp 443
)
```
-A global init file at `~/.config/pisol/init` runs before the local `.isolate`
-file. Use it for shared grants. Set `PISOL_INIT_CONFIG` to use another path.
+Set `ISOLATE_EXTRA_CONFIG` to use a different local file. Set
+`PISOL_INIT_CONFIG` to use a different global init file. The default global
+path is `~/.config/pisol/init`.
-The source tree includes an example init file 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.
+Saving creates a static argument list. It removes comments and dynamic shell
+code from the local file.
-pisol evaluates custom `.isolate` files and manages their `--rwx` and
-`--connect-tcp` arguments. Saving replaces custom code with a static argument
-list. This removes comments and dynamic logic.
+`NO_COLOR=1` disables editor colour. `ISOLATE_ENV` prevents nested sandboxes.
-The project tree is readable, writable and executable. Temporary storage is
-writable. System configuration, shared data and standard runtime paths are
-read-only. pisol grants the standard null, zero, random and terminal devices.
-It adds a Wayland socket when `WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` are set.
+## Install
-Set `NO_COLOR=1` to disable colour. Set `ISOLATE_EXTRA_CONFIG` to use a local
-configuration file other than `CURRENT_DIRECTORY/.isolate`.
-
-## Build and install
-
```sh
-make build
make test
make install
-make copy-config
```
-`make install` uses `/usr/local` by default. Use `sudo make install` only when
-your chosen destination needs it.
-
-Set `PREFIX`, `DESTDIR`, `BINDIR`, `LIBEXECDIR`, `MANDIR` or `SCHEME` to change
-the build or installation paths.
+`make install` uses `/usr/local`. Set `PREFIX`, `DESTDIR`, `BINDIR`,
+`LIBEXECDIR`, `MANDIR` or `SCHEME` to change build or install paths.
blob - ff730a838058e6ffc6f53adc6d606321ff25dad7
blob + f814c847ae23501bfe8be65f85a5784813de3d5b
--- doc/pisol.1
+++ doc/pisol.1
-.TH PISOL 1 "2026-08-28" "pisol" "User Commands"
+.TH PISOL 1 "2026-08-29" "pisol" "User Commands"
.SH NAME
pisol \- run commands in a Landrun sandbox
.SH SYNOPSIS
.RI [ ARG ...]
.SH DESCRIPTION
.B pisol
-opens a terminal editor for the current project's isolation settings. With a
-command, it runs that command in a Landrun sandbox for the current directory.
+opens an editor for the local
+.I .isolate
+file when run without a command. Otherwise, it runs the command in a Landrun
+sandbox for the current directory.
+.PP
Use
.B --
-before a command whose name conflicts with a pisol option.
+before a command name that starts with a hyphen.
+.SH SANDBOX
+pisol grants read, write and execute access to the current directory.
+Temporary storage is writable. System runtime files are readable. Outbound TCP
+is denied unless configuration allows a port.
.PP
-The current directory is the writable project tree. pisol reads its
-configuration from
-.I CURRENT_DIRECTORY/.isolate
-unless
-.B ISOLATE_EXTRA_CONFIG
-is set.
-.SH ISOLATION POLICY
-The project tree is readable, writable and executable. Temporary storage is
-writable. Standard runtime paths and absolute PATH directories are readable and
-executable. System configuration and shared data are read-only. The standard
-null, zero, random and controlling-terminal devices are writable.
-.PP
-Outbound TCP is denied by default. pisol grants only destination ports listed
-with
-.B --connect-tcp .
-It relaxes scoped IPC restrictions. It grants the current Wayland socket when
-its environment variables are available.
-.PP
-The command receives the caller environment, plus
+The command receives the caller environment. pisol also sets
.B PROMPT_ENV_INDICATOR=isolated
and
.B ISOLATE_ENV
-set to the resolved project directory. If
+to the resolved current directory. If
.B ISOLATE_ENV
-is already set, pisol warns and runs the command directly. It does not start a
-nested Landlock domain.
-.SH TERMINAL COMMANDS
+is set, pisol runs the command without another sandbox.
+.SH EDITOR COMMANDS
.TP
.B a
-Add a read, write and execute directory grant. The path starts at the home
-directory. Press Tab to complete a path. Press Tab twice to list matches.
+Add a writable directory.
.TP
.B r
Remove a writable directory by number.
.TP
.BI p " PORT"
-Allow outbound TCP to PORT. Valid ports are 1 to 65535.
+Allow outbound TCP to PORT.
.TP
.B d
Remove an outbound TCP port.
.TP
.B c
-Show the global init file and local configuration file. A missing file is
-labelled absent.
+Show the global and local configuration files.
.TP
.B ?
Show help.
.TP
.B x
-Save changes atomically with mode 0600, then exit.
+Save and exit.
.SH CONFIGURATION
.I .isolate
-is trusted Bash code. The launcher sources it. It normally changes the Bash
-array
-.IR args
-with an
-.B args+=(...)
-fragment.
+is trusted Bash. pisol loads the optional global init file before this local
+file. Both files add Landrun arguments to the Bash array
+.IR args .
.PP
-If
-.I ~/.config/pisol/init
-exists, the launcher sources it before the local
-.I .isolate .
-Use it for shared grants. Set
-.B PISOL_INIT_CONFIG
-to use another init file.
+For example:
.PP
-The source tree includes an example init file at
-.IR config/pisol/init .
-Copy it to
-.I ~/.config/pisol/init
-and change it for your needs. Remove
-.B --unrestricted-network
-to deny outbound TCP by default.
+.nf
+args+=(
+ --rwx "/path/to/shared"
+ --connect-tcp 443
+)
+.fi
.PP
-pisol evaluates an existing configuration. It manages the resulting
-.B --rwx
-and
-.B --connect-tcp
-arguments and keeps other arguments. Saving custom shell code replaces it with
-a static array. This removes comments and dynamic logic. The editor shows global
-init grants but does not let you change them.
-.SH ENVIRONMENT
-.TP
-.B ISOLATE_EXTRA_CONFIG
-Override the local configuration path.
-.TP
-.B PISOL_INIT_CONFIG
-Override the global init path. The default is
+The default global init path is
.IR ~/.config/pisol/init .
+Set
+.B PISOL_INIT_CONFIG
+to use another global file. Set
+.B ISOLATE_EXTRA_CONFIG
+to use another local file.
+.PP
+Saving writes a static local argument list. It removes comments and dynamic
+shell code from that file.
+.SH ENVIRONMENT
.TP
+.B ISOLATE_EXTRA_CONFIG
+Sets the local configuration path.
+.TP
+.B PISOL_INIT_CONFIG
+Sets the global init path.
+.TP
.B ISOLATE_ENV
-Marks an existing pisol sandbox and prevents nesting.
+Prevents nested sandboxes.
.TP
.B NO_COLOR
-Disable TUI colour when set.
+Disables editor colour.
.TP
.BR HOME , " PATH" , " TMPDIR"
-Supply runtime paths and grants.
+Provide runtime paths and sandbox grants.
.TP
.BR WAYLAND_DISPLAY , " XDG_RUNTIME_DIR"
-Identify an optional Wayland socket grant.
+Provide an optional Wayland socket grant.
.SH EXIT STATUS
-The editor returns zero on normal exit. It returns non-zero on load or save
-errors. In command mode, pisol returns the command's status. Usage errors return
-2. A missing Landrun executable returns 127.
+The editor returns zero after exit. Load and save errors return nonzero. In
+command mode, pisol returns the command status. Usage errors return 2. A
+missing Landrun executable returns 127.
