Skip to content

Commit 23990b3

Browse files
authored
feat: first-run UX with built-in agent profiles (#10)
* feat: Add first-run UX with built-in agent profiles When a known agent (claude, opencode, etc.) is run without a template, prompt the user to apply recommended filesystem defaults. Each agent is a self-contained file under internal/profiles/agents/ that self-registers via init(), so adding a new agent requires zero changes elsewhere. * feat: add toolchain profiles and trim AdHocCommands to basic unix utilities Move toolchain commands (npm, uv, cargo, docker, etc.) out of the ad-hoc command set into their own profiles under internal/profiles/toolchains/. Each toolchain is a self-contained file with filesystem paths from the agent-safehouse analysis. Toolchain profiles are not merged with BaseProfile() since they only need their own config/cache directories. * feat: improve first-run UX, add --template composability, update README First-run prompt redesign: - Explain that the command is being sandboxed and a profile is available - Show full allow/deny paths with ~/ prefixes for clarity - Add [e] Edit first option with $EDITOR and re-validate loop - Use [s] Skip / [n] Don't ask again instead of [n] / [never] - Add (recommended) and (restrictive) hints on options - ANSI colors when output is a terminal, respects NO_COLOR Template composability: - --template now accepts comma-separated names (e.g. --template claude,python) - Each name resolves: saved template on disk > built-in profile - templates list shows combo usage example README: add Agent profiles section with first-run and --template examples. * docs: fix README prompt example to match current UX Update paths to show ~/ prefix and use current option keys ([s] Skip, [n] Don't ask again, (recommended) hint). * feat: add --auto-profile flag for non-interactive profile selection When set, silently applies the built-in profile (or saved template) for known agents without prompting. Useful for CI/scripts where there is no terminal. In non-interactive mode, a hint about --auto-profile is now shown when a built-in profile is available but not applied. * refactor: rename --template to --profile, templates subcommand to profiles Unify terminology: everything is now "profiles" in the CLI and user-facing messages. The old --template flag and "templates" subcommand are kept as hidden aliases for backwards compatibility. * fix: resolve lint errors (errcheck, gosec, gofumpt, unused) * feat: add macOS-specific paths to built-in profiles Profiles previously only included XDG/Linux paths. On macOS, agents and toolchains store config, cache, and state under ~/Library/ and /Library/ which were missing entirely. Add runtime.GOOS == "darwin" checks to conditionally include: - Base: keychain paths, user preferences - Agents: Claude Desktop config, Codex plists, Cursor/Cline/Kilo VS Code globalStorage, Goose/Gemini Library paths, Pi metadata - Toolchains: Playwright/Cypress caches (node), JVM paths (java), system Ruby, OrbStack/Colima/Rancher Desktop (containers) * fix: use cross-platform terminal detection instead of Linux-only TCGETS
1 parent 3925d67 commit 23990b3

37 files changed

+1869
-97
lines changed

CLAUDE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Greywall
22

3-
Deny-by-default command sandbox. Wraps commands with restricted filesystem access (current directory only by default) and transparent network redirection through [greyproxy](https://github.com/GreyhavenHQ/greyproxy). Supports `--learning` mode to trace filesystem access and auto-generate config templates. Linux only (bubblewrap + seccomp/Landlock/eBPF); macOS support coming.
3+
Deny-by-default command sandbox. Wraps commands with restricted filesystem access (current directory only by default) and transparent network redirection through [greyproxy](https://github.com/GreyhavenHQ/greyproxy). Supports `--learning` mode to trace filesystem access and auto-generate config templates. Linux (bubblewrap + seccomp/Landlock/eBPF) and macOS (sandbox-exec Seatbelt profiles).
44

55
## Build & Run
66

README.md

Lines changed: 42 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Greywall
22

3-
Greywall wraps commands in a deny-by-default sandbox. Filesystem access is restricted to the current directory by default. Use `--learning` to trace what else a command needs and auto-generate a config template. All network traffic is transparently redirected through [greyproxy](https://github.com/GreyhavenHQ/greyproxy), a deny-by-default transparent proxy with a live allow/deny dashboard. Run `greywall setup` to install greyproxy automatically.
3+
Greywall wraps commands in a deny-by-default sandbox. Filesystem access is restricted to the current directory by default. Use `--learning` to trace what else a command needs and auto-generate a config profile. All network traffic is transparently redirected through [greyproxy](https://github.com/GreyhavenHQ/greyproxy), a deny-by-default transparent proxy with a live allow/deny dashboard. Run `greywall setup` to install greyproxy automatically.
44

55
*Supports Linux and macOS. See [platform support](docs/platform-support.md) for details.*
66

@@ -13,7 +13,7 @@ greywall check
1313
# Sandbox a command (network + filesystem denied by default)
1414
greywall -- curl https://example.com
1515

16-
# Learn what filesystem access a command needs, then auto-generate a template
16+
# Learn what filesystem access a command needs, then auto-generate a profile
1717
greywall --learning -- opencode
1818

1919
# Block dangerous commands
@@ -99,21 +99,55 @@ greywall check
9999
greywall setup
100100
```
101101

102+
### Agent profiles
103+
104+
Greywall ships with built-in profiles for popular AI coding agents (Claude, Codex, Cursor, Aider, Goose, Gemini, OpenCode, Amp, Cline, Copilot, Kilo, Auggie, Droid) and toolchains (Node, Python, Go, Rust, Java, Ruby, Docker).
105+
106+
On first run, greywall shows what the profile allows and lets you apply, edit, or skip:
107+
108+
```bash
109+
$ greywall -- claude
110+
111+
[greywall] Running claude in a sandbox.
112+
A built-in profile is available. Without it, only the current directory is accessible.
113+
114+
Allow read: ~/.claude ~/.claude.json ~/.config/claude ~/.local/share/claude ~/.gitconfig ... + working dir
115+
Allow write: ~/.claude ~/.claude.json ~/.cache/claude ~/.config/claude ... + working dir
116+
Deny read: ~/.ssh/id_* ~/.gnupg/** .env .env.*
117+
Deny write: ~/.bashrc ~/.zshrc ~/.ssh ~/.gnupg
118+
119+
[Y] Use profile (recommended) [e] Edit first [s] Skip (restrictive) [n] Don't ask again
120+
>
121+
```
122+
123+
Combine agent and toolchain profiles with `--profile`:
124+
125+
```bash
126+
# Agent + Python toolchain (allows access to ~/.cache/uv, ~/.local/pipx, etc.)
127+
greywall --profile claude,python -- claude
128+
129+
# Agent + multiple toolchains
130+
greywall --profile opencode,node,go -- opencode
131+
132+
# List all available and saved profiles
133+
greywall profiles list
134+
```
135+
102136
### Learning mode
103137
104-
Greywall can trace a command's filesystem access and generate a config template automatically:
138+
Greywall can trace a command's filesystem access and generate a config profile automatically:
105139

106140
```bash
107141
# Run in learning mode - traces file access via strace
108142
greywall --learning -- opencode
109143
110-
# List generated templates
111-
greywall templates list
144+
# List generated profiles
145+
greywall profiles list
112146
113-
# Show a template's content
114-
greywall templates show opencode
147+
# Show a profile's content
148+
greywall profiles show opencode
115149
116-
# Next run auto-loads the learned template
150+
# Next run auto-loads the learned profile
117151
greywall -- opencode
118152
```
119153

0 commit comments

Comments
 (0)