opensquilla--opensquilla/README.product.md

OpenSquilla Product Guide

OpenSquilla is a token-efficient personal agent runtime for the terminal, a local Web UI, and messaging channels. It is designed for users who want one agent surface that can chat, use tools, remember useful context, run scheduled work, publish artifacts, and route work across multiple LLM providers without rewriting their workflow for each provider.

This guide is the product and usage entry point. The existing README.md remains the package/release README.

Start Here

1. Install OpenSquilla:

   uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc3/opensquilla-0.5.0rc3-py3-none-any.whl"
   

2. Configure your provider:

   opensquilla onboard
   

3. Start the gateway:

   opensquilla gateway run
   

4. Open the control UI:

   http://127.0.0.1:18791/control/

For platform-specific install paths and recovery steps, see docs/quickstart.md.

Why OpenSquilla

OpenSquilla focuses on cost-per-success and long-running usefulness rather than single-turn chat alone.

Product capability	What users get
SquillaRouter	Local, on-device routing that chooses an appropriate model tier per turn so simple tasks avoid premium-model cost.
Tool compression	Large tool outputs stay useful without flooding the model context; raw results can be preserved while compact previews are sent to the model.
Meta-skills	Repeatable workflows can be packaged as composable skills, so users can turn recurring multi-step work into reusable agent routines.
Unified surfaces	CLI, Web UI, gateway RPC, and channels share the same runtime path, tools, memory, approvals, and usage accounting.
Durable sessions	Conversations, transcripts, compaction summaries, artifacts, cost, and replay data are persisted for later inspection.
Personal memory	User facts, notes, and task traces can be saved and recalled through local keyword and semantic search.
Multi-provider runtime	OpenRouter, OpenAI, Anthropic, Gemini, DeepSeek, DashScope, Ollama, and other provider-compatible backends can be configured through one schema.
Safe tool use	File, shell, web, memory, git, artifact, media, channel, and agent tools run behind policy layers and approval surfaces.

Documentation Map

Need	Read
Install and run OpenSquilla	docs/quickstart.md
Choose the right workflow for a goal	docs/use-cases.md
Start, stop, expose, or troubleshoot the gateway	docs/gateway.md
Configure providers, router, search, channels, memory, and permissions	docs/configuration.md
Learn the CLI command groups	docs/cli.md
Use the local control console	docs/web-ui.md
Resume, export, abort, or delete sessions	docs/sessions.md
Choose and inspect LLM providers/models	docs/providers-and-models.md
Configure web search	docs/search.md
Understand the main product capabilities	docs/features.md
Use SquillaRouter	docs/features/squilla-router.md
Understand tool compression and tool-result handles	docs/features/tool-compression.md
Use MetaSkills	docs/features/meta-skills.md
Work with memory	docs/features/memory.md
Work with skills	docs/features/skills.md
Understand compaction, cache, and long-session continuity	docs/features/compaction-and-cache.md
Publish artifacts and use media features	docs/artifacts-and-media.md
Connect chat channels	docs/channels.md
Create durable named agents	docs/agents.md
Schedule recurring or one-time work	docs/scheduling.md
Understand tools, sandboxing, and approvals	docs/tools-and-sandbox.md
Choose permissions and approval posture	docs/approvals-and-permissions.md
Inspect usage and model cost	docs/usage-and-cost.md
Diagnose and replay a turn	docs/diagnostics-and-replay.md
Connect MCP-capable clients	docs/mcp-server.md
Run sessions, cron, diagnostics, migration, and MCP operations	docs/operations.md
Fix common install/runtime problems	docs/troubleshooting.md
Understand OpenSquilla terminology	docs/glossary.md

The Fastest Useful Workflow

After the gateway is running, use the surface that fits the job:

opensquilla chat

Use this for interactive terminal work.

opensquilla agent -m "Summarize this repo and tell me what to test"

Use this for one-shot automation.

opensquilla gateway start --json

Use this for background Web UI, channels, and RPC clients.

opensquilla sessions list
opensquilla cost
opensquilla doctor

Use these to inspect history, cost, and readiness.

Configuration Essentials

OpenSquilla loads configuration in this order:

1. OPENSQUILLA_GATEWAY_CONFIG_PATH
2. ./opensquilla.toml
3. ~/.opensquilla/config.toml
4. built-in defaults

Use the CLI for routine changes:

opensquilla onboard --if-needed
opensquilla configure provider --provider openrouter --api-key-env OPENROUTER_API_KEY
opensquilla configure router --router recommended
opensquilla configure search --search-provider duckduckgo
opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY
opensquilla configure channels
opensquilla config get llm.provider
opensquilla config set gateway.port 18791

See docs/configuration.md for details.

Feature Highlights

SquillaRouter

SquillaRouter is OpenSquilla's local routing layer. It keeps lightweight tasks on cheaper models and reserves stronger tiers for harder turns. Router decisions stay local; the user's prompt is not sent to a separate external classifier just to decide the model.

Read: docs/features/squilla-router.md

Tool Compression

Agent work often creates huge tool results: logs, web pages, search results, spreadsheets, diffs, and JSON. OpenSquilla can keep the raw result available while projecting a compact model-visible preview, reducing context pressure without throwing away the user's working state.

Read: docs/features/tool-compression.md

Meta-Skills

Meta-skills let OpenSquilla present higher-level workflows instead of making the user re-describe the same multi-step process. They are useful for repeatable research reports, document-to-decision work, daily operating briefs, account watching, job-search preparation, kid project planning, academic paper drafting, and MetaSkill proposal creation.

By default, launch them deliberately with /meta and /meta <name>.

Read: docs/features/meta-skills.md, docs/features/meta-skill-user-guide.md, and docs/authoring/meta-skills.md

What OpenSquilla Can Do

• Run chat from Web UI, CLI, gateway RPC, terminal channels, and supported messaging platforms.
• Use tools for files, shell commands, code execution, git, web search/fetch, memory, sessions, artifacts, media, Feishu, scheduled jobs, and subagents.
• Install, inspect, publish, and compose skills.
• Schedule recurring runs with opensquilla cron.
• Save durable memory and search previous sessions.
• Track usage and estimated cost with opensquilla cost.
• Diagnose readiness with opensquilla doctor and /control/ health views.
• Export reproducible install state with opensquilla dist.
• Remove OpenSquilla cleanly with opensquilla uninstall — keeps your data unless you pass --purge-state / --purge-config / --purge-all.
• Bridge OpenSquilla into MCP-capable clients with opensquilla mcp-server run when the mcp extra is installed.
• Create and deliver artifacts such as HTML files, PDF reports, slides, spreadsheets, generated images, and channel-delivered files.

Safety Defaults

The gateway binds to 127.0.0.1 by default. Binding to public interfaces is opt-in:

opensquilla gateway run --listen 0.0.0.0 --port 18791

Do not expose a public gateway without token auth and a network boundary you trust. For tool behavior, approval flow, and workspace containment, see docs/tools-and-sandbox.md.

Existing Reference Docs

• README.md - release/package README
• MIGRATION.md - migration from OpenClaw and Hermes Agent
• docs/features/meta-skill-user-guide.md - MetaSkill user guide
• docs/authoring/meta-skills.md - MetaSkill authoring guide
• CONTRIBUTING.md - contributor workflow
• CHANGELOG.md - release history

Improve the Documentation

OpenSquilla documentation is part of the product. If a setup step is confusing, a command is stale, or a feature guide needs a clearer example, open a small pull request against main. Existing dev pull requests may continue during the branch transition.

Read docs/contributing-docs.md for docs-specific guidance.

---

Docs index · Improve these docs · Report a docs issue · Contributing