commit 36d14dc55db5ada1238a2d27232416ee1b997448 from: mtmn date: Sat Aug 29 16:08:40 2026 UTC less fluff in readme commit - 6dfb427fbfa52cbb037b31445b7e596c3f877075 commit + 36d14dc55db5ada1238a2d27232416ee1b997448 blob - f26d533171dc19fa023971ebbf7818c8298d912a blob + bc848fb3ebf7040cd3892c92409f8f4555a6add3 --- README.md +++ README.md @@ -1,106 +1,62 @@ # 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 @@ -1,4 +1,4 @@ -.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 @@ -13,115 +13,93 @@ pisol \- run commands in a Landrun sandbox .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.