Skip to content

Commit c0a6ce5

Browse files
kpiwkoclaude
andcommitted
docs: update README for current services and sandbox workflow
- Fix services table: remove ai-beacon, gmail-mcp, gdrive-mcp, mcp-atlassian; add notebooklm-mcp and workspace-mcp - Replace old /ai-stack:install-* commands with consolidated /ai-stack:bootstrap; add /ai-stack:sandbox for LINCE - Remove outdated "External MCPs" table — atlassian and context7 are Claude Code plugins, not HTTP MCP endpoints - Expand Just recipes to include all sandbox goals - Rewrite OpenShell section: note the Vertex AI workaround (pending NVIDIA/OpenShell#472), add quick workflow with just goals Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
1 parent 6cd7ce9 commit c0a6ce5

1 file changed

Lines changed: 42 additions & 79 deletions

File tree

‎README.md‎

Lines changed: 42 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,10 @@ Personal AI tooling stack: Podman Compose services for MCP servers, plus Claude
66

77
| Service | Port | Description |
88
|---|---|---|
9-
| ai-beacon | 17090 | Session manager for multiple Claude sessions |
109
| devlake-local-mysql-mcp | 17301 | Read-only MCP proxy for local DevLake MySQL |
1110
| devlake-prod-mysql-mcp | 17300 | Read-only MCP proxy for remote Konflux RDS |
12-
| gmail-mcp | 17633 | Gmail MCP server (search, draft, attachments) |
13-
| mcp-atlassian | 17000 | Jira MCP server (streamable HTTP transport) |
14-
| gdrive-mcp | 17100 | Google Drive MCP server (streamable HTTP transport) |
11+
| notebooklm-mcp | 17200 | NotebookLM MCP server |
12+
| workspace-mcp | 17150 | Google Workspace MCP (Gmail, Drive, Calendar, Docs, Sheets) |
1513

1614
## Quick start
1715

@@ -27,7 +25,7 @@ cp env.example .env
2725
```bash
2826
just up
2927
# or selectively:
30-
podman compose up -d gmail-mcp mcp-atlassian
28+
podman compose up -d workspace-mcp notebooklm-mcp
3129
```
3230

3331
Container images are built by CI and published to `ghcr.io/kpiwko/` — no local build needed.
@@ -41,26 +39,21 @@ claude plugin marketplace add https://github.com/kpiwko/ai-stack.git --scope use
4139
claude plugin install ai-stack@ai-stack
4240
```
4341

44-
**2. Use it inside a Claude session to set up everything else:**
42+
**2. Run bootstrap inside a Claude session to set up everything:**
4543

4644
```
47-
/ai-stack:install-plugins ← install dev, track, quarterly plugins
48-
/ai-stack:install-skills ← install bare skills (template-slide-deck, n8n-skills)
49-
/ai-stack:install-mcps ← register MCP servers with Claude Code
45+
/ai-stack:bootstrap
5046
```
5147

52-
All three commands are interactive: they show what's available, what's already installed,
53-
and let you pick scope (user / project / local) before making any changes.
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.
5450

55-
**3. Install LSP servers and language runtimes:**
51+
**3. Install or update the LINCE toolkit:**
5652

5753
```
58-
/ai-stack:bootstrap
54+
/ai-stack:sandbox
5955
```
6056

61-
Sets up Go, Python (pyright), TypeScript, and Rust language servers for code intelligence
62-
in Claude Code.
63-
6457
**Updating plugins:**
6558

6659
```bash
@@ -70,39 +63,22 @@ claude plugin update ai-stack@ai-stack
7063

7164
Restart Claude Code after updating for changes to take effect.
7265

73-
**Updating plugins inside the agent-sandbox (LINCE):**
74-
75-
The sandbox uses an isolated Claude config at `~/.agent-sandbox/claude-config/`.
76-
Target it explicitly with `CLAUDE_CONFIG_DIR`:
77-
78-
```bash
79-
CLAUDE_CONFIG_DIR=~/.agent-sandbox/claude-config claude plugin marketplace update ai-stack
80-
CLAUDE_CONFIG_DIR=~/.agent-sandbox/claude-config claude plugin update ai-stack@ai-stack
81-
```
82-
8366
## Just recipes
8467

8568
```bash
86-
just up # podman compose up -d
87-
just down # podman compose down
88-
just status # podman compose ps
89-
```
90-
91-
## gmail-mcp
92-
93-
The container bind-mounts `~/.config/gmail-mcp-server/` so tokens from a previous run are
94-
reused automatically. On first run, authorize via browser:
95-
96-
```bash
97-
open http://localhost:17633/auth # complete Google Device Authorization
69+
just up # podman compose up -d
70+
just down # podman compose down
71+
just status # podman compose ps
72+
just sandbox-bootstrap # build OpenShell gateway + sideload image, start gateway, register provider
73+
just sandbox-bootstrap rebuild # force rebuild even if binaries/image already exist
74+
just sandbox # generate Vertex AI wrapper and launch Claude Code in a sandbox
75+
just sandbox-teardown # delete sandboxes, stop gateway, clean up staging files
9876
```
9977

100-
Then register with Claude Code via `/ai-stack:install-mcps`.
101-
10278
## devlake-local-mysql-mcp
10379

10480
Connects to a DevLake MySQL instance running on the host at port 3306. Start DevLake's
105-
MySQL service first, then register this MCP via `/ai-stack:install-mcps`. The command
81+
MySQL service first, then register this MCP via `/ai-stack:bootstrap`. The command
10682
reads `$DEVLAKE_MCP_SECRET_KEY` from the environment — make sure `.env` is sourced first.
10783

10884
**Optional: connect via shared Podman network instead of host port**
@@ -129,61 +105,48 @@ that network and reach MySQL by container name — no host port exposure needed.
129105
MYSQL_HOST: mysql # replace with DevLake's MySQL container name
130106
```
131107

132-
## mcp-atlassian (Jira)
133-
134-
Credentials come from `.env`: `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`. Start the
135-
service then register via `/ai-stack:install-mcps`.
108+
## notebooklm-mcp
136109

137-
## gdrive-mcp (Google Drive)
138-
139-
Authenticate on the host before starting the container — the server cannot open a browser
140-
inside the container:
110+
On first run (or when cookies expire), authenticate via the bundled VNC browser:
141111

142112
```bash
143-
npx @piotr-agier/google-drive-mcp auth
113+
open http://localhost:17201/vnc.html
114+
podman exec -it ai-stack-notebooklm-mcp-1 nlm login
144115
```
145116

146-
This writes `credentials.json` and `tokens.json` into `~/.config/google-drive-mcp/`.
147-
Then start the service and register via `/ai-stack:install-mcps`.
148-
149-
## OpenShell sandboxes
150-
151-
`openshell/policy.yaml` grants sandbox access to all services in this stack.
152-
Services are reached via `host.openshell.internal` (OpenShell injects this as an alias
153-
for the gateway host IP). Private IP ranges are explicitly allowlisted to override the
154-
built-in SSRF guard.
117+
## workspace-mcp
155118

156-
### Rootful Podman required
119+
On first run, make any Google Workspace tool call — the server returns a clickable OAuth
120+
URL. Complete the Google OAuth flow in your browser. Credentials are stored in
121+
`~/.config/workspace-mcp/` and reused on subsequent runs.
157122

158-
OpenShell's gateway runs k3s inside a container. k3s requires kernel interfaces
159-
(`/dev/kmsg`, OOM tuning, network namespaces) unavailable in rootless Podman.
123+
## OpenShell sandboxes
160124

161-
Switch once:
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.
162129

163-
```bash
164-
podman machine stop
165-
podman machine set --rootful
166-
podman machine start
167-
podman compose pull # re-pull images (rootful/rootless use separate stores)
168-
```
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.
169133

170-
### Gateway port
134+
See `openshell/bootstrap.md` for full setup instructions and known issues.
171135

172-
OpenShell's gateway defaults to port 8080, which conflicts with services here.
173-
Start it on a free port:
136+
### Quick workflow
174137

175138
```bash
176-
openshell gateway start --port 17711
177-
```
139+
# One-time setup (or after OpenShell git pull):
140+
just sandbox-bootstrap
178141
179-
### Launching a sandbox
142+
# Each session:
143+
just sandbox
180144
181-
```bash
182-
podman compose up -d gmail-mcp devlake-local-mysql-mcp
183-
openshell sandbox create --policy ./openshell/policy.yaml -- claude
145+
# Tear everything down:
146+
just sandbox-teardown
184147
```
185148

186-
From inside the sandbox, services are reachable at `host.openshell.internal:<port>`.
149+
Gateway logs go to `/tmp/openshell-gateway.log`.
187150

188151
## macOS notes
189152

0 commit comments

Comments
 (0)