[Resource]: VIWO - safely run "dangerously-skip-permissions"

[hal-shin]

Display Name

viwo-cli

Category

Tooling

Sub-Category

General

Primary Link

https://github.com/OverseedAI/viwo

Secondary Link

No response

Author Name

Hal Shin

Author Link

https://github.com/hal-shin

License

MIT

Other License

No response

Description

Run Claude Code in a Docker container with git worktrees as volume mounts to enable safer usage of --dangerously-skip-permissions for frictionless one-shotting prompts. Allows users to spin up multiple instances of Claude Code in the background easily with reduced permission fatigue.

Validate Claims

1. Install viwo through install script
2. Run viwo auth to add your API token
3. Run viwo register to enlist your repository
4. Run viwo start and prompt That's it!

Additional Comments

No response

Recommendation Checklist

• [x] I have checked that this resource hasn't already been submitted
• [x] My resource provides genuine value to Claude Code users, and any risks are clearly stated
• [x] All provided links are working and publicly accessible
• [x] I am submitting only ONE resource in this issue
• [x] I understand that low-quality or duplicate submissions may be rejected

[github-actions[bot]]

🤖 Validation Results

✅ All validation checks passed!

Your submission is ready for review by a maintainer.

Validated Data:

{
  "display_name": "viwo-cli",
  "category": "Tooling",
  "subcategory": "General",
  "primary_link": "https://github.com/OverseedAI/viwo",
  "secondary_link": "",
  "author_name": "Hal Shin",
  "author_link": "https://github.com/hal-shin",
  "license": "MIT",
  "description": "Run Claude Code in a Docker container with git worktrees as volume mounts to enable safer usage of `--dangerously-skip-permissions` for frictionless one-shotting prompts. Allows users to spin up multiple instances of Claude Code in the background easily with reduced permission fatigue.",
  "active": "TRUE",
  "last_checked": "2025-11-28:23-26-03"
}

---

_{This comment is automatically updated when you edit the issue.}

[hesreallyhim]

thanks @hal-shin ! Looks very cool - could you help clarify a few things? The README doesn’t fully explain the security model, so I’m not sure I understand what VIWO is doing.

1. What exactly happens at runtime?

I see references to Docker, worktrees, and session management, but not a clear description of: • what processes the CLI runs • what directories it touches • what network calls it makes • where it stores data

2. What permissions does it actually need?

Running containers and worktrees are local operations, so I’m unclear why VIWO requires anything beyond Docker + filesystem access. If additional privileges are required, could you explain why?

3. Why does VIWO need my Anthropic API key?

It’s not clear whether the key: • stays entirely on my machine, • is sent anywhere externally, or • is used through any proxy service.

Given the sensitivity of LLM API keys, this needs to be explicit.

4. What does “registering” a repository do?

It isn’t obvious what changes VIWO makes to a repo or whether any repo information is transmitted off-machine.

⸻

In short: running Claude Code in a local Docker sandbox doesn’t obviously require giving a third party my API key or “enlisting” a repository, so I’d appreciate more detail to understand the architecture and trust boundaries.

Thanks!

/request-changes see comment in thread

[github-actions[bot]]

🔄 Changes Requested by @hesreallyhim

see comment in thread

Please edit your issue to address these points. The validation will run again automatically after you make changes.

[hal-shin]

hey @hesreallyhim, thanks for the response, here's the extra detail:

1. What exactly happens at runtime? • what processes the CLI runs

VIWO itself is inherently a short-lived process and relies on the Docker daemon for long-lived processes. The main command viwo start basically calls git worktree and then docker run then exits. Inside the Docker container, the command that is invoked is claude (Claude Code CLI) in print mode.

• what directories it touches

Only the directory you register, which will primarily be git repositories. VIWO will duplicate the git repositories through the git worktree command into the app data directory, and these worktrees then get volume mount onto Docker containers.

• what network calls it makes

Locally, only to the Docker API. The Claude Code instance inside the Docker container will have full access to WAN, but its network is limited by the one provided by Docker.

• where it stores data

The sqlite database lives in the app data directory, which depends on the OS. For Mac, it's under /Users/[username]/Library/Application Support/viwo

2. What permissions does it actually need?

The main point of VIWO is to run claude in headless mode to one-shot prompts. For that to happen, Claude needs unfettered permissions. Not sure if the question is insinuating that Claude would be the one calling VIWO, but the main flow is:

human -> VIWO -> git worktree/Docker -> Claude Code -> one-shot output

There is no human feedback to approve web calls or writing to file system (inside the Docker that is), so the Claude instance is given --dangerously-skip-permissions.

3. Why does VIWO need my Anthropic API key?

The Docker container bootstraps a clean installation of Claude Code. It does not have access to the host machine's environment, so it needs an API key to be able to run Claude Code. This API key is stored in the host machine's app data directory inside the sqlite database and is injected into the Docker container to run Claude Code. The API key is never stored off the user's computer.

[hesreallyhim]

@hal-shin thanks for the detailed information, i'll think it over. if the goal is: execute a single non-interactive prompt in a containerized worktree with maximum isolation, i still have to understand what problem you're solving that couldn't be solved with a docker environment variable or something much simpler. i think you're creating a special app directory with a database, credentials, and that's getting volume mounted, by why not just mount the worktree directory and use docker Secrets or something more lightweight? maybe there is a good reason, but i'm trying to figure it out. does it have access to my global .claude skills/hooks/subagents/etc? what's IN the database besides an API key?

[hal-shin]

Hey @hesreallyhim , thanks again for the response.

The user is able to run many VIWO instances, either in parallel or in sequence. So the database contains metadata about each session that the user ran, and this includes stuff like session name, created date, the original prompt, path to the created worktree, etc. It'll also capture the output of the run, but that's not implemented yet. This gets captured in the user's app data, but this does not get mounted to a Docker container. The database also captures the local repositories that the user registers.

What does get mounted, as you suggested, are the worktrees. Nothing else is mounted, so your personal .claude context files are not included and not visible by the Claude running inside the Docker container.

I'm not entirely sure what you mean by using something simpler like Docker secrets or environment variables to achieve this--my understanding is that Docker secrets are generally meant for their Swarm service and we strictly use docker run or its API equivalent so we inject the API key directly in as a runtime environment variable. The API key is never embedded in the Docker image.

[hesreallyhim]

@hal-shin

Nothing else is mounted, so your personal .claude context files are not included and not visible by the Claude running inside the Docker container.

So does that mean I can't access my my usual hooks, sub-agents, etc.? I'm gonna approve this because it seems like you've put some thought into the security design and in some cases it's actually nice to spin up workers without any context bloat that may have accumulated in your project folders, but FWIW I would probably want some way to maybe copy those files over into the new worktree as an option, for users who do rely on their own preferred configuration, which it seems like is not possible right now. Thanks for bearing with me on the questions.

/approve

[github-actions[bot]]

✅ Resource Approved!

🎉 A pull request has been created with your resource: https://github.com/hesreallyhim/awesome-claude-code/pull/352

The PR will be merged shortly, and you'll be notified when your resource is live.

Thank you for contributing to Awesome Claude Code!

[hal-shin]

@hal-shin

Nothing else is mounted, so your personal .claude context files are not included and not visible by the Claude running inside the Docker container.

So does that mean I can't access my my usual hooks, sub-agents, etc.? I'm gonna approve this because it seems like you've put some thought into the security design and in some cases it's actually nice to spin up workers without any context bloat that may have accumulated in your project folders, but FWIW I would probably want some way to maybe copy those files over into the new worktree as an option, for users who do rely on their own preferred configuration, which it seems like is not possible right now. Thanks for bearing with me on the questions.

/approve

@hesreallyhim Thanks for the review! Hooking in your personal configurations is definitely useful and something we'll want to add in the future. I find viwo-cli already useful without all the bells and whistles, so wanted to get it out there quickly :)