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

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

@@ -6,6 +6,18 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [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 +186,8 @@ 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.5.0...HEAD
+[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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.4.1
+Version: 0.5.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,6 +78,8 @@ 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
@@ -184,7 +186,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.5.0}/README.md

@@ -44,6 +44,8 @@ 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
@@ -150,7 +152,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.5.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.5.0}/docs/configuration.md

@@ -25,6 +25,9 @@ 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 |
 | `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 +53,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.5.0}/docs/how-it-works.md

@@ -77,6 +77,7 @@ 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 |
+| `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.5.0}/docs/quickstart.md

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

lcode_cli-0.5.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.5.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) |
@@ -101,8 +103,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.5.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.5.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.5.0"

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

@@ -26,6 +26,7 @@ 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,
     WEB_FETCH_SCHEMA,
@@ -140,6 +141,9 @@ 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
 
 
 class Agent:
@@ -153,6 +157,11 @@ 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.session_name = ""
         self.session_title = ""
@@ -462,6 +471,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)

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

@@ -321,6 +321,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 +494,20 @@ 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"],
     )
     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 +517,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 +545,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

{lcode_cli-0.4.1 → lcode_cli-0.5.0}/src/lcode/config.py

@@ -25,6 +25,7 @@ PERMISSION_MODES = ("ask", "auto-edit", "yolo")
 WEB_MODES = ("on", "ask", "off")
 SEARCH_BACKENDS = ("auto", "ollama", "brave", "tavily", "searxng")
 MCP_TOOL_MODES = ("auto", "direct", "search")
+SANDBOX_ENGINES = ("off", "docker", "podman")
 
 # key -> (default, type, help)
 SETTINGS: dict[str, tuple[object, type, str]] = {
@@ -39,6 +40,9 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "search_backend": ("auto", str, "auto | ollama | brave | tavily | searxng (keys come from environment variables)"),
     "searxng_url": (None, str, "your SearXNG instance, e.g. http://localhost:8888"),
     "checkpoints": (True, bool, "snapshot files before the model changes them, so /undo can restore them"),
+    "sandbox": ("off", str, "run the model's shell commands in a container: off | docker | podman"),
+    "sandbox_image": (None, str, "container image for the sandbox (default: lcode's, built on first use)"),
+    "sandbox_network": (False, bool, "let commands in the sandbox use the network"),
     "mcp_tools": ("auto", str, "how MCP tools reach the model: auto | direct | search (on demand, saves context)"),
 }
 ENV_OVERRIDES = {
@@ -48,6 +52,7 @@ ENV_OVERRIDES = {
     "LCODE_KEEP_ALIVE": "keep_alive",
     "OLLAMA_HOST": "ollama_host",
     "LCODE_WEB": "web",
+    "LCODE_SANDBOX": "sandbox",
 }
 
 
@@ -99,6 +104,11 @@ def coerce(key: str, value: object) -> object:
         if value not in WEB_MODES:
             raise ConfigError(f"web must be one of {', '.join(WEB_MODES)}")
         return value
+    if key == "sandbox":
+        value = {"none": "off", "false": "off", "no": "off"}.get(str(value).lower(), str(value).lower())
+        if value not in SANDBOX_ENGINES:
+            raise ConfigError(f"sandbox must be one of {', '.join(SANDBOX_ENGINES)}")
+        return value
     if key == "mcp_tools" and value not in MCP_TOOL_MODES:
         raise ConfigError(f"mcp_tools must be one of {', '.join(MCP_TOOL_MODES)}")
     if key == "search_backend" and value not in SEARCH_BACKENDS:

{lcode_cli-0.4.1 → lcode_cli-0.5.0}/src/lcode/repl.py

@@ -39,6 +39,7 @@ COMMANDS = {
     "/undo": "Undo the file changes of the last request (lcode saves a checkpoint before changing files)",
     "/rewind": "Go back to before an earlier request: its files, and optionally the conversation",
     "/checkpoints": "List the requests that changed files, and which files",
+    "/sandbox": "Shell-command sandbox: status, or /sandbox network on|off",
     "/mcp": "MCP servers and their tools: /mcp, /mcp tools NAME, /mcp login NAME, /mcp restart NAME",
     "/compact": "Summarize the conversation to free context (optional: what to focus on)",
     "/context": "Show context usage and change the window size: pick from a list, or /context 128k",
@@ -143,6 +144,11 @@ def banner(agent: Agent) -> None:
                     f"[dim]mode[/]     {agent.perms.mode} [dim](Shift+Tab to cycle)[/]\n"
                     f"[dim]web[/]      {web_status(agent)}\n"
                     + (f"[dim]mcp[/]      {escape(', '.join(agent.mcp.servers))} [dim](/mcp)[/]\n" if agent.mcp else "")
+                    + (
+                        f"[dim]sandbox[/]  {escape(agent.sandbox.describe())} [dim](/sandbox)[/]\n"
+                        if agent.sandbox
+                        else ""
+                    )
                     + "\n"
                     "[dim]/help for commands · @file to attach · Esc+Enter for a newline[/]"
                 ),
@@ -240,6 +246,31 @@ def context_command(agent: Agent, arg: str, hardware: Hardware) -> None:
     apply_context(agent, size, hardware)
 
 
+def sandbox_command(agent: Agent, arg: str) -> None:
+    c, sandbox = agent.console, agent.sandbox
+    if sandbox is None:
+        c.print(
+            "The sandbox is off: shell commands run directly on this machine. Start lcode with --sandbox, or "
+            "turn it on for every session with: lcode config set sandbox docker"
+        )
+        return
+    words = arg.split()
+    if len(words) == 2 and words[0] == "network" and words[1] in ("on", "off"):
+        sandbox.network = words[1] == "on"
+        sandbox.stop()  # the next command starts a container with the new setting
+        c.print(f"Network access in the sandbox is {words[1]} from the next command.")
+        return
+    if arg:
+        c.print("[yellow]Use /sandbox or /sandbox network on|off.[/]")
+        return
+    where = f" · container {sandbox.container}, mounting {sandbox.root}" if sandbox.container else ""
+    c.print(f"Sandbox: {escape(sandbox.describe())}{escape(where)}")
+    c.print(
+        "[dim]Shell commands run in the container and can only see this project; file tools are limited to it "
+        "too. In auto-edit mode, commands run without asking.[/]"
+    )
+
+
 def mcp_command(agent: Agent, arg: str) -> None:
     from lcode.mcp.commands import status_table
     from lcode.mcp.protocol import McpError
@@ -515,6 +546,8 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
         print_checkpoints(agent)
     elif cmd == "/mcp":
         mcp_command(agent, arg)
+    elif cmd == "/sandbox":
+        sandbox_command(agent, arg)
     elif cmd == "/compact":
         agent.compact(arg)
     elif cmd in ("/context", "/ctx"):

lcode_cli-0.5.0/src/lcode/sandbox.py

@@ -0,0 +1,204 @@
+"""An optional sandbox: the model's shell commands run in a container that only sees the project.
+
+One container per session. The project (the git repository around the working directory, or the
+working directory itself) is mounted at the same path, so paths in command output stay valid and
+lcode's file tools, which run on the host, see the same files. Commands run as the host user, with
+no network unless it's allowed, no Linux capabilities, a process limit, and nothing else from the
+host: not the home folder, not the Docker socket.
+
+The default image is built locally on first use from the Dockerfile below. Any image with bash and
+setsid (util-linux or busybox) can be used instead (`sandbox_image`).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import platform
+import secrets
+import shutil
+import subprocess
+from pathlib import Path
+
+from rich.console import Console
+
+DOCKERFILE = """\
+FROM python:3.12-slim-bookworm
+RUN apt-get update \\
+ && apt-get install -y --no-install-recommends \\
+      git curl ca-certificates build-essential ripgrep jq unzip less procps nodejs npm \\
+ && rm -rf /var/lib/apt/lists/*
+"""
+DEFAULT_IMAGE = f"lcode-sandbox:{hashlib.sha256(DOCKERFILE.encode()).hexdigest()[:12]}"
+LABEL = "dev.lcode.sandbox"
+HOME = "/tmp/lcode-home"
+ENGINES = ("docker", "podman")
+
+
+class SandboxError(Exception):
+    """The sandbox can't be used; the message says how to fix it."""
+
+
+def engine_problem(engine: str) -> str | None:
+    """Why `engine` can't run containers here, or None if it can."""
+    if not shutil.which(engine):
+        if engine == "podman":
+            return "podman isn't installed (https://podman.io/docs/installation)"
+        if platform.system() == "Darwin":
+            return "docker isn't installed: install Docker Desktop, OrbStack or colima"
+        return "docker isn't installed (https://docs.docker.com/engine/install/)"
+    try:
+        r = subprocess.run(
+            [engine, "version", "--format", "{{.Server.Version}}"], capture_output=True, text=True, timeout=20
+        )
+    except (OSError, subprocess.SubprocessError) as e:
+        return f"{engine} doesn't respond: {e}"
+    if r.returncode != 0:
+        detail = (r.stderr.strip().splitlines() or [""])[-1]
+        if "permission denied" in detail.lower():
+            return (
+                f"{engine} needs permission: add yourself to the docker group "
+                "(sudo usermod -aG docker $USER, then log in again)"
+            )
+        if platform.system() == "Darwin":
+            return f"{engine} isn't running: start Docker Desktop, OrbStack or colima ({detail})"
+        return f"{engine} isn't running: start it (sudo systemctl start {engine}) ({detail})"
+    return None
+
+
+def remove_orphans(engine: str) -> None:
+    """Remove sandboxes left behind by lcode sessions that ended without cleaning up."""
+    try:
+        r = subprocess.run(
+            [engine, "ps", "-a", "--filter", f"label={LABEL}", "--format", '{{.ID}} {{.Label "dev.lcode.pid"}}'],
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return
+    stale = []
+    for line in r.stdout.split("\n"):
+        parts = line.split()
+        if len(parts) == 2 and parts[1].isdigit() and not _alive(int(parts[1])):
+            stale.append(parts[0])
+    if stale:
+        subprocess.run([engine, "rm", "-f", *stale], capture_output=True, timeout=60)
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+class Sandbox:
+    def __init__(self, engine: str, image: str | None = None, network: bool = False, console: Console | None = None):
+        if engine not in ENGINES:
+            raise SandboxError(f"unknown sandbox {engine!r}; use docker or podman")
+        self.engine = engine
+        self.image = image or DEFAULT_IMAGE
+        self.network = network
+        self.console = console or Console()
+        self.container: str | None = None
+        self.root: Path | None = None
+
+    # -- lifecycle
+    def check(self) -> None:
+        problem = engine_problem(self.engine)
+        if problem:
+            raise SandboxError(problem)
+
+    def contains(self, path: Path) -> bool:
+        return self.root is not None and (path == self.root or self.root in path.parents)
+
+    def ensure(self, cwd: Path) -> None:
+        """Have a container running whose mounted folder includes `cwd`."""
+        if self.container and self.contains(cwd):
+            return
+        self.stop()
+        self.check()
+        remove_orphans(self.engine)
+        if self.image == DEFAULT_IMAGE:
+            self._build_default_image()
+        root = project_root(cwd)
+        name = f"lcode-sandbox-{os.getpid()}-{secrets.token_hex(3)}"
+        command = [
+            self.engine, "run", "--detach", "--init", "--name", name,
+            "--label", LABEL, "--label", f"dev.lcode.pid={os.getpid()}",
+            "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--pids-limit", "1024",
+            "--volume", f"{root}:{root}", "--workdir", str(cwd),
+            "--env", f"HOME={HOME}", "--tmpfs", f"{HOME}:exec,mode=1777",
+        ]  # fmt: skip
+        if not self.network:
+            command += ["--network", "none"]
+        if self.engine == "podman":
+            command += ["--userns", "keep-id"]  # rootless podman: files belong to the host user
+        else:
+            command += ["--user", f"{os.getuid()}:{os.getgid()}"]
+        command += [self.image, "sleep", "infinity"]
+        r = subprocess.run(command, capture_output=True, text=True, timeout=300)
+        if r.returncode != 0:
+            raise SandboxError(f"couldn't start the sandbox: {(r.stderr.strip().splitlines() or ['?'])[-1]}")
+        self.container, self.root = name, root
+
+    def _build_default_image(self) -> None:
+        exists = subprocess.run([self.engine, "image", "inspect", self.image], capture_output=True, timeout=30)
+        if exists.returncode == 0:
+            return
+        with self.console.status("Building the sandbox image (once; a minute or two)…"):
+            r = subprocess.run(
+                [self.engine, "build", "--tag", self.image, "-"],
+                input=DOCKERFILE,
+                capture_output=True,
+                text=True,
+                timeout=1800,
+            )
+        if r.returncode != 0:
+            tail = "\n".join(r.stderr.strip().splitlines()[-5:])
+            raise SandboxError(f"couldn't build the sandbox image:\n{tail}")
+
+    def exec_argv(self, cwd: Path, script: str) -> tuple[list[str], str]:
+        """The command that runs `script` with bash inside the container, and a token for kill()."""
+        assert self.container is not None
+        token = secrets.token_hex(6)
+        # Its own session, so a timeout or Ctrl+C can stop everything the command started.
+        script = f"echo $$ > /tmp/.lcode-{token}.pgid\n{script}"
+        argv = [self.engine, "exec", "--interactive", "--workdir", str(cwd), self.container]
+        return [*argv, "setsid", "--wait", "bash", "-c", script], token
+
+    def kill(self, token: str) -> None:
+        """Stop a command and everything it started (after a timeout or Ctrl+C); the container stays."""
+        if self.container:
+            pgid = f"$(cat /tmp/.lcode-{token}.pgid 2>/dev/null)"
+            subprocess.run(
+                # bash, not sh: dash's kill doesn't accept "--" before a negative (process group) id
+                [self.engine, "exec", self.container, "bash", "-c", f'[ -n "{pgid}" ] && kill -KILL -- -{pgid}'],
+                capture_output=True,
+                timeout=30,
+            )
+
+    def stop(self) -> None:
+        if self.container:
+            subprocess.run([self.engine, "rm", "--force", self.container], capture_output=True, timeout=60)
+        self.container, self.root = None, None
+
+    def describe(self) -> str:
+        image = "lcode's image" if self.image == DEFAULT_IMAGE else self.image
+        network = "network on" if self.network else "no network"
+        return f"{self.engine} · {image} · {network}"
+
+
+def project_root(cwd: Path) -> Path:
+    """The folder the sandbox mounts: the git repository around `cwd`, or `cwd` itself."""
+    from lcode.checkpoints import work_tree_for
+
+    root = work_tree_for(cwd)
+    home = Path.home().resolve()
+    if root == home or root in home.parents or root == Path("/"):
+        raise SandboxError(f"won't mount {root} into the sandbox; start lcode in a project folder")
+    return root