Skip to content

Commit 74b376a

Browse files
kpiwkoclaude
andcommitted
docs: restructure README — sandbox section, OpenKaiden, experimental notes
- Remove redundant Quick start section; /ai-stack:bootstrap now covers starting services and registering MCPs - Clarify that LINCE and OpenShell are two separate experimental sandbox approaches: LINCE uses bwrap/nono + Zellij, OpenShell uses Podman + network policy enforcement - Note that LINCE is experimental and not yet integrated with OpenShell - Note that OpenShell Vertex AI support is a temporary workaround (NVIDIA/OpenShell#472) - Document the tooling split: /ai-stack:sandbox bootstraps LINCE, just sandbox-bootstrap bootstraps OpenShell - Add reference to OpenKaiden (https://openkaiden.ai/) as a related project for sandboxed AI agent execution Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
1 parent c0a6ce5 commit 74b376a

1 file changed

Lines changed: 41 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -11,25 +11,6 @@ Personal AI tooling stack: Podman Compose services for MCP servers, plus Claude
1111
| notebooklm-mcp | 17200 | NotebookLM MCP server |
1212
| workspace-mcp | 17150 | Google Workspace MCP (Gmail, Drive, Calendar, Docs, Sheets) |
1313

14-
## Quick start
15-
16-
**1. Copy and fill in secrets**
17-
18-
```bash
19-
cp env.example .env
20-
# Edit .env
21-
```
22-
23-
**2. Start services**
24-
25-
```bash
26-
just up
27-
# or selectively:
28-
podman compose up -d workspace-mcp notebooklm-mcp
29-
```
30-
31-
Container images are built by CI and published to `ghcr.io/kpiwko/` — no local build needed.
32-
3314
## Getting started with Claude Code
3415

3516
**1. Register the marketplace and install the ai-stack plugin:**
@@ -39,21 +20,21 @@ claude plugin marketplace add https://github.com/kpiwko/ai-stack.git --scope use
3920
claude plugin install ai-stack@ai-stack
4021
```
4122

42-
**2. Run bootstrap inside a Claude session to set up everything:**
23+
**2. Copy and fill in secrets, then run bootstrap inside a Claude session:**
4324

25+
```bash
26+
cp env.example .env
27+
# Edit .env — fill in GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET, etc.
4428
```
45-
/ai-stack:bootstrap
46-
```
47-
48-
This installs runtimes (uv, pnpm, rustup), LSP plugins (gopls, pyright, typescript-lsp, rust-analyzer),
49-
Claude plugins (superpowers, context7, atlassian, dev, track, quarterly), and registers MCP servers.
50-
51-
**3. Install or update the LINCE toolkit:**
5229

5330
```
54-
/ai-stack:sandbox
31+
/ai-stack:bootstrap
5532
```
5633

34+
Bootstrap starts the compose stack, installs runtimes (uv, pnpm, rustup), LSP plugins
35+
(gopls, pyright, typescript-lsp, rust-analyzer), Claude plugins (superpowers, context7,
36+
atlassian, dev, track, quarterly), and registers MCP servers with Claude Code.
37+
5738
**Updating plugins:**
5839

5940
```bash
@@ -120,20 +101,37 @@ On first run, make any Google Workspace tool call — the server returns a click
120101
URL. Complete the Google OAuth flow in your browser. Credentials are stored in
121102
`~/.config/workspace-mcp/` and reused on subsequent runs.
122103

123-
## OpenShell sandboxes
104+
## Agent sandboxes (experimental)
124105

125-
> **Note:** Running Claude Code in an OpenShell sandbox with Vertex AI currently requires
126-
> a manual credential wrapper (`just sandbox`). This is a workaround until OpenShell adds
127-
> native Vertex AI support (tracked in NVIDIA/OpenShell issue #472). Once that lands, the
128-
> workflow simplifies to `openshell sandbox create -- claude` with a configured provider.
106+
Running AI coding agents in isolated sandboxes is an active area. Two separate experimental
107+
approaches are available here; neither is production-ready. See also
108+
[OpenKaiden](https://openkaiden.ai/) — a desktop application that runs AI coding agents in
109+
isolated sandboxes with enterprise governance controls.
129110

130-
`openshell/policy.yaml` grants sandbox network access to all MCP services in this stack.
131-
Local services are reached via `host.containers.internal` (injected by the Podman driver).
132-
Private IP ranges are explicitly allowlisted to override the built-in SSRF guard.
111+
### LINCE (Zellij dashboard + bwrap/nono sandbox)
112+
113+
> **Experimental.** LINCE is a standalone toolkit and is not yet integrated with OpenShell.
114+
> It uses `bubblewrap` (Linux) or `nono` (macOS) for filesystem/process isolation and
115+
> Zellij for multi-agent session management.
116+
117+
Install or update via the plugin skill:
118+
119+
```
120+
/ai-stack:sandbox
121+
```
122+
123+
This installs `agent-sandbox`, the `lince-dashboard` Zellij plugin, and supporting scripts
124+
from the local `lince/` checkout.
133125

134-
See `openshell/bootstrap.md` for full setup instructions and known issues.
126+
### OpenShell (Podman + network policy enforcement)
135127

136-
### Quick workflow
128+
> **Experimental.** Running Claude Code in an OpenShell sandbox with Vertex AI currently
129+
> requires a manual credential wrapper. This is a workaround until OpenShell adds native
130+
> Vertex AI support (tracked in NVIDIA/OpenShell issue #472). Once that lands, the workflow
131+
> simplifies to `openshell sandbox create -- claude` with a configured provider.
132+
133+
Set up via `just` goals (not the plugin — OpenShell setup requires build tools and a running
134+
gateway, which the plugin cannot manage):
137135

138136
```bash
139137
# One-time setup (or after OpenShell git pull):
@@ -146,7 +144,11 @@ just sandbox
146144
just sandbox-teardown
147145
```
148146

149-
Gateway logs go to `/tmp/openshell-gateway.log`.
147+
`openshell/policy.yaml` grants sandbox network access to all MCP services in this stack.
148+
Local services are reached via `host.containers.internal` (injected by the Podman driver).
149+
150+
Gateway logs go to `/tmp/openshell-gateway.log`. See `openshell/bootstrap.md` for full
151+
setup instructions and known issues.
150152

151153
## macOS notes
152154

0 commit comments

Comments
 (0)