What is Shell Gate?
Shell Gate is Alius’s human-in-the-loop security layer. It performs risk analysis and scope checking on all shell and file operations requested by the Agent, ensuring you remain in control during sensitive operations.
Shell Gate is not a simple “allow/deny” switch. It analyzes the command string, arguments, paths, redirection targets, current working directory, origin, workspace root, and authorization policy to make fine-grained decisions.
How It Works
When the Agent wants to execute an operation (Shell command, file write, etc.), Shell Gate:
- Intercepts the operation
- Analyzes command risk and scope
- Decides: Allow / Deny / ApprovalRequired
- Records the decision for auditing
Shell Gate Decisions
| Decision | Plan Mode Behavior | Bypass Mode Behavior |
|---|---|---|
| Allow | Execute directly | Execute directly |
| Deny | Reject execution | Reject execution |
| ApprovalRequired | Pause and wait for user confirmation | Execute directly and return result |
In Bypass mode, Shell Gate’s
ApprovalRequireddecisions are executed directly rather than waiting for confirmation. Denied operations still do not execute.
Git Command Risk Classification
Shell Gate classifies Git subcommands:
| Risk Level | Commands | Description |
|---|---|---|
| Low risk | git status, git log, git diff, git show, git branch | Read-only operations |
| Medium risk | git clone, git fetch, git pull, git submodule | Write to workspace and/or use network |
| Medium risk | git push, git checkout, git switch, git merge, git rebase, git restore, git add, git commit | Modification operations |
| High risk | git clean, git reset --hard | May cause data loss |
Workspace Boundary Checks
All file operations go through resolve_within_workspace(path, workspace, must_exist) for boundary checking:
- Blocks absolute path access (e.g.,
/etc/passwd) - Blocks parent directory traversal (e.g.,
../secret) - Blocks symlink escapes
- Checks paths in option values (e.g.,
--output=/tmp/file) - Checks redirection targets (e.g.,
> /tmp/file,2>/tmp/error) - Ignores URL-like values (not treated as paths)
Built-in Tool Permissions
| Tool | Permission Level | Description |
|---|---|---|
shell | Execute | Execute shell commands, 120-second timeout, output truncated to 20,000 characters |
read_file | Read | Read files, workspace boundary check |
write_file | Write | Write files, requires confirmation in Plan mode |
list_dir | Read | List directory contents |
edit_file | Write | Replace file content, requires confirmation in Plan mode |
Shell Tool
The complete execution flow for the Shell tool:
- Parse arguments
- Resolve cwd within workspace scope
- Call
shell_gate::authorizefor risk analysis Deny→ reject executionAllow→ execute commandApprovalRequired→ Plan mode pauses for confirmation, Bypass mode executes directly- Output format:
[exit:N]\n<stdout>\n<stderr>, truncated to 20,000 characters
Configuring Permissions
Configure in .alius/config/permissions.toml:
[shell]
default = "ask"
auto_approve = ["ls", "cat", "git status", "git log", "git diff"]
deny = ["rm -rf /", "format", "mkfs"]
[file_write]
default = "ask"
deny_patterns = [".env", "credentials", "*.key"]
[network]
default = "ask"Best Practices
- Start strict — Use
askas the default for all operation types - Add auto-approvals gradually — Only for commands you run frequently and trust
- Review Traces — Regularly check audit logs
- Don’t auto-approve writes — Keep file modifications requiring approval
- Be mindful of Bypass mode — In Bypass mode, ApprovalRequired executes directly, so ensure you trust the current task
Auditing
All tool calls produce ToolCallStarted and ToolCallCompleted events, recorded in the Session’s Trace. Shell calls appear in the session area as shell: <command>, and completion blocks include a brief output summary.