lcode-cli 0.4.1__tar.gz → 0.6.0__tar.gz

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/CHANGELOG.md

@@ -6,6 +6,35 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-01
+
+### Added
+
+- lcode can look at images: attach a screenshot, mockup or diagram with `@path`, and the model can
+  open images itself with the new `view_image` tool. A model that can see describes the image in
+  detail (all text transcribed, with your question in mind): your model itself if it can see, or
+  the original model behind lcode's text-only variant, which `lcode setup` already downloaded
+  (`vision_model` setting; `lcode doctor` shows which). Screenshots returned by MCP tools, such as
+  Playwright's, are described too.
+- `lcode mcp add comfyui`: generate and edit images with models you run locally in ComfyUI (FLUX,
+  SDXL, Stable Diffusion 1.5, Qwen-Image), through ComfyUI's official MCP server, with only its local
+  tools enabled.
+- MCP servers can mark tools that need the GPU to themselves (`free_gpu` in `mcp.json`): lcode
+  unloads its own model before they run and reloads it afterwards. On for ComfyUI's generation tools,
+  so image models work on a 12 GB GPU next to a large coding model.
+
+## [0.5.0] - 2026-10-01
+
+### Added
+
+- An optional sandbox for shell commands: with `lcode --sandbox` (or `sandbox = "docker"` /
+  `"podman"`), the model's commands run in a container that only sees the project folder, as your
+  user, with no network access unless you allow it (`/sandbox network on`, `sandbox_network`), no
+  Linux capabilities and a process limit. The file tools are limited to the project too. lcode builds
+  a default image with Python, Node.js, git and build tools on first use (`sandbox_image` for your
+  own). In `auto-edit` mode, sandboxed commands run without asking. If the sandbox can't start, lcode
+  stops instead of running commands without it.
+
 ## [0.4.1] - 2026-10-01
 
 ### Added
@@ -174,7 +203,9 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/nasser1941/lcode/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/nasser1941/lcode/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/nasser1941/lcode/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/nasser1941/lcode/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/nasser1941/lcode/compare/v0.3.0...v0.3.1

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.4.1
+Version: 0.6.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -78,13 +78,18 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   real coding tasks on your machine.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
+- **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
+  Podman) that only sees your project, without network access unless you allow it.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
   with tool calling.
 - **MCP servers, ready to go.** Connect Jira and Confluence, GitHub, AWS, Google Drive, Grafana,
   Google Cloud, Sentry, Linear, Notion, Postgres, Kubernetes and more with one command
-  (`lcode mcp add atlassian`), or any other MCP server. Browser sign-in (OAuth) is built in.
+  (`lcode mcp add atlassian`), image generation with ComfyUI, or any other MCP server. Browser sign-in (OAuth) is built in.
+- **Sees images.** Attach a screenshot or mockup with `@path` and lcode looks at it, using the
+  vision part of your model. With ComfyUI (`lcode mcp add comfyui`) it can also generate and edit
+  images with local models such as FLUX, SDXL and Qwen-Image.
 - **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
   search, Brave, Tavily or your own SearXNG, and reads pages as clean text.
 - **Private.** The model runs on your machine, lcode never uploads your files and has no telemetry.
@@ -184,7 +189,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- An [optional sandbox for shell commands](https://github.com/nasser1941/lcode/issues/9)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 
 ## Contributing

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/README.md

@@ -44,13 +44,18 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   real coding tasks on your machine.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
+- **Sandbox (optional).** `lcode --sandbox` runs the model's shell commands in a container (Docker or
+  Podman) that only sees your project, without network access unless you allow it.
 - **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
   request's edits, new files and shell-command changes, without touching your git history.
 - **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
   with tool calling.
 - **MCP servers, ready to go.** Connect Jira and Confluence, GitHub, AWS, Google Drive, Grafana,
   Google Cloud, Sentry, Linear, Notion, Postgres, Kubernetes and more with one command
-  (`lcode mcp add atlassian`), or any other MCP server. Browser sign-in (OAuth) is built in.
+  (`lcode mcp add atlassian`), image generation with ComfyUI, or any other MCP server. Browser sign-in (OAuth) is built in.
+- **Sees images.** Attach a screenshot or mockup with `@path` and lcode looks at it, using the
+  vision part of your model. With ComfyUI (`lcode mcp add comfyui`) it can also generate and edit
+  images with local models such as FLUX, SDXL and Qwen-Image.
 - **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
   search, Brave, Tavily or your own SearXNG, and reads pages as clean text.
 - **Private.** The model runs on your machine, lcode never uploads your files and has no telemetry.
@@ -150,7 +155,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- An [optional sandbox for shell commands](https://github.com/nasser1941/lcode/issues/9)
 - More models in the catalog, and test reports from your hardware ([report one](https://github.com/nasser1941/lcode/issues/new?template=model_request.yml))
 
 ## Contributing

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/SECURITY.md

@@ -25,8 +25,13 @@ user, in your working directory**. It is not a sandbox. Keep in mind:
 
 - In the default `ask` mode, every file edit and every shell command that isn't on the read-only
   allowlist (`ls`, `cat`, `grep`, `git status`, …) is shown to you and needs your approval.
-  `auto-edit` skips approval for edits; `yolo` skips all approval — use it only in disposable
-  environments (a container, a VM, a throwaway clone).
+  `auto-edit` skips approval for edits; `yolo` skips all approval — use it only with the sandbox or
+  in disposable environments (a VM, a throwaway clone).
+- The optional sandbox (`sandbox = "docker"` or `"podman"`, or `lcode --sandbox`) runs shell commands
+  in a container that sees only the project folder, as your user, without network access unless
+  allowed. The file tools are then limited to the project too. It doesn't cover web or MCP tools,
+  the project folder itself stays writable, and a container shares the host kernel; see
+  https://nasser1941.github.io/lcode/sandbox/ for its limits.
 - Content the model reads (files, command output, search results and web pages) can contain prompt
   injections that try to make it run harmful commands. lcode marks web content as untrusted, but
   review commands before approving them.

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/docs/configuration.md

@@ -25,6 +25,10 @@ lcode config path                      # print the file location
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
 | `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |
 | `searxng_url` | | Your SearXNG instance, e.g. `http://localhost:8888` |
+| `sandbox` | `off` | Run shell commands in a container: `docker` or `podman` ([Sandbox](sandbox.md)) |
+| `sandbox_image` | lcode's image | Container image for the sandbox; any image with bash and setsid |
+| `sandbox_network` | `false` | Let commands in the sandbox use the network |
+| `vision_model` | `auto` | The model that [looks at images](usage.md#images): `auto`, `off` or an Ollama model that can see |
 | `mcp_tools` | `auto` | How [MCP](mcp.md#context) tool definitions reach the model: `auto`, `direct` or `search` (on demand) |
 | `checkpoints` | `true` | Save a checkpoint before the model changes files, so [`/undo`](usage.md#undo-and-checkpoints) can restore them |
 
@@ -50,6 +54,7 @@ Environment variables override the file, which is useful for one-off runs and CI
 | `LCODE_KEEP_ALIVE` | `keep_alive` |
 | `OLLAMA_HOST` | `ollama_host` (same variable the Ollama CLI uses) |
 | `LCODE_WEB` | `web` |
+| `LCODE_SANDBOX` | `sandbox` |
 | `OLLAMA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` | API key for that [search provider](usage.md#web-search) (never stored in the config file) |
 | `LCODE_HOME` | where sessions and prompt history are stored |
 

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/docs/how-it-works.md

@@ -77,6 +77,8 @@ the Ollama server you configure, it only contacts the web when the model searche
 | `permissions.py` | Approval prompts and the read-only allowlist |
 | `mcp/` | MCP client: stdio and HTTP transports, OAuth sign-in, server settings, the catalog, `lcode mcp` |
 | `bench.py` | `lcode bench`: the benchmark tasks, their checks and the reports |
+| `vision.py` | Looking at images with a model that can see |
+| `sandbox.py` | The optional container for shell commands |
 | `checkpoints.py` | Snapshots before the model changes files, for `/undo` and `/rewind` |
 | `catalog.py`, `models.toml` | Model catalog and memory estimates |
 | `hardware.py` | NVIDIA / Apple Silicon detection |

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/docs/mcp.md

@@ -28,6 +28,7 @@ and find the code for the top one."*
 | `gcp` | `gcloud` commands on your Google Cloud projects | `npx` and the `gcloud` CLI, signed in |
 | `github` | Repositories, issues, pull requests, Actions | a GitHub token (or the GitHub CLI) |
 | `playwright` | A real (headless) browser: open pages, click, fill forms | `npx` |
+| `comfyui` | Generate and edit images with local models (FLUX, SDXL, SD 1.5, Qwen-Image) | `uvx` and [ComfyUI](#images-with-comfyui) running locally |
 | `context7` | Up-to-date docs and examples for thousands of libraries | nothing (an API key is optional) |
 | `sentry` | Errors, issues, traces and releases | a Sentry account (browser sign-in) |
 | `postgres` | Schemas, read-only queries, query performance | `uvx`, a connection URL |
@@ -82,6 +83,57 @@ Google Cloud project:
 See [Google's guide](https://developers.google.com/workspace/guides/configure-mcp-servers) for
 details.
 
+### Images with ComfyUI
+
+[ComfyUI](https://github.com/comfyanonymous/ComfyUI) runs image generation and editing models
+locally; its official MCP server lets lcode use it, for app icons, illustrations, mockups or
+placeholder art.
+
+```bash
+uv tool install comfy-cli && comfy install                 # ComfyUI, once
+comfy launch --background -- --disable-smart-memory          # start it (http://127.0.0.1:8188)
+lcode mcp add comfyui
+```
+
+Then add models in ComfyUI (its model manager, or ask lcode: *"download FLUX.2 Klein 4B in
+ComfyUI"*), and ask for images: *"make a 512×512 app icon of a paper plane and save it in
+assets/"*. To edit an image, ask lcode to upload it and run an editing workflow (Kontext or
+Qwen-Image-Edit).
+
+| Model | Good for | On a 12 GB GPU |
+|---|---|---|
+| FLUX.2 Klein 4B | Generation and editing, fast | Fits (about 8 GB) |
+| SDXL and its community models | Generation, inpainting | Fits |
+| Stable Diffusion 1.5 and its community models | Light generation, inpainting | Fits easily |
+| FLUX.1 Dev and finetunes | High-quality generation | Needs an fp8 or GGUF version; slower |
+| FLUX.1 Kontext Dev | Editing an image from instructions | Needs an fp8 or GGUF version; slower |
+| Qwen-Image / Qwen-Image-Edit | Generation and editing, good text in images | Heavy: a GGUF version and RAM offloading |
+
+Only ComfyUI's local tools are turned on; Comfy Cloud's partner tools are left out, so prompts and
+images stay on your machine.
+
+**Sharing one GPU.** A GPU rarely holds a coding model and an image model at the same time, so the
+two take turns: before ComfyUI generates, lcode unloads its own model (the `free_gpu` setting), and
+ComfyUI started with `--disable-smart-memory` gives the GPU back after each image. lcode's model
+then reloads for the next step, which adds a few seconds to half a minute per image request. With
+enough GPU memory for both (or on a Mac with plenty of memory), remove `free_gpu` from the server's
+settings in `mcp.json`. lcode can also look at the results ([Images](usage.md#images)).
+
+Measured on an RTX 4080 Laptop GPU (12 GB) with qwen3.6-35b at 64K context and FLUX.2 Klein Base 4B
+(fp8, 512×512, 20 steps):
+
+| | |
+|---|---|
+| Generating while lcode's model is loaded | Fails: ComfyUI runs out of GPU memory |
+| Freeing the GPU (lcode unloads its model) | 0.2 s |
+| Generating one image | about 12 s |
+| Reloading lcode's model afterwards | about 20 s |
+
+The first time, the model has to find the right template and fill in its settings (model file names,
+size, prompt), which can take several minutes of trial and error. Once an image comes out right, ask
+lcode to save that workflow in your project (for example `assets/icon.workflow.json`) and reuse it:
+later images are a single `run_workflow` call.
+
 ## Adding your own servers
 
 Any MCP server works. For a remote server, give its URL; for a local one, the command that starts it:
@@ -122,6 +174,7 @@ document, so you can also paste a server's example config into that file:
 | `allow` | Tools that run without asking; `["*"]` for all of the server's tools |
 | `timeout` | Seconds a tool call may take (default 300) |
 | `disabled` | `true` to turn the server off (`lcode mcp disable <name>`) |
+| `free_gpu` | Tools that need the GPU to themselves (`true` for all): lcode unloads its model first and reloads it afterwards |
 | `oauth` | For servers that need a pre-registered OAuth client: `client_id`, `client_secret`, `scopes`, `authorize_params` |
 
 Values can use environment variables: `${NAME}`, or `${NAME:-default}`. Keep tokens in environment

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/docs/models.md

@@ -225,7 +225,9 @@ GPU's share of unified memory. Results from other Macs are very welcome in the
 
 ## Text-only variants
 
-Some models (the Qwen3.6 family, for example) ship with a vision encoder that a coding agent doesn't
-use. `lcode setup` creates a text-only variant named `lcode-<key>` that reuses the downloaded
+Some models (the Qwen3.6 family, for example) ship with a vision encoder that a coding agent rarely
+needs. `lcode setup` creates a text-only variant named `lcode-<key>` that reuses the downloaded
 weights, so it takes no extra disk space, and frees about 1 GB of GPU memory for the context cache
 (and for a larger prompt batch, where it fits; see [tuning](configuration.md#tuning-for-speed-and-memory)).
+When you show lcode an image, it borrows the original model, vision encoder included, to look at it
+(see [Images](usage.md#images)).

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.4.1 — local coding agent            │
+│ lcode v0.6.0 — local coding agent            │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

lcode_cli-0.6.0/docs/sandbox.md

@@ -0,0 +1,79 @@
+# Sandbox
+
+By default the model's shell commands run directly on your machine, as you. The permission prompts
+let you check each command, but they're a guardrail, not isolation, and `yolo` mode removes even
+that. The sandbox runs the commands in a container that can only see your project:
+
+```bash
+lcode --sandbox                       # this session
+lcode config set sandbox docker       # every session (or podman)
+```
+
+The session's banner then shows `sandbox  docker · lcode's image · no network`.
+
+## What the container can and can't do
+
+| | |
+|---|---|
+| **Sees** | Your project: the git repository you started lcode in (or the folder itself, outside a repository), mounted at the same path, read-write |
+| **Doesn't see** | Anything else on your machine: your home folder, SSH keys, cloud credentials, other projects, the Docker socket |
+| **Network** | None, unless you allow it (`/sandbox network on`, or `sandbox_network = true`) |
+| **Runs as** | Your user ID, so files it creates belong to you; no Linux capabilities, no privilege escalation, at most 1,024 processes |
+| **Lives** | For the session: started when lcode starts, removed when it exits. Containers left behind by a crash are removed the next time |
+
+lcode's file tools (reading, editing, searching) run on your machine, but with the sandbox on they're
+limited to the same project folder, so the model's whole world is the project.
+
+## Approvals
+
+With the sandbox on, `auto-edit` mode runs shell commands without asking too, since they can only
+change the project, and [`/undo`](usage.md#undo-and-checkpoints) can take those changes back. `ask`
+mode still asks before every command that isn't read-only. `yolo` asks for nothing, with or without
+the sandbox.
+
+## The image
+
+lcode builds its default image the first time you use the sandbox (a minute or two): Python 3.12,
+Node.js, git, build tools, ripgrep, curl and jq. Use your own image to match your project's toolchain:
+
+```bash
+lcode config set sandbox_image node:22
+```
+
+Any image with `bash` and `setsid` works. Installing packages (`pip install`, `npm install`) needs
+the network: allow it with `/sandbox network on` for the session, or `sandbox_network = true`. The
+model is told when a command failed because there's no network.
+
+## Settings
+
+| Setting | Default | |
+|---|---|---|
+| `sandbox` | `off` | `docker` or `podman` to run commands in a container |
+| `sandbox_image` | lcode's image | Any image with bash and setsid |
+| `sandbox_network` | `false` | Let commands use the network |
+
+In a session, `/sandbox` shows the sandbox and `/sandbox network on|off` changes network access (the
+container restarts; files in the project stay). `lcode doctor` checks that Docker or Podman works.
+
+## Requirements
+
+- **Linux:** [Docker Engine](https://docs.docker.com/engine/install/) (your user in the `docker`
+  group) or [Podman](https://podman.io/docs/installation) (rootless; lcode passes `--userns keep-id`.
+  Podman is less tested than Docker, so reports are welcome).
+- **macOS:** Docker Desktop, [OrbStack](https://orbstack.dev) or [colima](https://github.com/abiosoft/colima).
+  Your project must be in a folder they share with containers (your home folder is, by default).
+
+If the sandbox is on but can't start, lcode stops instead of running commands without it, and says
+how to fix it.
+
+## What the sandbox doesn't cover
+
+It isolates **shell commands**. Know its limits:
+
+- The project folder is writable: a command can still delete or damage your project's files. Use git,
+  and `/undo` for changes since the request started.
+- With the network on, commands can reach the internet, including to send out anything in the project.
+- [Web search and page fetching](usage.md#web-search) and [MCP tools](mcp.md) run on your machine,
+  not in the container. They still need their own approval (MCP) or can be turned off (`--no-web`).
+- A container is not a virtual machine: it shares your machine's kernel, so a kernel vulnerability
+  could let a process escape. For untrusted code you can't afford to run, use a separate VM.

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/docs/usage.md

@@ -25,6 +25,7 @@ lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases
 | `--no-think` | Turn off the model's reasoning: faster, less accurate |
 | `--no-web` | No web search or page fetching in this session |
 | `--no-mcp` | Don't start [MCP servers](mcp.md) in this session |
+| `--sandbox` | Run shell commands in a container that only sees the project ([Sandbox](sandbox.md)) |
 | `--show-thinking` | Print the model's reasoning as it streams |
 | `-V, --version` | Print the version |
 
@@ -55,6 +56,7 @@ reasoning is on.
 | `/undo` | Undo the file changes of the last request ([details](#undo-and-checkpoints)) |
 | `/rewind [N]` | Go back to before request N: its files, and optionally the conversation |
 | `/checkpoints` | List the requests that changed files, and which files |
+| `/sandbox [network on\|off]` | The [sandbox](sandbox.md) for shell commands |
 | `/mcp [tools\|login\|restart NAME]` | [MCP servers](mcp.md), their status and tools |
 | `/compact [focus]` | Summarize the conversation to free context |
 | `/context [size]` | Show how full the context window is and change its size: pick from a list with memory estimates, or give a size like `/context 128k` (`/ctx` is a shortcut) |
@@ -84,6 +86,34 @@ reasoning is on.
 lcode refuses to edit a file the model hasn't read in the session, or one that changed on disk since
 it was read, so the model always edits the current version.
 
+## Images
+
+lcode can look at screenshots, mockups, diagrams and photos:
+
+```text
+❯ the layout breaks on mobile, see @screenshots/mobile.png
+❯ make the settings page match @design/settings.png
+```
+
+- Attach an image with `@path`, like a file. lcode describes it in detail, with all visible text
+  transcribed and with your question in mind, and the model works from that description.
+- The model can open images itself with the `view_image` tool, for example a screenshot a test wrote.
+- Screenshots that [MCP](mcp.md) tools return, such as the Playwright browser's, are described too.
+
+**Which model looks.** lcode's text-only model variants leave out the vision part to save GPU
+memory, so lcode borrows the original model, which `lcode setup` already downloaded (for example
+`qwen3.6:35b-a3b-coding` for `qwen3.6-35b`). If your model can see, it looks itself. `lcode doctor`
+shows which one is used. With another model, install one that can see and point lcode to it:
+
+```bash
+ollama pull qwen3-vl:8b
+lcode config set vision_model qwen3-vl:8b
+```
+
+Loading a second model takes a moment: on a 12 GB GPU, describing an image with the original
+`qwen3.6:35b-a3b-coding` takes about a minute, and the next request reloads the main model. Turn
+image support off with `lcode config set vision_model off`.
+
 ## Permissions
 
 | Mode | File edits | Shell commands |
@@ -101,8 +131,12 @@ or ++n++. Text after ++n++ goes to the model as instructions: `n run the tests w
 
 !!! warning "yolo mode"
 
-    In `yolo` mode the model can run any command as your user. Use it in a container, a VM or a
-    throwaway clone, not on a machine with data you care about.
+    In `yolo` mode the model can run any command as your user. Use it with the
+    [sandbox](sandbox.md), in a VM or in a throwaway clone, not on a machine with data you care
+    about.
+
+With the [sandbox](sandbox.md) on, `auto-edit` mode runs shell commands without asking too: they can
+only reach the project, and `/undo` can take their changes back.
 
 ## Undo and checkpoints
 

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/mkdocs.yml

@@ -95,6 +95,7 @@ nav:
       - Models & context windows: models.md
       - Benchmarking models: bench.md
       - MCP servers: mcp.md
+      - Sandbox: sandbox.md
       - Configuration: configuration.md
   - Reference:
       - How it works: how-it-works.md

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/src/lcode/__init__.py

@@ -1,3 +1,3 @@
 """lcode — a local-first terminal coding agent powered by open-weight models via Ollama."""
 
-__version__ = "0.4.1"
+__version__ = "0.6.0"

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/src/lcode/agent.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import base64
 import datetime as dt
 import json
 import platform
@@ -19,18 +20,21 @@ from rich.markup import escape
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog, limits, sessions, web
+from lcode import catalog, limits, sessions, vision, web
 from lcode.checkpoints import Checkpoints
 from lcode.config import format_tokens
 from lcode.mcp import McpManager
 from lcode.ollama import Ollama, OllamaError
 from lcode.permissions import Permissions
 from lcode.render import MarkdownStreamer
+from lcode.sandbox import Sandbox, SandboxError, project_root
 from lcode.tools import (
     SCHEMAS,
+    VIEW_IMAGE_SCHEMA,
     WEB_FETCH_SCHEMA,
     WEB_SEARCH_SCHEMA,
     Toolbox,
+    ToolError,
     is_binary,
     parse_text_tool_calls,
     tree,
@@ -140,6 +144,10 @@ class Settings:
     search_backend: str = "auto"
     searxng_url: str | None = None
     checkpoints: bool = True  # snapshot files before the model changes them, for /undo
+    sandbox: str = "off"  # off, docker or podman: where the model's shell commands run
+    sandbox_image: str | None = None
+    sandbox_network: bool = False
+    vision_model: str = "auto"  # auto, off or an Ollama model that can see images
 
 
 class Agent:
@@ -153,7 +161,13 @@ class Agent:
         self.session_id = self.new_session_id()
         self.checkpoints = Checkpoints(self.console, settings.checkpoints)
         self.mcp: McpManager | None = None  # set by the CLI when MCP servers are configured
+        self.sandbox = (
+            Sandbox(settings.sandbox, settings.sandbox_image, settings.sandbox_network, self.console)
+            if settings.sandbox != "off"
+            else None
+        )
         self._mcp_prompt = ""  # the MCP part at the end of the system prompt
+        self._vision: str | bool | None = False  # the model that looks at images; False = not decided yet
         self.session_name = ""
         self.session_title = ""
         self.ctx_used = 0
@@ -195,10 +209,65 @@ class Agent:
         schemas = list(SCHEMAS)
         if self.settings.web != "off":
             schemas += [*([WEB_SEARCH_SCHEMA] if self.search_backend() else []), WEB_FETCH_SCHEMA]
+        if self.vision_model():
+            schemas.append(VIEW_IMAGE_SCHEMA)
         if self.mcp:
             schemas += self.mcp.schemas(self.settings.context)
         return schemas
 
+    def vision_model(self) -> str | None:
+        """The model that looks at images for this session, if any (see lcode.vision)."""
+        if self._vision is False:
+            self._vision = vision.pick_model(self.ollama, self.settings.model, self.settings.vision_model)
+        return self._vision or None
+
+    def free_gpu(self) -> list[str]:
+        """Unload lcode's models from Ollama so another program can use the GPU; the next request reloads.
+
+        Only lcode's own models: the session's and the one that looks at images.
+        """
+        mine = {self.settings.model, *([self._vision] if isinstance(self._vision, str) else [])}
+        freed = []
+        for entry in self.ollama.running():
+            name = entry.get("name") or entry.get("model") or ""
+            if name in mine or name.removesuffix(":latest") in mine:
+                try:
+                    self.ollama.unload(name)
+                    freed.append(name.removesuffix(":latest"))
+                except OllamaError:
+                    pass
+        return freed
+
+    def look(self, path: Path, question: str = "") -> str:
+        """Describe an image with the vision model. Raises ToolError if it can't."""
+        model = self.vision_model()
+        if not model:
+            raise ToolError(f"can't look at {path.name}: {vision.INSTALL_HINT}")
+        try:
+            image = vision.read_image(path)
+            # The session's own model keeps its settings, so Ollama doesn't reload it.
+            options = self.options() if model == self.settings.model else None
+            loading = "" if model == self.settings.model else " (loads it; the next request reloads the main model)"
+            with self.console.status(f"Looking at {path.name} with {model}{loading}…", spinner="dots"):
+                return vision.describe(self.ollama, model, image, question, options, self.settings.keep_alive)
+        except vision.VisionError as e:
+            raise ToolError(str(e)) from e
+
+    def describe_image_data(self, data: str, mime: str) -> str:
+        """For images that tools return (e.g. an MCP browser's screenshots): a description, or a note."""
+        model = self.vision_model()
+        if not model:
+            return f"[{mime} image not shown: {vision.INSTALL_HINT}]"
+        options = self.options() if model == self.settings.model else None
+        try:
+            with self.console.status(f"Looking at the {mime} image with {model}…", spinner="dots"):
+                text = vision.describe(
+                    self.ollama, model, base64.b64decode(data), "", options, self.settings.keep_alive
+                )
+        except (vision.VisionError, ValueError) as e:
+            return f"[{mime} image not shown: {e}]"
+        return f"[{mime} image, as described by {model}]\n{text}"
+
     def prepare_mcp(self) -> None:
         """Before a request: wait for MCP servers still starting and describe them in the system prompt."""
         if not self.mcp:
@@ -462,6 +531,15 @@ class Agent:
         finally:
             self.checkpoints.end_turn()
 
+    def sandbox_root(self) -> Path | None:
+        """The folder the model is limited to while the sandbox is on (None when it's off)."""
+        if not self.sandbox:
+            return None
+        try:
+            return project_root(self.cwd)
+        except SandboxError:
+            return self.cwd
+
     def checkpoint(self) -> None:
         """Called before the model changes files: snapshot them once per request, for /undo."""
         self.checkpoints.before_change(self.cwd)
@@ -541,7 +619,17 @@ class Agent:
         attached = []
         for ref in re.findall(r"(?<!\S)@([\w./~\-]+)", text):
             p = self.tools.resolve(ref)
-            if p.is_file() and not is_binary(p) and p.stat().st_size < 200_000:
+            if p.is_file() and vision.is_image(p):
+                try:
+                    description = self.look(p, re.sub(r"(?<!\S)@[\w./~\-]+", "", text))
+                    who = f' described_by="{self.vision_model()}"'
+                except ToolError as e:
+                    description, who = f"(lcode couldn't look at this image: {e})", ""
+                    self.console.print(Text(f"  ⎿ {e}", style="yellow"))
+                else:
+                    self.console.print(Text(f"  ⎿ looked at {self.tools.rel(p)}", style="dim"))
+                attached.append(f'<image path="{self.tools.rel(p)}"{who}>\n{description}\n</image>')
+            elif p.is_file() and not is_binary(p) and p.stat().st_size < 200_000:
                 attached.append(f'<file path="{self.tools.rel(p)}">\n{p.read_text(errors="replace")}\n</file>')
                 self.tools.read_mtimes[str(p)] = p.stat().st_mtime
                 self.console.print(Text(f"  ⎿ attached {self.tools.rel(p)}", style="dim"))

{lcode_cli-0.4.1 → lcode_cli-0.6.0}/src/lcode/cli.py

@@ -273,6 +273,17 @@ def cmd_doctor(args) -> None:
         if spec:
             detail += f" · ~{spec.memory_gib(ctx):.0f} GB needed, ~{hw.budget_gib:.0f} GB available"
         line("Context", detail + (f" ({note})" if note else ""), None if note else True)
+        from lcode import vision
+
+        seer = vision.pick_model(ollama, model, cfg["vision_model"])
+        if seer:
+            line(
+                "Vision",
+                f"{seer} looks at screenshots and images" + ("" if seer == model else " (loaded when needed)"),
+                True,
+            )
+        else:
+            line("Vision", "off" if cfg["vision_model"] == "off" else vision.INSTALL_HINT, None)
         if limits.get(model):
             line(
                 "Limit",
@@ -321,6 +332,15 @@ def cmd_doctor(args) -> None:
     except ValueError as e:
         line("MCP", str(e), False)
         ok = False
+    if cfg["sandbox"] == "off":
+        line("Sandbox", "off (lcode config set sandbox docker)", True)
+    else:
+        from lcode.sandbox import engine_problem
+
+        problem = engine_problem(cfg["sandbox"])
+        network = "network on" if cfg["sandbox_network"] else "no network"
+        line("Sandbox", problem or f"{cfg['sandbox']} · {network}", problem is None)
+        ok &= problem is None
     node = shutil.which("npx")
     line("Node.js", "found" if node else "not found (some MCP servers need npx)", True if node else None)
     sys.exit(0 if ok else 1)
@@ -485,8 +505,21 @@ def cmd_chat(args) -> None:
         search_backend=cfg["search_backend"],
         searxng_url=cfg["searxng_url"],
         checkpoints=cfg["checkpoints"],
+        sandbox=(cfg["sandbox"] if cfg["sandbox"] != "off" else "docker") if args.sandbox else cfg["sandbox"],
+        sandbox_image=cfg["sandbox_image"],
+        sandbox_network=cfg["sandbox_network"],
+        vision_model=cfg["vision_model"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
+    if agent.sandbox:
+        # Never run commands unsandboxed when the user asked for a sandbox: stop here instead.
+        from lcode.sandbox import SandboxError
+
+        try:
+            with console.status("Starting the sandbox…"):
+                agent.sandbox.ensure(cwd)
+        except SandboxError as e:
+            fail(f"the sandbox can't start: {e}\nTurn it off with: lcode config set sandbox off")
     if not args.no_mcp:
         from lcode.mcp.commands import start_session
 
@@ -496,6 +529,8 @@ def cmd_chat(args) -> None:
     finally:
         if agent.mcp:
             agent.mcp.close()
+        if agent.sandbox:
+            agent.sandbox.stop()
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -522,6 +557,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--no-think", action="store_true", help="disable model reasoning (faster, less accurate)")
     parser.add_argument("--no-web", action="store_true", help="don't let the model search or fetch web pages")
     parser.add_argument("--no-mcp", action="store_true", help="don't start MCP servers in this session")
+    parser.add_argument("--sandbox", action="store_true", help="run shell commands in a container (Docker or Podman)")
     parser.add_argument("--show-thinking", action="store_true", help="print the model's reasoning as it streams")
     parser.add_argument("-V", "--version", action="version", version=f"lcode {__version__}")
     return parser