A privacy-first Python workbench for running an AI agent with local language models. Local Agent combines a transparent tool-calling loop, persistent SQLite memory, reusable skills, managed project workspaces, and optional media tools without requiring a hosted LLM account.
Portfolio release: the core workflow runs locally, the complete offline test suite needs no model or API key, and potentially dangerous execution tools are disabled by default.
- A model-agnostic agent loop that parses tool calls, executes them, returns observations, and stops safely
- Persistent facts and conversation history backed by SQLite
- Reusable Markdown/YAML skills loaded into the model context
- Project manifests with goals, tasks, status, and isolated storage
- Workspace-confined file operations with traversal protection
- Ollama integration for local open-weight models
- A deterministic mock backend for testing without a GPU, network, or model download
- Optional web research, image generation, text-to-speech, and video assembly
- Cross-platform Python packaging and automated CI on Python 3.10–3.12
Local Agent is intentionally conservative by default:
- File tools can access only the managed workspace under
LOCAL_AGENT_HOME. - Absolute paths and
..traversal outside that workspace are rejected. - Project names are validated and projects remain inside managed storage.
- Python and shell execution are disabled unless the operator explicitly sets
LOCAL_AGENT_ALLOW_EXECUTION=1. - Tool loops, output size, and execution time have hard limits.
- Runtime memory, workspaces, media, logs, and local configuration are excluded from Git.
Local execution remains powerful after it is enabled. Review generated commands and use a dedicated workspace for important tasks. See SECURITY.md.
Requirements: Python 3.10+ and, for real-model chat, Ollama.
git clone https://github.com/alphapoptart/local_agent.git
cd local_agent
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
python -m pip install -e .
python selftest.pyThe smoke test proves memory, managed files, projects, skills, and the safe execution default without downloading a model.
LOCAL_AGENT_LLM=mock local-agentWindows PowerShell:
$env:LOCAL_AGENT_LLM = "mock"
local-agentThe mock backend is deterministic and intended for evaluation, demos, and CI—not general conversation.
LOCAL_AGENT_LLM=mock local-agent webOpen http://127.0.0.1:8765. The responsive interface includes chat, runtime and safety status, persistent memory, project tracking, suggested evaluation prompts, and visible local-processing feedback. The server binds only to the local computer.
ollama pull llama3.1:8b
local-agentChoose another installed model with LOCAL_AGENT_MODEL, or point OLLAMA_HOST at another Ollama-compatible endpoint.
Chat normally, or use the optional shortcuts:
/remember <key> <value>
/recall
/skills
/projects
/project <name>
/clear
/exit
Core tools include:
| Area | Tools | Default behavior |
|---|---|---|
| Memory | remember, recall |
Stored locally in SQLite |
| Files | write_file, read_file |
Confined to the managed workspace |
| Projects | project_create, project_plan, project_status |
Confined to managed project storage |
| Skills | save_skill, list_skills, delete_skill |
Stored locally |
| Research | web_search, web_fetch |
Uses network access when invoked |
| Media | image, TTS, and video tools | Optional local or keyless services |
| Execution | run_code, terminal |
Disabled until explicitly enabled |
Only enable execution in an environment where you are comfortable running model-generated code:
LOCAL_AGENT_ALLOW_EXECUTION=1 local-agentExecution calls are still time-limited and output-limited, but this is not an operating-system sandbox.
| Variable | Default | Purpose |
|---|---|---|
LOCAL_AGENT_LLM |
ollama |
ollama or deterministic mock backend |
LOCAL_AGENT_MODEL |
llama3.1:8b |
Ollama model name |
OLLAMA_HOST |
http://localhost:11434 |
Ollama endpoint |
LOCAL_AGENT_HOME |
~/local_agent_data |
Memory, projects, outputs, skills, and workspace |
LOCAL_AGENT_ALLOW_EXECUTION |
disabled | Explicitly enables Python and shell tools |
STABLE_DIFFUSION_API |
unset | Optional local image-generation endpoint |
EDGE_TTS_VOICE |
en-US-AriaNeural |
Optional narration voice |
User request
│
▼
Agent loop ─────► Model backend (Ollama or deterministic mock)
│ │
│ tool call ◄───────┘
▼
Tool registry
├── memory ──────────────► SQLite
├── skills ──────────────► managed skill files
├── projects ────────────► managed project manifests
├── files ───────────────► confined workspace
├── research/media ──────► optional network/local services
└── execution ───────────► explicit opt-in only
The implementation is deliberately small enough to audit:
local_agent/
├── agent.py tool-calling loop and result feedback
├── config.py environment configuration and workspace policy
├── llm.py Ollama and deterministic mock backends
├── memory.py SQLite persistence
├── projects.py project manifests and task tracking
├── skills.py reusable skill storage
├── web.py responsive local web application
└── tools/
├── __init__.py registry and tool metadata
└── builtins.py research, media, execution, file, and state tools
Run the complete standard-library suite:
python -m unittest discover -s tests -v
python selftest.pyThe suite covers both accepted tool schemas, malformed Windows-style escapes, multiple tool calls, memory persistence, skills, project lifecycle, workspace file isolation, path traversal rejection, safe execution defaults, explicit execution opt-in, callbacks, and an end-to-end mock tool loop.
GitHub Actions runs the same checks on Python 3.10, 3.11, and 3.12.
- Model quality and tool-selection reliability depend on the local model.
- The JSON tool protocol is intentionally simple and educational rather than a replacement for a production agent SDK.
- Optional keyless media providers can change or become unavailable; local backends are preferable for repeatability and privacy.
- Shell execution is intentionally opt-in and is not an OS-level sandbox.
- The project is a local CLI workbench; it does not expose an authenticated multi-user service.
