vbookshelf/W2H-Basic-Agent-Loop-w-Sandbox

W2H Basic Agent Loop with built in Linux Sandbox

A lightweight home agent that talks, runs code and takes actions in the real world. Access it from anywhere.

This is a vanilla Python agent loop that supports tools, skills, a microVM sandbox, encrypted data-in-transit and the Arduino microcontroller. The web UI includes voice, file uploads and slash commands. Designed for learning and experimentation. Use vibe coding to adapt it for different tasks.

Talk to the agent from anywhere using a web based chat interface that you host on an ordinary shared web hosting platform. No third party connection services needed. The connection is made using polling based remote access. It creates a secure bridge between your web UI and your local AI agent - without exposing your home network to the internet.

Setting up a website for remote access is a bit more work, but in return you get control and data privacy.

To understand how everything works, please pass a link to this page and the following files to a frontier LLM like Claude Sonnet, Gemini or ChatGPT and ask it to explain.<br> Prompt: ``Please explain what this project is and how it works``

• —w2h-ollama.py
• —w2h-openrouter.py
• —api.php
• —index.php
• —control-panel.php

Tech stack:<br> Python + Html + CSS + JS + PHP<br> Ollama model: ``qwen3.5:9b (Q4_K_M, 6.6GB)`<br> OpenRouter Model: `qwen3.5-flash ($0.065/0.26 per 1M)``

<img src="images/image5.png" alt="Screenshot" width="300"> <p>Mobile web UI</p>

<br>

<img src="images/image2.png" alt="Screenshot" height="500"> <p>Slash commands</p>

<br>

<img src="images/image3.png" alt="Screenshot" height="500"> <p>Hardware control panel</p>

<br>

<img src="images/image4.jpg" alt="Mac and Arduino" width="400"> <p>Arduino</p>

Quick Info

• —The agent loop runs locally on your mac
• —The setup supports both Ollama and Openrouter - selected by running the appropriate Python file.
• —You interact with the agent via a relay website that you host on a cheap web hosting platform.
• —Access to the website is controlled using a simple token system.
• —The website relays commands using a polling mechanism.
• —Third party relay/tunneling apps are not required.
• —Files and chat messages are encrypted in transit - the web server cannot read the data that it relays.
• —You will need to enter an encryption key when you first access the website. This key is also in the Python code that runs on your local server.
• —The agent has a built-in Linux sandbox where it can run shell commands, write and run code etc.
• —The Agent has a workspace folder. It can only see and manipulate files that are inside the workspace folder.
• —The agent cannot see anything outside the sandbox.
• —The agent has tools.
• —The agent supports skills.
• —The agent can send and receive images.
• —Supports voice input and output.
• —The agent has access to a set of Linux Python packages (e.g. Pandas, Matplotlib) that it can use in it's workspace.
• —The agent is able to save files to a W2H-Archive folder thats located on the Desktop. This prevents it from mistakenly deleting work that it has completed.
• —The W2H-Archive folder can also be located inside a folder that auto syncs to your Google Drive.
• —An Arduino can be connected to your computer. This gives your computer I/O (input/output) pins that the agent can use to interact with the real world. Switch on a light or launch a rocket - all that's needed is a signal sent from your computer to an I/O pin on the Arduino.
• —Remotely control devices connected to the Arduino via a control panel on the website.
• —Issue slash commands via the chat - e.g. ``/ls_workspace`` will respond with a list of all files and folders that are currently in the workspace folder. Slash commands are executed by the Python code, not by the LLM. The output appears in the chat.

<br>

How to run this system

• —Required: macOS
• —Required: Apple Silicon Mac (M-Series) <br>
• —Required: uv package manager installed
• —Required: You need to have a domain or sub-domain available with a web hosting service like Dreamhost.
• —Optional: Ollama installed with the qwen3.5:9b model downloaded. (Only required if not using OpenRouter)
• —Optional: You need to know how to set up and use an Arduino micro-controller.

1- Update the config.py file

• —Download the project folder and unzip
• —Open the app/config.py file
• —Add your website url:

  # Example: WEBSITE_URL = "https://yoursite.com"
  WEBSITE_URL = "PASTE_YOUR_WEBSITE_URL"

• —Take note of ACCESSTOKEN and ENCRYPTIONKEY_B64. You will need these to log in to the website.

2- Add your OpenRouter API Key (Optional - not required if using Ollama)

• —Open the ``my-api-key.env.txt`` file and replace YOUR-API-KEY with your OpenRouter API Key.

  # Example: OPENROUTER_API_KEY=sk-or-v1-4ba9e3b...
  OPENROUTER_API_KEY=YOUR-API-KEY

• —Use the terminal to change the file name from ``my-api-key.env.txt` to `my-api-key.env``. On mac, trying to rename a .env file manually may not work.<br> Terminal: mv my-api-key.env.txt my-api-key.env

3- Set up the website

• —Upload all the files that are inside the ``web-app`` folder to your web domain. Only upload the individual files, not the web-app folder.
• —Enter the url of your website into a web browser and load your website.
• —To log in enter the access token and the encryption key that you saw in config.py. This only needs to be done the first time. This info will be saved in browser storage so that you can be auto logged in on subsequent visits.

4- Launch the python app

• —In the terminal, cd into the folder named: ``app``
• —If using Ollama, type this into the terminal:<br> uv run w2h-ollama.py
• —If using OpenRouter, type this into the terminal:<br> uv run w2h-openrouter.py
• —The app will start polling your website.

5- Chat with the agent

• —Go to your website and send a chat message. The agent should reply. When using Ollama, the first response may be delayed because the model needs to load. Subsequent responses will be faster.

6- Set up the Arduino (Optional)

• —Connect the Arduino to you mac. You may need to try plugging it into different USB ports until you find the port that matches the port defined in config.py. Alternatively, change the port specified in congfig.py.
• —There is a Arduino sketch in the folder named: ``arduino-sketch``. Upload this sketch to your Arduino.
• —Go back to the chat and ask the Agent to turn the LED on. The built in LED on the Arduino should turn on after a short wait.
• —Go to the control panel page on the website. Press the button to turn the Arduino off and on.

6- For additional security

• —Change the login token in ``config.py` and in `allowed_tokens.json``
• —Move the allowedtokens.json file to a location thats outside your website root folder. Update the path to ```allowedtokens.json`` in `api.php``
• —Generate a new encryption key and update it in config.py. The key can be generated by typing the following command into the terminal:<br> openssl rand -base64 32
• —The access token and the encryption key can be changed in the settings menu.
• —Store the ``my-api-key.env` file outside the project folder, then update the file path in `config.py``.

<br>

Notes

1- This is not an agent you use blindly. To get the most out of the agent it's important to review the code, especially the tools it has available. So, for example, if the agent says it can't see the files, you can tell it to use the runshellcommand tool to list the files in the workspace.

2- State info (led status, time, day, date) is passed to the LLM with every prompt. The gives the LLM situational awareness without it having to make tool calls to retrieve this info.

3- The included data science packages give the agent interesting capabilities. For example, try asking the agent to crop out the cat's head (cat image included) or ask it to draw a sine curve. Also try asking it the analyze the sales data csv file that's in the workspace.

4- Arduino Serial Reset Latency<br> In w2h-ollama.py and w2h-openrouter.py, the ledcontrol() function opens the serial port, sleeps for 2 seconds, writes the command, and closes the port.

ser = serial.Serial(PORT, BAUD_RATE, timeout=2)
time.sleep(2)  # wait for Arduino to reset

Why this happens: Opening a serial connection sends a DTR signal to Arduino Unos/Nanos, forcing a hardware reset. The 2-second sleep is necessary to wait for the bootloader to finish. The drawback: It adds a hard 2-second delay to every single LED command. Future fix: If you want instant LED control later on, you can disable the Arduino auto-reset by placing a 10µF capacitor between the Arduino's RESET and GND pins. You can then remove the time.sleep(2) from your Python code, and the LED will respond instantly.

5- Tool calls, tool responses and other stats are printed to the terminal. This provides a view into the inner workings of the agent.

6- Every tool call and tool response is also logged in a file named toolcalllog.jsonl. This log file is created after the agent makes the first tool call. It can be found beside the workspace folder.

References

• —W2H - Polling Based Remote Access<br> https://github.com/vbookshelf/W2H-Web-2-Home

• —Juru Lab Desktop Agent Sandbox<br> https://huggingface.co/datasets/vbookshelf/Juru-Lab-Agent-Sandbox-HYA

• —Connect Ai to the Physical World with Arduino<br> https://github.com/vbookshelf/Connect-Ai-to-the-Physical-World-with-Arduino

• —Shuru microVM sandbox<br> https://github.com/superhq-ai/shuru

• —Jai World - VRM 3D Embodied AI<br> https://huggingface.co/datasets/vbookshelf/Jai-World-VRM-3D-Embodied-AI

Revision History

Version 1.0<br> 12-Sept-2026<br> First release.

<br>