2026-05-03-allow-flag-cli-design.md

CLI –allow Flag Support for jail.sh and vibe.sh

Summary

Add --allow <dir> flag support to jail.sh and vibe.sh scripts to enable users to whitelist additional directories with read/write access in the firejail sandbox.

Current Behavior

• jail.sh sandboxes a command using firejail with a fixed set of whitelisted paths
• vibe.sh is a convenience wrapper that launches opencode through jail.sh
• Users cannot add custom directories to the sandbox whitelist

Proposed Behavior

jail.sh

jail [--allow <dir>]... <command> [args...]

Examples: - jail opencode - Run opencode with default whitelist - jail --allow /tmp opencode - Add /tmp to whitelist - jail --allow /data --allow /home/projects bash - Add multiple directories, run bash - jail --allow /mnt opencode -s token123 - Combine with command args

vibe.sh

vibe [--allow <dir>]... [<session_token>]

Examples: - vibe - Run opencode with default whitelist - vibe --allow /tmp - Add /tmp to whitelist - vibe --allow /data --allow /projects token123 - Multiple dirs + session token

Design Decisions

1. One directory per flag: Each --allow flag takes exactly one directory argument
2. Flags before positional args: All --allow flags must come before the command (jail) or token (vibe)
3. No read-only option: All allowed directories get read/write access
4. getopts parsing: Use bash’s getopts for clean, POSIX-compliant argument parsing

Technical Details

jail.sh Changes

• Parse --allow flags using getopts loop before processing command
• Collect directories into an array
• For each directory, add --whitelist=<dir> and --read-write=<dir> to FIREJAIL_ARGS
• Pass remaining arguments unchanged to firejail

vibe.sh Changes

• Parse --allow flags using getopts loop before handling session token
• Collect directories and pass them to jail.sh using --allow <dir> syntax
• Maintain existing token handling logic (-s <token> or positional)

Edge Cases

• Duplicate directories: Firejail handles gracefully (no error)
• Non-existent directories: Firejail will error with appropriate message
• Directories with spaces: Properly quoted via array handling
• No –allow flags: Backward compatible with existing behavior
• No arguments after –allow flags: Script should error with usage message

Success Criteria

• [ ] jail --allow /tmp opencode works and /tmp is writable in sandbox
• [ ] jail --allow /foo --allow /bar bash allows access to both directories
• [ ] vibe --allow /tmp passes through to jail correctly
• [ ] vibe --allow /data token123 works with session token
• [ ] Scripts remain backward compatible (no –allow flags)