ENGLISH | 한국어
Local coding agents for potato PCs.
rolling-potato is a local-first coding-agent runtime for low-end and
mid-range machines. It is designed around a simple premise:
Small models need a small-model runtime, not just a smaller prompt.
| Project snapshot | |
|---|---|
| Current release | v0.53.0 |
| CLI | rpotato |
| Runtime | Rust, managed llama.cpp, GGUF |
| Primary surfaces | CLI and TUI |
| Release platforms | macOS arm64/x64, Linux arm64/x64, Windows x64 |
| User-facing language | Korean |
Install · How it works · Current capabilities · Safety model · Documentation
Small local models can be useful, but they are fragile. They need a runtime
that narrows choices, enforces policy, preserves evidence, and manages failure
modes. rolling-potato therefore owns more than model inference:
- model and backend lifecycle
- bounded repository context
- permissions, approvals, hooks, and stop gates
- durable sessions, transcripts, workflows, and evidence
- patch preview, application, and verification
- skills, plugin adapters, subagents, and teams
- token, latency, CPU, memory, disk, and benchmark monitoring
- CLI, TUI, and optional local static HTML reporting
- Korean final-response validation
The CLI and TUI are user surfaces. Session state, tool permissions, context, the agent loop, and verification remain runtime-core responsibilities.
The first audience is:
- Korean-speaking developers
- users who find subscription coding agents expensive
- users with 16 GB RAM class low-end or mid-range laptops
- users who want code and model execution to remain local
- users who want local coding help without first mastering local LLM tooling
The long-term target is a practical local alternative to Claude Code/Codex, not a thin wrapper that imitates them with a weaker model.
Official binaries are distributed only through
GitHub Releases.
Download the archive for your platform and verify it with the matching
.sha256 file or the aggregate checksum file. Homebrew, Scoop, winget, and
other package-manager channels are not operated by this project.
Starting with v0.42.0, run the extracted binary once to place it
in the user-local CLI directory and register that directory in the detected
shell profile or Windows user PATH:
./rpotato install
# Open a new terminal, then:
rpotato initOn Windows, use .\rpotato.exe install, then run
& "$env:LOCALAPPDATA\Programs\rpotato\bin\rpotato.exe" init. A new terminal
picks up the persistent PATH automatically; both commands print the one-line
activation command for the current terminal. RPOTATO_* variables remain
optional overrides and are not forced globally.
From v0.44.0, the TUI checks this repository's latest stable GitHub Release
at startup. A short timeout and six-hour cache keep an offline or slow network
from blocking startup. When a newer version exists, use /update in the TUI or
the equivalent CLI commands:
rpotato update --check
rpotato updateSelf-update is limited to the managed user-local installation. It downloads
only the exact archive for the current supported platform, verifies the
matching .sha256 sidecar, and then replaces the installed binary. On Windows,
replacement completes after the current process exits.
For a reset that removes the global application data and only the current
project's .rpotato state, inspect and then explicitly confirm the clean
install:
./rpotato install --clean --dry-run
./rpotato install --clean --yesClean install is blocked while a managed backend or generation is active. Its dry-run also reports whether the binary and PATH registration would be created, updated, or left unchanged. Runtime publication and deletion share a cross-process guard; an unavailable process-liveness check blocks deletion.
To remove the program and all runtime-managed state, inspect the exact scope and then confirm it explicitly:
rpotato uninstall --clean --dry-run
rpotato uninstall --clean --yesClean uninstall removes the installed binary, the PATH block owned by
rpotato, global application data, and the current project's .rpotato.
User-owned files such as the extracted source binary and source repositories
are preserved. On Windows, self-removal of the installed binary completes
immediately after the current process exits.
Supported release targets and checksum verification are documented in docs/release.md.
The intended local setup flow is:
- Run
rpotato. - Review the model/version, quantization, download size, context, RAM status, license, and source evidence shown by first-run setup.
- Select a model with Up/Down and Enter, then approve its download from the second selectable prompt.
- Let
rpotatoinstall or reuse its managedllama.cppbackend, verify the artifact size and SHA-256, and start the model. - Enter a coding request in the same TUI.
Model weights are not bundled with rpotato. A global llama.cpp
installation is not required on the managed path.
Start the product with:
rpotatoRunning rpotato without arguments starts the primary TUI. Plain text entered
there supports both general LLM questions and coding-agent requests. For each
request, the local model decides whether current public evidence requires the
bounded read-only WebSearch, WebOpen, or WebFind tool; this is not driven by
a fixed keyword list. /search <question> remains an explicit fallback. Direct
HTML search uses runtime-rendered source links and needs no API key, MCP process,
or provider SDK. /open <URL> opens a bounded public HTTPS
document and /find <text> searches the last document opened in the current TUI.
Only same-host redirects are followed automatically; a cross-host redirect is
reported and requires a new explicit /open. /doctor reports whether the
repo-owned web tools are ready.
The v0.50.0 release also supports a restricted browser search-form route
for explicit requests such as “open Naver and search for …”. There is no manual
/browser command: the agent chooses the typed tool, with a narrow deterministic
fallback for small models. The runtime discovers a generic accessibility search
field instead of using site-specific selectors or page JavaScript, types only the
bounded search query, submits it, and returns the verified public result URL and
bounded page text. It starts an installed Chromium-family browser with a fresh
temporary profile, never reuses existing cookies or logins, and forces public
HTTPS port 443 traffic through a loopback CONNECT proxy that resolves and pins a
public address before connecting. Login, payment, posting, upload, download,
personal-data entry, and project or attachment submission are outside this route.
An explicit offline/no-browse instruction disables both static and browser
retrieval.
The line below the composer shows the current
model, context usage, compaction checkpoint, backend state, and session.
Normal TUI operations use /model, /compact, /search, /open, /find, /attach, /update,
/status, /sessions, /doctor, /more, /back, /clear, /help, and /quit.
The slash palette and model picker support Up/Down, Enter, Esc, and numbered
plain-terminal fallback. The composer supports standard Home/End and Ctrl bindings,
Option/Alt word movement, and Command/Meta line movement when emitted by the terminal.
Long responses remain
available through /more and /back instead of being discarded at the viewport
boundary. Context compaction starts automatically at 75% usage; /compact
creates a manual checkpoint while preserving the immutable transcript as the
authority.
Pasted local image/text paths are captured as attachment badges rather than parsed
as slash commands. Bounded UTF-8 text/code attachments are included in the next
request only while they fit the selected model's manifest context limit. PNG and
JPEG attachments are available when the selected model has a
verified vision projector. rpotato downloads that model-specific mmproj
artifact with the main GGUF, verifies both files independently, and starts
llama-server with --mmproj. A verified cached projector is reused without
downloading it again. A missing, corrupt, or failed projector leaves the previous
model and backend selection unchanged, and a partial download remains resumable.
The smaller public CLI surface is:
rpotato doctor
rpotato init
rpotato run "이 저장소의 테스트 실패 원인을 찾아줘"
rpotato debug --helprpotato debug --help lists granular compatibility and diagnostic commands;
normal setup does not require a backend executable or GGUF path.
The detailed MVP acceptance criteria are in docs/mvp.md.
The v0.53.0 release is an active pre-1.0 runtime, not only a
product-definition scaffold. Implemented areas include:
| Area | Current surface |
|---|---|
| Agent loop | Bounded context, JSON-schema turn decisions, runtime-owned tool observations, typed model actions, and guarded Korean reporting |
| Durable state | Sessions, transcripts, workflows, ledgers, evidence, resume and continue |
| Patch workflow | Preview, explicit apply approval, separate verification approval, rollback records |
| Backend and models | Managed sidecar lifecycle, source-backed candidates, local promotion/install gate |
| Extensions | Native hooks and skills; local Codex/Claude Code plugin adapters |
| Collaboration | One bounded subagent and runtime-owned team execution |
| Monitoring | CLI/TUI metrics, SQLite projection, benchmark records, static HTML export |
| Interfaces | Primary conversation TUI, keyboard pickers, local attachment badges, automation/diagnostic CLI, self-contained local HTML report |
| General answers and web | General knowledge/calculation answers, model-selected API-key-free WebSearch, WebOpen, and WebFind, explicit no-browse control, and runtime-owned source links |
The v0.50.0 release adds agent-selected restricted browser search-form research
without granting general browser automation. See the
v0.50 web research and browser plan.
The v0.52.0 release makes WebSearch, WebOpen, and WebFind follow one
runtime-owned ToolCall → Observation → Answer contract instead of exposing
small-model free-form tool text.
The v0.52.1 patch restores the default conversation path on the managed
llama.cpp backend by keeping JSON-schema repetition bounds within the pinned
grammar compiler's verified limits.
The v0.53.0 release makes volatile questions enter a generic, runtime-owned
grounding path before a small model can answer from stale memory, and splits
the runtime, TUI, persistence, model, web, and test responsibilities into
bounded owners without changing the public command surface.
See docs/current-capabilities.md for the
chaptered capability map, representative commands, and known incomplete
boundaries. Use rpotato --help and subcommand help for the exact command
syntax of the installed version.
The runtime treats model output as untrusted input. Model text never executes tools directly. Every supported side effect must pass runtime policy, approval where required, evidence recording, and verification.
Key constraints:
- user-facing natural-language output defaults to Korean; an explicit request for another language is respected, and language-neutral numbers and formulas remain valid
- code blocks, paths, commands, and quoted logs remain unchanged when needed
- mixed-language final output gets one Korean rewrite attempt, then preserves valid Korean lines through safe projection and falls back to the non-empty visible answer instead of hiding it; only empty/hidden output is blocked
- imported plugin instructions cannot widen runtime permissions
- web evidence and browser page content remain untrusted data; the restricted browser route uses a temporary profile, public-HTTPS-only address-pinned proxy, and an anonymous search-form action instead of an authenticated user session
- shell, background, remote-connector, sensitive-setting, and write capabilities remain blocked unless a supported policy path allows them
- uncertain backend requests or verification commands are not replayed automatically after recovery
- model, license, performance, memory, and compatibility claims require recorded sources or local evidence
Architecture details:
Qwen and Gemma entries are evaluation candidates, not assumed defaults.
llama.cpp is a backend, not a model candidate. See
model sources,
model licenses, and
local evaluation.
The published release history through v0.53.0 includes bounded web research,
restricted browser search-form support, a reliable interactive TUI, and
grounded conversation continuity across follow-ups and resumed sessions. Web
tools use schema-constrained turn decisions, generic freshness routing, and
runtime-owned observations while preserving the local coding-agent workflow.
See
ROADMAP.md and the
v0.50 delivery plan.
Use the documentation index to browse by topic.
| Start with | Purpose |
|---|---|
| PLAN.md | Product intent, target users, and product shape |
| ROADMAP.md | Version-only release history and next-version rule |
| DESIGN.md | CLI, TUI, and monitoring UX source of truth |
| Current capabilities | Implemented areas, entry points, and known boundaries |
| Development | Local development and verification workflow |
| Release | Version, branch, artifact, and publication policy |
Korean documentation is available through README.ko.md and the Korean documentation index.
This is a public Apache-2.0 open-source repository, but external code contributions and external PRs are not currently accepted. Bug reports, usability feedback, security reports, and model/license evidence may be accepted.
See GOVERNANCE.md, SECURITY.md, and PRIVACY.md.