nhcarrigan/hikari-desktop
9
0
Fork 0
generated from nhcarrigan/template
Code Issues 9 Pull Requests 36 Actions Releases 22 Activity

feat: sandbox mode for isolated Claude Code execution #182

New Issue
Open
opened 2026-03-06 09:28:25 -08:00 by hikari · 0 comments
hikari commented 2026-03-06 09:28:25 -08:00
Owner
Copy Link
Copy Source

Overview

Inspired by ralph-tui's sandbox execution mode, this adds a Sandbox Mode that runs Claude Code in an isolated environment, preventing it from making unintended changes to the host system during autonomous or task-loop sessions.

User Story

As a developer using the automated task loop, I want Claude Code to run in a sandboxed environment so that autonomous tasks cannot accidentally modify system files, install packages globally, or make destructive changes outside the project directory.

Implementation Details

Linux: bwrap (bubblewrap)

On Linux, use bwrap to create a lightweight container:

bwrap \
  --bind /home/user/project /home/user/project \
  --bind /usr /usr \
  --ro-bind /etc /etc \
  --proc /proc \
  --dev /dev \
  --unshare-net \
  -- claude --output-format stream-json ...

Key restrictions:

  • Bind-mount only the project directory as read-write
  • Make the rest of the filesystem read-only
  • Optionally restrict network access (--unshare-net) for offline tasks
  • Block writes outside the project root

macOS: sandbox-exec

On macOS, use the built-in sandbox-exec with a profile that restricts file writes to the project directory.

Windows

Sandbox support on Windows is more complex; defer to a future issue. On Windows, sandbox mode should show an "unsupported" message rather than failing silently.

Configuration Options

Add to Config Sidebar under a new "Security" section:

  • Enable Sandbox Mode toggle (off by default)
  • Allow Network Access toggle (only visible when sandbox is enabled)
  • Additional Allowed Paths list (allow read-write access to specific paths beyond the project root, e.g. ~/.config)

Behaviour

  • When sandbox mode is enabled, all Claude Code processes are launched via bwrap/sandbox-exec
  • A sandbox indicator (🔒) appears in the status bar when active
  • If bwrap is not installed, show a friendly error with install instructions
  • Sandbox mode is especially recommended when using the Task Loop

Acceptance Criteria

  • Sandbox mode available as a settings toggle
  • On Linux, Claude Code runs via bwrap when enabled
  • On macOS, Claude Code runs via sandbox-exec when enabled
  • On Windows, a clear "not supported" message is shown
  • Status bar indicator shows sandbox is active
  • Network restriction can be toggled independently
  • Graceful error if bwrap/sandbox-exec is not installed
  • Tests written for command-building logic (E2E integration test pattern)

✨ This issue was created with help from Hikari~ 🌸

## Overview Inspired by [ralph-tui](https://github.com/subsy/ralph-tui)'s sandbox execution mode, this adds a **Sandbox Mode** that runs Claude Code in an isolated environment, preventing it from making unintended changes to the host system during autonomous or task-loop sessions. ## User Story As a developer using the automated task loop, I want Claude Code to run in a sandboxed environment so that autonomous tasks cannot accidentally modify system files, install packages globally, or make destructive changes outside the project directory. ## Implementation Details ### Linux: `bwrap` (bubblewrap) On Linux, use [`bwrap`](https://github.com/containers/bubblewrap) to create a lightweight container: ```bash bwrap \ --bind /home/user/project /home/user/project \ --bind /usr /usr \ --ro-bind /etc /etc \ --proc /proc \ --dev /dev \ --unshare-net \ -- claude --output-format stream-json ... ``` Key restrictions: - Bind-mount only the project directory as read-write - Make the rest of the filesystem read-only - Optionally restrict network access (`--unshare-net`) for offline tasks - Block writes outside the project root ### macOS: `sandbox-exec` On macOS, use the built-in `sandbox-exec` with a profile that restricts file writes to the project directory. ### Windows Sandbox support on Windows is more complex; defer to a future issue. On Windows, sandbox mode should show an "unsupported" message rather than failing silently. ### Configuration Options Add to **Config Sidebar** under a new "Security" section: - **Enable Sandbox Mode** toggle (off by default) - **Allow Network Access** toggle (only visible when sandbox is enabled) - **Additional Allowed Paths** list (allow read-write access to specific paths beyond the project root, e.g. `~/.config`) ### Behaviour - When sandbox mode is enabled, all Claude Code processes are launched via `bwrap`/`sandbox-exec` - A **sandbox indicator** (🔒) appears in the status bar when active - If `bwrap` is not installed, show a friendly error with install instructions - Sandbox mode is especially recommended when using the Task Loop ## Acceptance Criteria - [ ] Sandbox mode available as a settings toggle - [ ] On Linux, Claude Code runs via `bwrap` when enabled - [ ] On macOS, Claude Code runs via `sandbox-exec` when enabled - [ ] On Windows, a clear "not supported" message is shown - [ ] Status bar indicator shows sandbox is active - [ ] Network restriction can be toggled independently - [ ] Graceful error if `bwrap`/`sandbox-exec` is not installed - [ ] Tests written for command-building logic (E2E integration test pattern) ✨ This issue was created with help from Hikari~ 🌸
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
aspect
code
Concerns the software code in the repository
aspect
dx
Concerns developers' experience with the codebase
aspect
interface
Concerns end-users' experience with the software
aspect
text
Concerns the documentation material in the repository
contribute
good first issue
A great opportunity for a team member to learn a new codebase
contribute
help wanted
Open for anyone on our team to grab.
contribute
staff only
Restricted to our executive leadership.
goal
addition
Addition of new feature
goal
fix
Bug fix
goal
improvement
Improvement to an existing feature
points
1
Very simple issue requiring minimal effort and complexity.
points
13
Extremely complex issue representing major undertakings. Should be broken down into smaller pieces.
points
2
Simple issue that requires a bit more thought or investigation.
points
3
Moderate complexity issue requiring more substantial work.
points
5
Complex issue requiring significant effort and expertise.
points
8
Very complex issue requiring extensive work and deep expertise.
priority
critical
1
Must be fixed ASAP
priority
high
2
Stalls work on the project or its dependents
priority
low
4
Low priority and doesn't need to be rushed
priority
medium
3
Not blocking but should be fixed soon
priority
none
5
No priority, should only be performed when a developer is available
status
awaiting triage
Has not been triaged & therefore, not ready for work
status
blocked
Blocked and therefore not ready for work
status
discarded
Will not be worked on
status
discontinued
Not suitable for work as repo is in maintenance
status
label work required
Needs proper labelling before it can be worked on
status
ready for dev
Ready for work
status
ticket work required
Needs more details before it can be worked on
talk
discussion
Open for discussions and feedback
talk
question
Can be resolved with an answer
time
1 day
Approximately one full day of development work.
time
1-2 weeks
One to two weeks of focused development effort.
time
2-3 days
Two to three days of development effort.
time
4-5 days
Approximately one week of development work.
time
<1 day
Less than one day of focused work. Quick fixes or simple tasks.
time
>2 weeks
More than two weeks of development work. Must be broken down into smaller pieces.
No Label
Milestone
No items
No Milestone
Assignees
Clear assignees
gurkirat hanna (Hanna Rose) hikari (Hikari) minori (Minori) naomi (Naomi Carrigan) rain teklu tim
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: nhcarrigan/hikari-desktop#182
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?