Personal AI tooling stack: Podman Compose services for MCP servers, plus Claude Code plugins for productivity workflows.

1. Register the marketplace and install the ai-stack plugin:

claude plugin marketplace add https://github.com/kpiwko/ai-stack.git --scope user
claude plugin install ai-stack@ai-stack

2. Run bootstrap inside a Claude session:

/ai-stack:bootstrap

Bootstrap creates .env from the template (if missing), installs runtimes (uv, pnpm, rustup), LSP plugins (gopls, pyright, typescript-lsp, rust-analyzer), Claude plugins (superpowers, context7, atlassian, dev, track, quarterly), and registers MCP servers with Claude Code.

If .env has placeholder values, bootstrap will list them. Edit .env with your secrets (Google OAuth credentials, database passwords, etc.) and run /ai-stack:up to start the services.

Updating plugins:

claude plugin marketplace update ai-stack
claude plugin update ai-stack@ai-stack

Restart Claude Code after updating for changes to take effect.

just lince-bootstrap             # install or update LINCE toolkit (agent-sandbox, lince-dashboard)
just lince                       # launch the LINCE dashboard

just openshell-bootstrap         # build OpenShell gateway + sideload image, start gateway, register provider
just openshell-bootstrap force       # force rebuild even if binaries/image already exist
just openshell                   # generate Vertex AI wrapper and launch Claude Code in a sandbox
just openshell-teardown          # delete sandboxes, stop gateway, clean up staging files

Stack lifecycle (up, down, status) is handled by the /ai-stack:up and /ai-stack:down Claude skills.

Connects to a DevLake MySQL instance running on the host at port 3306. Start DevLake's MySQL service first, then register this MCP via /ai-stack:project-init. The command reads $DEVLAKE_LOCAL_MCP_SECRET_KEY from the environment — make sure .env is sourced first.

Optional: connect via shared Podman network instead of host port

If DevLake runs in Podman Compose with a named network, you can attach this service to that network and reach MySQL by container name — no host port exposure needed.

1. Find DevLake's network name: podman network ls

2. Declare it as external in compose.yaml:

   networks:
     ai-stack:
       driver: bridge
     devprod:        # replace with DevLake's actual network name
       external: true

3. Add the network to the service and update MYSQL_HOST to the MySQL container name:

   devlake-mysql-local:
     networks: [ai-stack, devprod]
     environment:
       MYSQL_HOST: mysql   # replace with DevLake's MySQL container name

On first run (or when cookies expire), authenticate via the bundled VNC browser:

open http://localhost:17201/vnc.html
podman exec -it ai-stack-notebooklm-mcp-1 nlm login

On first run, make any Google Workspace tool call — the server returns a clickable OAuth URL. Complete the Google OAuth flow in your browser. Credentials are stored in ~/.config/workspace-mcp/ and reused on subsequent runs.

Running AI coding agents in isolated sandboxes is an active area. Two separate experimental approaches are available here; neither is production-ready. See also OpenKaiden — a desktop application that runs AI coding agents in isolated sandboxes with enterprise governance controls.

Experimental. LINCE is a standalone toolkit and is not yet integrated with OpenShell. It uses bubblewrap (Linux) or nono (macOS) for filesystem/process isolation and Zellij for multi-agent session management.

Install or update via just:

just lince-bootstrap

This runs the interactive quickstart installer from the local lince/ checkout, installing agent-sandbox, the lince-dashboard Zellij plugin, and supporting scripts. Launch the dashboard with just lince.

Experimental. Running Claude Code in an OpenShell sandbox with Vertex AI currently requires a manual credential wrapper. This is a workaround until OpenShell adds native Vertex AI support (tracked in NVIDIA/OpenShell issue #472). Once that lands, the workflow simplifies to openshell sandbox create -- claude with a configured provider.

Set up via just goals (not the plugin — OpenShell setup requires build tools and a running gateway, which the plugin cannot manage):

# One-time setup (or after OpenShell git pull):
just openshell-bootstrap

# Each session:
just openshell

# Tear everything down:
just openshell-teardown

openshell/policy.yaml grants sandbox network access to all MCP services in this stack. Local services are reached via host.containers.internal (injected by the Podman driver).

Gateway logs go to /tmp/openshell-gateway.log. See openshell/bootstrap.md for full setup instructions and known issues.

This repo includes an AgentReady assessment that scores how well the codebase supports AI coding agents. Reports live in .agentready/.

To regenerate:

mkdir -p .agentready
podman run --rm \
  -v $(pwd):/repo:ro \
  -v $(pwd)/.agentready:/reports \
  ghcr.io/ambient-code/agentready:latest assess /repo --output-dir /reports

The latest report is at .agentready/report-latest.md (or .html for the full version).

• Named volumes are managed inside the Podman VM — data persists across restarts.
• host.containers.internal resolves to the macOS host from inside containers.
• network_mode: host is not supported; all services use bridge networking.

MIT — see LICENSE.