@greppleai/grip 0.0.1 → 0.1.3

package/docs/daemon.md

@@ -2,12 +2,12 @@
 
 `grip --daemon` starts Grip as a remote workspace runtime. A normal local Grip process remains the orchestrator: it owns provider credentials, model calls, prompts, sessions, compaction, extensions, subagents, RPC, and UI. The daemon owns one configured workspace and executes canonical workspace tools, primitive project-resource operations, streamed file transfers, optional process execution, and optional colocated LSP.
 
-Grip integrates the daemon into `@greppleai/grip`; start it with `grip --daemon`. Verify package availability before installing from a registry; a local packaged build can be used instead.
+Grip includes the daemon in the single-file executable; install a published, checksummed binary using [Quickstart](quickstart.md#install) or use a locally built executable. The daemon needs no npm installation on its host.
 
 ## Start a daemon
 
 ```bash
-npm install -g --ignore-scripts @greppleai/grip
+# Install the verified Grip binary first (see Quickstart).
 GRIP_DAEMON_TOKEN='long-random-token' \
 grip --daemon --daemon-cwd /workspace --daemon-host 127.0.0.1 --daemon-port 8787
 ```
@@ -31,12 +31,15 @@ Use `GRIP_REMOTE_TOKEN` on the client. Do not put tokens in query strings or URL
 
 ## Topology and trust boundary
 
-One daemon process serves one workspace root and one trust domain. The daemon is an authenticated remote-code-execution service: anyone with the bearer token can use every advertised daemon capability.
+In ordinary v1 mode, each daemon connection exposes a single workspace root; all clients of a daemon still share its OS-user trust domain. The daemon is an authenticated remote-code-execution service: anyone with the bearer token can use every advertised daemon capability. The separately negotiated v2 shared-Lima mode binds a workspace root per channel, but does **not** provide hostile-client isolation.
 
 Application-layer confinement prevents protocol paths and symlinks from escaping the configured workspace and optional temporary root for file tools, resource reads, file transfers, temporary outputs, subprocess working directories, and LSP paths. `GRIP_DAEMON_TEMP_ROOT` is opt-in and should point only to disposable storage inside an OS sandbox; it is unset by default. This is not an operating-system sandbox. If process execution is enabled, commands can access anything the daemon OS user can access. Run the daemon as a dedicated unprivileged user, in a container, VM, or equivalent sandbox for hostile repositories.
 
 The daemon refuses root and insecure non-loopback deployment by default. Non-loopback HTTP requires explicit override and should only be used behind a trusted TLS terminator. Prefer TLS for direct non-local use.
 
+
+The shared Lima workflow uses a **separately negotiated v2** protocol, not a reinterpretation of the v1 single-root handshake. Each local TUI opens its own authenticated WebSocket and binds a workspace channel under the guest daemon's fixed parent mount. The daemon starts with `--daemon-shared-parent`; ordinary `--remote` still creates a v1 connection. Shared transfers are not advertised (ordinary v1 transfers remain available), and guest process execution is enabled for trusted clients only. See [sandbox.md](sandbox.md#direct-shared-lima-attachment) for attachment and stop policy.
+
 ## Configuration
 
 Common options:
@@ -74,7 +77,6 @@ File uploads/downloads and artifact reads use bounded streamed transfer messages
 
 A local daemon smoke-test image lives at `packages/coding-agent/examples/daemon-docker` and starts the packaged `grip --daemon` command inside the container.
 
-The sandbox base image used by `/sandbox start` lives at `packages/coding-agent/examples/sandbox-docker`. It builds from local release artifacts, expects the host workspace to be mounted at `/workspace`, and receives `GRIP_DAEMON_TOKEN` from the sandbox launcher environment. See [Docker Sandbox](sandbox.md) for the hidden `/sandbox` command, configuration precedence, auto-switch behavior, and security limits.
 
 ```bash
 docker build -f packages/coding-agent/examples/daemon-docker/Dockerfile -t grip-remote-daemon-test .

package/docs/docs.json

@@ -40,7 +40,7 @@
           "path": "daemon.md"
         },
         {
-          "title": "Docker Sandbox",
+          "title": "Lima Sandbox",
           "path": "sandbox.md"
         },
         {

package/docs/index.md

@@ -4,23 +4,19 @@ Grip is a minimal terminal coding harness. It is designed to stay small at the c
 
 ## Quick start
 
-When the package is available in your registry, install Grip with npm:
+Install the single compiled executable from a published Grip release:
 
 ```bash
-npm install -g --ignore-scripts @greppleai/grip
+# macOS/Linux
+curl -fsSL https://raw.githubusercontent.com/greppleai/grip/main/install.sh | sh
 ```
 
-`--ignore-scripts` disables dependency lifecycle scripts during install. Grip does not require install scripts for normal npm installs. This repository rename does not verify publication or ownership of the new npm scope.
-
-The former installer at `https://pi.dev/install.sh` belongs to the old Pi distribution; it is not a verified Grip installation method. Do not replace the hostname with a guessed endpoint.
-
-To uninstall Grip itself after an npm install, use:
-
-```bash
-npm uninstall -g @greppleai/grip
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/greppleai/grip/main/install.ps1 | iex
 ```
 
-For pnpm, Yarn, or Bun installs, use the matching global remove command: `pnpm remove -g @greppleai/grip`, `yarn global remove @greppleai/grip`, or `bun uninstall -g @greppleai/grip`.
+These commands require the scripts and checksummed release binaries to have been published. They do **not** install the Grip CLI through npm. See [Quickstart](quickstart.md) for pinning versions, PATH, and uninstall instructions; the old Pi installer at `https://pi.dev/install.sh` is unrelated.
 
 Then run it in a project directory:
 
@@ -41,7 +37,7 @@ For the full first-run flow, see [Quickstart](quickstart.md). Upgrading from the
 - [Settings](settings.md) - global and project settings.
 - [Language Server Protocol](lsp.md) - configure spawned servers, attached endpoints, host connections, and remote-backend path mappings.
 - [Remote Daemon](daemon.md) - run `grip --daemon` as a confined remote workspace runtime.
-- [Docker Sandbox](sandbox.md) - hidden user-only `/sandbox` command for Docker-backed workspace execution.
+- [Lima Sandbox](sandbox.md) - hidden user-only `/sandbox` command for Lima VM workspace execution.
 - [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
 - [Sessions](sessions.md) - session management, branching, and tree navigation.
 - [Compaction](compaction.md) - context compaction and branch summarization.

package/docs/packages.md

@@ -28,10 +28,10 @@ grip install ./relative/path/to/package
 
 grip remove npm:@foo/bar
 grip list                     # show installed packages from settings
-grip update                   # update Grip, update packages, and reconcile pinned git refs
+grip update                   # update packages; for a compiled CLI rerun the verified installer
 grip update --extensions      # update packages and reconcile pinned git refs only
-grip update --self            # update Grip only
-grip update --self --force    # reinstall Grip even if current
+grip update --self            # npm-managed CLI only; compiled binary cannot replace itself
+grip update --self --force    # npm-managed CLI only
 grip update npm:@foo/bar      # update one package
 grip update --extension npm:@foo/bar
 ```

package/docs/quickstart.md

@@ -4,33 +4,25 @@ This page gets you from install to a useful first Grip session.
 
 ## Install
 
-When available in your registry, Grip is distributed as an npm package:
+Install the single compiled binary from a published [Grip GitHub release](https://github.com/greppleai/grip/releases) (no npm required):
 
 ```bash
-npm install -g --ignore-scripts @greppleai/grip
+# macOS/Linux; inspect the script before running
+curl -fsSL https://raw.githubusercontent.com/greppleai/grip/main/install.sh | sh
 ```
 
-`--ignore-scripts` disables dependency lifecycle scripts during install. Grip does not require install scripts for normal npm installs. The new npm scope's publication and ownership have not been verified by this repository rename.
-
-### Uninstall
-
-Use the package manager that installed Grip:
-
-```bash
-# npm install -g
-npm uninstall -g @greppleai/grip
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/greppleai/grip/main/install.ps1 | iex
+```
 
-# pnpm
-pnpm remove -g @greppleai/grip
+The installers download a platform-specific executable and verify its published SHA-256 before placing it in your user PATH. Linux binaries target glibc (not Alpine/musl); macOS and Windows native functionality still requires platform validation. Set `GRIP_VERSION=vX.Y.Z` to pin a release or `GRIP_INSTALL_DIR` to select a destination; rerun to update. Open a new shell and confirm that `command -v grip` (PowerShell: `Get-Command grip.exe`) resolves to the installed binary; an older npm executable earlier in PATH can shadow it, and is never removed automatically. The scripts and release assets must be published first. A compiled binary may extract embedded resources into a private temporary directory at runtime, without installing Node or Bun.
 
-# Yarn
-yarn global remove @greppleai/grip
+Alternatively, install `@greppleai/grip` with `npm install -g @greppleai/grip` when you need a Node installation. Each release also publishes `@greppleai/grip-ai`, `@greppleai/grip-agent-core`, and `@greppleai/grip-tui` for extension and SDK development.
 
-# Bun
-bun uninstall -g @greppleai/grip
-```
+### Uninstall
 
-Uninstalling Grip leaves settings, credentials, sessions, and installed Grip packages in `~/.grip/agent/`. For migrating an older Pi installation, see [Migrating to Grip](migrating-to-grip.md). The old Pi curl installer is not a verified Grip installation method.
+For the binary installer, delete `~/.local/bin/grip` on macOS/Linux, or `%LOCALAPPDATA%\Programs\Grip\bin\grip.exe` on Windows (or the path set with `GRIP_INSTALL_DIR`). Remove the optional PATH entry from your shell profile or Windows user PATH if you no longer need it. For an npm installation, run `npm uninstall -g @greppleai/grip` instead. Uninstalling Grip leaves settings, credentials, sessions, and installed Grip packages in `~/.grip/agent/`. For migrating an older Pi installation, see [Migrating to Grip](migrating-to-grip.md). The old Pi installer is not a Grip installation method.
 
 Then start Grip in the project directory you want it to work on:
 

package/docs/sandbox.md

@@ -1,97 +1,52 @@
 # Workspace Sandbox
 
-`/sandbox` is the single interactive command for workspace tool backends. It can show or clear the active backend, attach an existing sandbox daemon, or manage a Docker container or Lima VM. Sandbox connections are session-local: a new session starts on its underlying backend, returning to an earlier session reconnects its remembered sandbox while Grip remains running, and multiple session sandboxes may coexist. Local Grip remains the orchestrator: provider credentials, model calls, session history, extensions, RPC, and UI stay in the local process; subagent workspace tools inherit the parent session's active sandbox.
+`/sandbox` is the user-only interactive command for workspace tool backends. It can show or clear the active backend, attach an existing sandbox daemon, or manage a Lima VM. Connections are session-local: switching back to an earlier session reconnects its remembered sandbox while Grip remains running. Local Grip retains provider credentials, model calls, session history, extensions, RPC, and UI; subagent workspace tools inherit the active backend.
 
-The command is user-only. It is shown in interactive slash-command completion, but it is not exposed through RPC `get_commands`, extension-visible command catalogs, system prompts, tool definitions, prompt templates, skills, or rules. This only hides the Grip operator command from LLM-visible catalogs; it does not prevent a model with host shell access from invoking Docker or Lima directly.
+The command appears in slash-command completion but not in model-visible catalogs, system prompts, tool definitions, templates, skills, or rules. This is not a permission boundary: a model with host shell access may still invoke Lima directly.
 
 ## Commands
 
-Type these commands in interactive mode:
-
 ```text
 /sandbox [status]
 /sandbox clear
 /sandbox --attach <ws://url>
-/sandbox start [--runtime docker|lima] [--image <image>] [--name <lima-instance>] [--template <lima-template>]
-/sandbox list [--runtime docker|lima]
-/sandbox stop [sandbox]
+/sandbox start [--name <lima-instance>] [--template <lima-template>] [--update]
+/sandbox list
+/sandbox stop [vm]
 ```
 
-- `/sandbox` and `/sandbox status` show the active workspace tool backend.
-- `/sandbox clear` disconnects the active deferred or sandbox backend without stopping a managed container or VM.
-- `/sandbox --attach` connects to an already-running sandbox daemon without starting or managing its container. Set `GRIP_REMOTE_TOKEN` when the daemon requires authentication. The daemon workspace root must match `--remote-cwd` in deferred mode, or `sandbox.workspaceMountPath` (default `/workspace`) otherwise.
-- `/sandbox start` launches a Docker container by default. With `--runtime lima`, it creates a Lima VM from `template:docker-rootful`, mounts the current working directory read-write at `/workspace`, starts `grip --daemon` inside the VM, and switches workspace tools and project resource loading to that daemon. Use `--template` to override the Lima template for a new VM. Passing `--name` implies `--runtime lima` when no runtime is specified; without `--name`, runtime selection is unchanged. `--name` creates the named instance if missing, starts it if stopped, or reuses it if running. Existing instances must already have a writable `/workspace` mount mapping to the current directory. Explicitly named VMs remain running after `/sandbox stop` or graceful Grip shutdown; only their Grip daemon is stopped, regardless of `sandbox.cleanup`.
-- `/sandbox list` lists sandboxes for the current workspace. Use `/sandbox list --runtime lima` to list matching Lima instances that can be reused by name.
-- `/sandbox stop` stops the active Grip-owned sandbox. For a daemon connected with `--attach`, it only detaches and restores the previous tool backend. Explicitly named Lima VMs remain running, but their Grip daemon is stopped. With an id or name, it uses the active runtime, or `sandbox.runtime` when no sandbox is active. Ambiguous cases require an explicit target.
-
-Example:
+- `/sandbox status` shows the active workspace tool backend. `/sandbox clear` disconnects it without stopping a VM.
+- `/sandbox --attach` connects to an already-running daemon without managing its lifecycle. Set `GRIP_REMOTE_TOKEN` if required. The daemon workspace root must match `--remote-cwd` in deferred mode, or `sandbox.workspaceMountPath` otherwise.
+- `/sandbox start` creates a per-session Lima VM with the current working directory mounted read/write at `/workspace`. `--template` overrides the VM template for a new instance. `--name` creates an absent VM, resumes a stopped per-session VM, or attaches to a running VM after guest-mode inspection. A running VM with a verified shared guest-state marker uses the direct shared-daemon protocol; a VM without it follows the per-session path.
+- `/sandbox start --name <running-shared-VM> --update` updates a verified shared guest and reconnects this TUI. It stages and validates the replacement first, stops its supervised daemon (disconnecting every attached client), atomically replaces the executable, and restarts the same service. It cannot be combined with `--template`; legacy, stopped, or unverifiable VMs are refused without disconnecting anyone.
+- `/sandbox list` shows Lima instances mounting the current workspace. A shared VM mounting a parent might not appear from a child workspace; attach by exact name instead.
+- `/sandbox stop` stops only tracked per-session daemons and process-owned VMs. For a shared named VM or an attached daemon it detaches the current session only. A matching name or mount does not establish ownership; named per-session VMs remain running after daemon stop. Grip never stops another client's shared guest or VM.
 
 ```text
-GRIP_REMOTE_TOKEN=... grip
-/sandbox --attach ws://127.0.0.1:8787/grip/workspace
-/sandbox stop
-
-/sandbox start --image grip-sandbox:local
+/sandbox start
+/sandbox start --template template:alpine
 /sandbox list
-
-/sandbox start --runtime lima
-/sandbox start --runtime lima --template template:alpine
-/sandbox list --runtime lima
 /sandbox stop
-
 /sandbox start --name my-dev
+/sandbox start --name my-dev --update
 /sandbox stop
 ```
 
-When start succeeds, Grip shows the sandbox name/id, the host-to-sandbox workspace mount, a redacted daemon endpoint, and a status line that workspace tools/resources now route through the sandbox daemon.
-
-## Workspace mount and daemon endpoint
-
-Defaults:
-
-| Setting | Default |
-| --- | --- |
-| Host workspace | current working directory |
-| Container workspace | `/workspace` |
-| Daemon command | `grip --daemon` |
-| Docker network mode | `bridge` |
-| Daemon preferred bind and endpoint | `127.0.0.1:8787` |
-| Daemon token | generated per start |
-| Lima binary | `limactl` |
-| Lima template | `template:docker-rootful` |
-
-The mounted workspace is read/write. Any process in the container can modify files in the mounted host directory. Paths reported by the daemon use the container workspace root (`/workspace`), while local Grip keeps session and UI state on the host. The container uses Docker bridge networking and publishes only the authenticated daemon port to the configured host bind address (`127.0.0.1` by default), so sandbox processes cannot directly access host loopback services. Grip uses the configured daemon port when available and otherwise selects an available host port, allowing separate sessions to keep concurrent sandbox containers. The default image also configures `/tmp` as an additional confined temporary root, so workspace tools can use disposable scratch files without exposing another host mount.
+A successful start shows the VM name/id, host-to-guest workspace mount, redacted daemon endpoint, and backend status. Workspace tools and resources then route through the guest daemon. Sandbox bash calls receive the current `GRIP_SESSION_ID`, `GRIP_SESSION_FILE`, `GRIP_PROVIDER`, `GRIP_MODEL`, and `GRIP_REASONING_LEVEL` metadata for the active session; other host environment variables are not forwarded automatically.
 
-Sandbox bash calls receive the current `GRIP_SESSION_ID`, `GRIP_SESSION_FILE`, `GRIP_PROVIDER`, `GRIP_MODEL`, and `GRIP_REASONING_LEVEL` values per invocation. This metadata follows the active session rather than the daemon process environment; other host environment variables are not forwarded automatically.
+## Configuration
 
-`/sandbox start` uses a fresh bearer token for every daemon. Docker receives it through the container environment. Lima generates it inside the guest and returns it directly to the host launcher. Grip keeps the token in memory and uses it to connect to the daemon. Tokens are not put in Docker or Lima command arguments, image layers, container or instance names, labels, URLs, or user-facing status. Status, list output, and errors redact secrets.
+The mounted workspace is writable. The daemon normally binds through a host loopback forward on port `8787`; newly created VMs select an available port if necessary. New per-session daemons use fresh bearer tokens. Running shared guests retain their existing token, retrieved by each local TUI via Lima access. Grip keeps tokens in memory and redacts them from displayed output. Tokens are not stored in session files, so sandbox backends are not restored after Grip exits.
 
-## Image and configuration
-
-The configured default image is `ghcr.io/greppleai/grip-sandbox:latest`, but its publication has not been verified. Until it is available, build a reviewed local image below or configure a verified compatible replacement; do not assume the default image can be pulled. The local example image uses integrated `grip --daemon` from `@greppleai/grip`. There is no separate Grip daemon package or binary.
-
-When a sandbox daemon connects, Grip also loads `~/.grip/AGENTS.md` from the daemon user's home directory as user-scoped context. This is separate from the orchestrator's global instructions and lets custom Docker images or Lima users define instructions that apply only inside the sandbox. Create or update the file inside the sandbox, then run `/reload` to refresh context.
-Configuration precedence for a start is:
-
-1. command flags: `/sandbox start --runtime <runtime>`, `--image <image>`, `--name <lima-instance>`, and `--template <lima-template>`;
-2. environment variables: `GRIP_SANDBOX_*`;
-3. project settings in `.grip/settings.json`;
-4. global settings in `~/.grip/agent/settings.json`;
-5. defaults.
-
-Sandbox settings:
+Start precedence: command `--template`, then `GRIP_SANDBOX_*` environment variables, project `.grip/settings.json`, global `~/.grip/agent/settings.json`, then defaults. Available settings:
 
 ```json
 {
   "sandbox": {
-    "runtime": "docker",
-    "image": "grip-sandbox:local",
-    "dockerBinary": "docker",
     "limaBinary": "limactl",
     "limaTemplate": "template:docker-rootful",
     "limaInstanceNamePrefix": "grip-sandbox",
     "workspaceMountPath": "/workspace",
-    "containerNamePrefix": "grip-sandbox",
     "daemonPort": 8787,
     "daemonHostBind": "127.0.0.1",
     "cleanup": "stop"
@@ -99,83 +54,51 @@ Sandbox settings:
 }
 ```
 
-Environment overrides:
-
-| Variable | Setting |
+| Environment variable | Setting |
 | --- | --- |
-| `GRIP_SANDBOX_RUNTIME` | `sandbox.runtime` (`docker` or `lima`) |
-| `GRIP_SANDBOX_IMAGE` | `sandbox.image` |
-| `GRIP_SANDBOX_DOCKER` | `sandbox.dockerBinary` |
 | `GRIP_SANDBOX_LIMA` | `sandbox.limaBinary` |
 | `GRIP_SANDBOX_LIMA_TEMPLATE` | `sandbox.limaTemplate` |
 | `GRIP_SANDBOX_LIMA_INSTANCE_PREFIX` | `sandbox.limaInstanceNamePrefix` |
 | `GRIP_SANDBOX_WORKSPACE_MOUNT` | `sandbox.workspaceMountPath` |
-| `GRIP_SANDBOX_CONTAINER_PREFIX` | `sandbox.containerNamePrefix` |
 | `GRIP_SANDBOX_DAEMON_PORT` | `sandbox.daemonPort` |
 | `GRIP_SANDBOX_DAEMON_HOST_BIND` | `sandbox.daemonHostBind` |
 | `GRIP_SANDBOX_CLEANUP` | `sandbox.cleanup` (`stop` or `remove`) |
+| `GRIP_SANDBOX_GUEST_BINARY` | Explicit local Linux ELF guest executable for development |
 
-## Base image
-
-Build the local base image from repository release artifacts:
+The default Lima template name contains `docker-rootful`; it is a Lima VM template choice, not a Docker-container sandbox runtime. Change `sandbox.limaTemplate` or use `--template` to select a different Lima template.
 
-```bash
-npm run release:local -- --out /tmp/grip-local-release --force
-docker build \
-  -f packages/coding-agent/examples/sandbox-docker/Dockerfile \
-  -t grip-sandbox:local \
-  /tmp/grip-local-release
-```
-
-Then use it for one start:
-
-```text
-/sandbox start --image grip-sandbox:local
-```
+### Guest Grip during development
 
-Or make it the default:
+A new managed VM installs an exact-version Linux Grip release using the checksummed repository installer, when those release assets are published. Existing named VMs must already provide Grip. To test local code, cross-compile a Linux binary matching the guest architecture and opt in:
 
 ```bash
-GRIP_SANDBOX_IMAGE=grip-sandbox:local grip
+NODE_OPTIONS=--import=tsx ./scripts/build-binaries.sh --skip-install --platform linux-x64
+GRIP_SANDBOX_GUEST_BINARY="$PWD/packages/coding-agent/binaries/grip-linux-x64" ./grip-test.sh
+# In Grip: /sandbox start --name my-dev --update
 ```
 
-See [`../examples/sandbox-docker/README.md`](../examples/sandbox-docker/README.md) for image build inputs and manual `docker run` commands.
+For ARM64 use `--platform linux-arm64` and `grip-linux-arm64`. The ELF is validated, copied via `limactl copy` only when safe, checked against its SHA-256 and version, and installed at `~/.local/bin/grip`. An identical installation is reused. Normal attachment never replaces the running shared guest's binary. Explicit `--update` uses `GRIP_SANDBOX_GUEST_BINARY` when set; a source/tsx development session requires it rather than silently installing a release. Otherwise the update downloads the checksummed Linux release matching the Grip version that issued the command. The shared systemd unit must already run `~/.local/bin/grip`; other service binary paths require manual reconciliation. Downloads and validation complete before client disconnection. An uncertain install or restart leaves the VM for inspection. The guest needs `sha256sum` and `/proc`.
 
-## Sandbox identity, list, and stop
+## Direct shared Lima attachment
 
-Grip labels sandbox containers and filters list/stop operations by those labels, not by name alone. Labels include sandbox ownership, workspace hash, workspace mount target, daemon port, owner uid when available, Grip version, and a session id. Labels do not contain tokens.
+In each host workspace run `/sandbox start --name <running-shared-VM>`. The VM must already have a fixed writable parent mount, matching loopback forward, exact-version guest Grip, and a verified `~/.cache/grip/shared-lima` guest-state directory. Its systemd user manager must be running with linger enabled so Grip can start or reuse a supervised shared daemon. This command does not provision a new shared VM or convert a legacy one: a running VM without the shared marker takes the per-session path.
 
-Docker container names use the configured prefix plus a sanitized workspace name, workspace hash, and per-start session suffix. Managed Lima names use `sandbox.limaInstanceNamePrefix` with the same workspace/session identity and a random suffix. Daemon ports are allocated per start, preferring `sandbox.daemonPort` and falling back to an available host port. `/sandbox list --runtime lima` reports Lima instances whose writable `/workspace` mount maps to the current host workspace; their names can be passed back to `/sandbox start --runtime lima --name <name>`. Explicitly named VMs are left running by `/sandbox stop`, whether newly created or reused, while Grip stops or removes automatically named VMs according to `sandbox.cleanup`.
+Each TUI obtains the guest credential through local Lima access and opens its own authenticated v2 WebSocket workspace channel. Parent-root clients can access their children; shared file writes and edits use revision preconditions, but shell writes can still race. Transfers are unavailable in shared mode. `/sandbox stop` and `/sandbox clear` detach only the current TUI; neither stops the shared daemon or VM. Coordinate all clients and independently verify ownership before any manual guest or VM shutdown.
 
-Stopping the active sandbox clears the current session's remote tool backend and returns it to the previous non-sandbox backend or local tool execution. If Grip was started in deferred remote mode, stop leaves that session's deferred backend unconfigured. Switching sessions disconnects the old live client without stopping its managed sandbox; returning to that session reconnects it from memory. On graceful Grip shutdown, Docker containers and automatically named Lima instances started by that Grip process are stopped or removed according to `sandbox.cleanup`; explicitly named Lima VMs remain running with their Grip daemon stopped. Tokens are never persisted to session files, so sandboxes are not restored after Grip exits.
+Grip probes guest mode under the named owner lock before any legacy setup. A missing marker follows the per-session path; unreadable, symlinked, or ambiguous state refuses attachment. A stopped shared VM with a mismatched mount is not automatically resumed. Per-session start and stop check for shared guest state before rotating or killing a legacy daemon. Noncooperating programs may ignore these locks; a VM name alone proves nothing.
 
-## Security boundaries
+Shared startup requires guest `systemd-run --user`, `systemctl --user`, and `loginctl ... Linger=yes` already enabled by an operator. Grip launches one transient `grip-shared-lima-PORT.service` with `Restart=no`; it does not automatically restart failed units or retry uncertain operations. The unit reads its private 0600 token file without passing credentials in service arguments. Grip verifies its MainPID against a boot-ID/process-start-time-bound PID record before reuse. Missing manager, mismatched process identity, or uncertain guest state require manual reconciliation; guest shutdown remains explicit.
 
-Docker and Lima sandbox modes are not complete security sandboxes.
+## Lifecycle and security
 
-- The current working directory is mounted read/write into the container or VM.
-- Subagents inherit the active workspace backend. Sandboxed subagents reject host cwd overrides, do not load host project context or extensions, treat custom system prompts as literal text, and cannot continue an older run after the parent backend changes.
-- Sandbox processes can read, write, delete, or chmod files in that mount as the guest user.
-- Files created by the default image are owned by uid `1000` unless Docker/user policy changes it.
-- `/tmp` is writable container-local scratch storage and is removed with the container; it is not mounted from the host by default.
-- The daemon token authorizes high-privilege workspace tool access for the mounted workspace.
-- Anyone with Docker access on the host may inspect containers, images, mounts, labels, ports, and environment depending on host policy.
-- Override Docker images and Lima templates are trusted code. A malicious image or template can run arbitrary processes against the mounted workspace.
-- Docker socket mounts, privileged mode, broad host volumes, or extra credentials can further break the intended boundary.
-- Bridge networking prevents direct host-loopback access, but the container may still reach external networks and host services deliberately exposed beyond loopback.
-- Reused Lima instances retain their existing filesystem, software, credentials, and network access; only reuse instances you trust.
-- Hidden command behavior only keeps `/sandbox` out of LLM-visible Grip catalogs. It is not an OS, Docker, or VM permission boundary.
+Automatically named, process-owned VMs follow `sandbox.cleanup` on graceful Grip shutdown, subject to stopped-VM uncertainty. Tracked per-session named Lima daemons stop without stopping their VMs. A failed readiness check leaves uncertain guest state for manual reconciliation. Shared guest daemons and VMs remain running. Session switches reconnect remembered channels while the process remains running.
 
-Use trusted images, avoid mounting the Docker socket, avoid privileged containers, keep `sandbox.daemonHostBind` loopback-only unless you add a separate trusted network/TLS boundary, and do not place secrets in the mounted workspace unless the sandbox image should access them.
+Lima VMs are not complete security sandboxes. The workspace is mounted read/write and guest processes can modify it as the guest user. Subagents inherit the active workspace backend, reject host cwd overrides, and do not load host project context or extensions. The daemon token grants privileged workspace tool access. Reused VMs retain their own software, credentials, filesystem, and network access; use only trusted instances and Lima templates. Keep `sandbox.daemonHostBind` loopback-only unless you provide a separate trusted network/TLS boundary, and do not store secrets in the mounted workspace unless the guest should read them.
 
 ## Troubleshooting
 
-- Docker missing: install Docker or set `GRIP_SANDBOX_DOCKER` / `sandbox.dockerBinary` to the correct executable.
-- Lima missing: install Lima or set `GRIP_SANDBOX_LIMA` / `sandbox.limaBinary`. Newly created Lima VMs, including explicitly named ones, provision the current `@greppleai/grip` version through npm when `grip` is missing; reused instances must already provide a compatible `grip` command. Provisioning requires an apt-based guest and package availability.
-- Permission denied connecting to Docker: add the user to the appropriate Docker group, start Docker Desktop, or run Grip where Docker is accessible. Treat Docker group membership as host-level administrative power.
-- Image pull/build failure: verify the image name, registry authentication, network access, and local build command. For local images, build with the local release directory as context; do not use `--skip-install` for the sandbox Dockerfile.
-- Port conflict: Grip prefers the configured daemon port (default `8787`) and automatically selects an available port when it is occupied. A remaining bind failure can indicate an invalid `sandbox.daemonHostBind`, exhausted local resources, or a race with another process.
-- Start succeeds but daemon activation fails: the container or VM may still be running. Use the runtime-specific `/sandbox list` and `/sandbox stop <id-or-name>` commands to clean it up.
-- `/sandbox list` is empty: Docker listing only includes Grip-labeled containers; Lima listing only includes instances with the current workspace mounted at `/workspace`. Check that you selected the intended runtime and workspace.
-- `/sandbox stop` says no sandbox was found: pass the listed id or name, or switch to the workspace that owns the sandbox.
-- Already stopped: stop is idempotent for matching containers and reports already-stopped containers cleanly.
+- Lima missing: install Lima or configure `GRIP_SANDBOX_LIMA` / `sandbox.limaBinary`. New managed VMs require the published exact-version guest installer; reused VMs must provide a matching binary.
+- Port conflict: a newly created VM selects an available port; a running shared VM requires its configured forward to match exactly.
+- Activation failure: inspect VM and daemon state before retrying; do not stop an unverified VM or other shared clients.
+- Empty `/sandbox list`: only instances mounting the current workspace appear. An ancestor-mounted shared VM may not appear from a child directory; attach by name.
+- `/sandbox stop` not found: use the listed id or name, or switch to the owning workspace. Stopped or uncertain VMs require manual reconciliation before removal.

package/docs/settings.md

@@ -189,30 +189,31 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 
 Global and project `tools` settings merge per tool name, so a project can override `tools.websearch.baseUrl` while keeping a global `tools.websearch.apiKey`. Environment variables remain supported for `websearch`; explicit settings take precedence. Firecrawl uses `POST /v2/search` with web results only.
 
-### Docker Sandbox
+### Lima Sandbox
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `sandbox.image` | string | `"ghcr.io/greppleai/grip-sandbox:latest"` (not yet verified as published) | Docker image used by `/sandbox start`; override with a reviewed available image until the Grip image is published |
-| `sandbox.dockerBinary` | string | `"docker"` | Docker executable |
-| `sandbox.workspaceMountPath` | string | `"/workspace"` | Container path for the mounted current workspace |
-| `sandbox.containerNamePrefix` | string | `"grip-sandbox"` | Prefix for generated container names |
-| `sandbox.daemonPort` | number | `8787` | Preferred loopback-published daemon port; an available port is selected when occupied |
-| `sandbox.daemonHostBind` | string | `"127.0.0.1"` | Host address used to publish the container daemon port |
-| `sandbox.cleanup` | string | `"stop"` | Stop behavior: `"stop"` or `"remove"` |
+| `sandbox.limaBinary` | string | `"limactl"` | Lima executable |
+| `sandbox.limaTemplate` | string | `"template:docker-rootful"` | Template used to create a managed VM |
+| `sandbox.limaInstanceNamePrefix` | string | `"grip-sandbox"` | Generated VM name prefix |
+| `sandbox.workspaceMountPath` | string | `"/workspace"` | Guest path for the mounted current workspace |
+| `sandbox.daemonPort` | number | `8787` | Preferred loopback-forwarded daemon port; an available port is selected when occupied for new VMs |
+| `sandbox.daemonHostBind` | string | `"127.0.0.1"` | Host bind for the daemon forward |
+| `sandbox.cleanup` | string | `"stop"` | Stop behavior: `"stop"` or `"remove"` for owned VMs |
 
 ```json
 {
   "sandbox": {
-    "image": "grip-sandbox:local",
+    "limaBinary": "limactl",
     "cleanup": "remove"
   }
 }
 ```
 
-Precedence for sandbox starts is command flag, then `GRIP_SANDBOX_*` environment variables, then project settings, then global settings, then defaults. See [Docker Sandbox](sandbox.md) for command syntax, environment variable names, and security notes. The default image above is an upstream Pi artifact; no Grip image location has been verified.
+Precedence for sandbox starts is `--template`, `GRIP_SANDBOX_*` environment variables, project settings, global settings, then defaults. See [Lima Sandbox](sandbox.md) for command syntax, environment variables, and security notes.
 
-### Sessions
+
+For a running shared Lima VM, `/sandbox start --name` uses `sandbox.workspaceMountPath`, `sandbox.daemonHostBind`, `sandbox.daemonPort` and `sandbox.limaBinary` to verify its fixed writable parent mount and loopback forward before attaching. `sandbox.cleanup` does not authorize stopping or deleting the shared VM. Auth, config and sessions remain on the host; same-user agents share the default host directory unless each selects a distinct `GRIP_CODING_AGENT_DIR`. Shared writes and edits use revision preconditions, but shell writes can still race. Shared transfers are unavailable; guest process execution requires trusted clients. See [sandbox.md](sandbox.md#direct-shared-lima-attachment).
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|

package/docs/termux.md

@@ -9,24 +9,7 @@ Grip runs on Android via [Termux](https://termux.dev/), a terminal emulator and
 
 ## Installation
 
-When `@greppleai/grip` is available in your registry:
-
-```bash
-# Update packages
-pkg update && pkg upgrade
-
-# Install dependencies
-pkg install nodejs termux-api git
-
-# Install Grip
-npm install -g --ignore-scripts @greppleai/grip
-
-# Create config directory
-mkdir -p ~/.grip/agent
-
-# Run Grip
-grip
-```
+The single-file release installers support **macOS, Linux, and Windows**, not Android/Termux. Do not run the Linux installer here: its native modules and system ABI are not Android builds. There is currently no supported Grip binary or npm release for Termux. A source checkout and Termux-specific build would need separate validation before documenting an installation procedure.
 
 ## Clipboard Support
 

package/docs/usage.md

@@ -139,13 +139,13 @@ grip remove <source> [-l]        # Remove package
 grip uninstall <source> [-l]     # Alias for remove
 grip update [source|self|grip]   # Update Grip and packages; reconcile pinned git refs
 grip update --extensions        # Update packages only; reconcile pinned git refs
-grip update --self              # Update Grip only
+grip update --self              # npm-managed installs only; for binary installs rerun the verified installer
 grip update --extension <src>   # Update one package
 grip list                       # List installed packages
 grip config                     # Enable/disable package resources
 ```
 
-These commands manage Grip packages, not the Grip CLI installation. To uninstall Grip itself, see [Quickstart](quickstart.md#uninstall).
+These commands manage Grip packages; the compiled binary itself updates by rerunning the [verified installer](quickstart.md#install), not `grip update --self`. To uninstall Grip itself, see [Quickstart](quickstart.md#uninstall).
 
 See [Grip Packages](packages.md) for package sources and security notes.
 

package/examples/README.md

@@ -18,8 +18,6 @@ Example extensions demonstrating:
 - External integrations (SSH, file watchers, system theme sync)
 - Custom providers (Anthropic with custom streaming, GitLab Duo)
 
-### [sandbox-docker/](sandbox-docker/)
-Base Docker image for `/sandbox start`. Builds from local release artifacts and runs the packaged `grip --daemon` command with `/workspace` as the mounted workspace.
 
 ### [remote-session-server/](remote-session-server/)
 Hono-based remote session storage server. It uses static bearer auth and stores sessions as JSONL files for debugging the remote session protocol end-to-end.

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.0.1",
+	"version": "0.1.3",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.0.1",
+	"version": "0.1.3",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-sandbox",
 	"private": true,
-	"version": "0.0.1",
+	"version": "0.1.3",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-with-deps",
 	"private": true,
-	"version": "0.0.1",
+	"version": "0.1.3",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",