wehub-resource-sync
230 lines
5.1 KiB
Markdown
230 lines
5.1 KiB
Markdown
# Quickstart
|
|
|
|
This guide gets OpenSquilla installed, configured, and running locally. It
|
|
assumes you want the standard product experience: terminal commands, local Web
|
|
UI, SquillaRouter, memory/search support, and safe local defaults.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.12 or newer for terminal installs.
|
|
- `uv` for the recommended terminal install.
|
|
- Git and Git LFS only when installing from source.
|
|
- A provider API key unless you use a local provider such as Ollama.
|
|
|
|
## Recommended Install
|
|
|
|
Install the current release wheel with the recommended extras:
|
|
|
|
```sh
|
|
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"
|
|
```
|
|
|
|
The `recommended` extra includes SquillaRouter dependencies and memory/search
|
|
support used by the default product experience.
|
|
|
|
If `opensquilla` is not found after install, open a new shell or run:
|
|
|
|
```sh
|
|
uv tool update-shell
|
|
```
|
|
|
|
## First-Run Setup
|
|
|
|
Interactive setup:
|
|
|
|
```sh
|
|
opensquilla onboard
|
|
```
|
|
|
|
Script-friendly setup:
|
|
|
|
```sh
|
|
export OPENROUTER_API_KEY="sk-..."
|
|
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
|
|
```
|
|
|
|
Useful variants:
|
|
|
|
```sh
|
|
opensquilla onboard --if-needed
|
|
opensquilla onboard --minimal
|
|
opensquilla onboard --provider openai --api-key-env OPENAI_API_KEY
|
|
opensquilla onboard --provider ollama --model llama3.1
|
|
```
|
|
|
|
`--if-needed` is safe for install scripts because it avoids rewriting an
|
|
already-ready setup. `--minimal` configures the provider path and skips optional
|
|
channels/search/image-generation sections.
|
|
|
|
Check onboarding state:
|
|
|
|
```sh
|
|
opensquilla onboard status
|
|
```
|
|
|
|
## Run the Gateway
|
|
|
|
Foreground gateway:
|
|
|
|
```sh
|
|
opensquilla gateway run
|
|
```
|
|
|
|
Background gateway with readiness wait:
|
|
|
|
```sh
|
|
opensquilla gateway start --json
|
|
opensquilla gateway status
|
|
```
|
|
|
|
Default address:
|
|
|
|
```text
|
|
http://127.0.0.1:18791/control/
|
|
```
|
|
|
|
The gateway defaults to loopback for safety. To bind elsewhere, opt in:
|
|
|
|
```sh
|
|
opensquilla gateway run --listen 0.0.0.0 --port 18791
|
|
```
|
|
|
|
Only expose a non-loopback gateway behind appropriate auth and network controls.
|
|
|
|
## First Useful Run
|
|
|
|
Open the Web UI:
|
|
|
|
```text
|
|
http://127.0.0.1:18791/control/
|
|
```
|
|
|
|
Start terminal chat:
|
|
|
|
```sh
|
|
opensquilla chat
|
|
```
|
|
|
|
Run one automation turn:
|
|
|
|
```sh
|
|
opensquilla agent -m "Inspect this workspace and suggest a test plan"
|
|
```
|
|
|
|
Run a one-shot task in a specific workspace:
|
|
|
|
```sh
|
|
opensquilla agent \
|
|
--workspace /path/to/project \
|
|
--workspace-strict \
|
|
-m "Review the current diff and list the highest-risk changes"
|
|
```
|
|
|
|
Use the Web UI for browser-based chat, approvals, setup, channels, usage, and
|
|
logs. Use `opensquilla chat` when you want a terminal conversation. Use
|
|
`opensquilla agent` for one-shot automation.
|
|
|
|
## Resume Work
|
|
|
|
Resume a terminal chat session:
|
|
|
|
```sh
|
|
opensquilla chat --session <session-key>
|
|
```
|
|
|
|
Inspect sessions:
|
|
|
|
```sh
|
|
opensquilla sessions list
|
|
opensquilla sessions show <session-key>
|
|
opensquilla sessions export <session-key>
|
|
```
|
|
|
|
Export a session when exact history matters for debugging or handoff.
|
|
|
|
## Check Readiness
|
|
|
|
Run these after setup:
|
|
|
|
```sh
|
|
opensquilla doctor
|
|
opensquilla providers list
|
|
opensquilla search list
|
|
opensquilla channels types --json
|
|
```
|
|
|
|
If the gateway is running, inspect runtime status:
|
|
|
|
```sh
|
|
opensquilla gateway status
|
|
opensquilla providers status
|
|
opensquilla channels status
|
|
opensquilla memory status
|
|
```
|
|
|
|
For provider/model selection details, see
|
|
[`providers-and-models.md`](providers-and-models.md). For search setup, see
|
|
[`search.md`](search.md).
|
|
|
|
For gateway lifecycle, host/port, and exposure guidance, see
|
|
[`gateway.md`](gateway.md).
|
|
|
|
## Stop or Restart
|
|
|
|
Foreground gateway:
|
|
|
|
```text
|
|
Ctrl+C
|
|
```
|
|
|
|
Managed background gateway:
|
|
|
|
```sh
|
|
opensquilla gateway stop
|
|
opensquilla gateway restart
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
After the first run:
|
|
|
|
1. Configure search if you want web research:
|
|
[`search.md`](search.md).
|
|
2. Enable channels if you want Slack, Telegram, Feishu/Lark, or another
|
|
messaging surface: [`channels.md`](channels.md).
|
|
3. Review memory behavior if you want durable recall:
|
|
[`features/memory.md`](features/memory.md).
|
|
4. Review tool permissions before unattended automation:
|
|
[`tools-and-sandbox.md`](tools-and-sandbox.md).
|
|
5. Learn SquillaRouter if you want cost-aware model routing:
|
|
[`features/squilla-router.md`](features/squilla-router.md).
|
|
6. Use the glossary if product terms are unfamiliar:
|
|
[`glossary.md`](glossary.md).
|
|
|
|
## Install From Source
|
|
|
|
Use source install when you want a checkout-backed install:
|
|
|
|
```sh
|
|
git lfs install
|
|
git clone https://github.com/opensquilla/opensquilla.git
|
|
cd opensquilla
|
|
git lfs pull --include="src/opensquilla/squilla_router/models/**"
|
|
bash scripts/install_source.sh
|
|
```
|
|
|
|
For development, use the repository virtual environment:
|
|
|
|
```sh
|
|
uv sync --extra recommended --extra dev
|
|
uv run opensquilla --help
|
|
uv run opensquilla gateway run
|
|
```
|
|
|
|
When developing from source, prefix commands with `uv run` so they use the
|
|
checkout you are editing.
|
|
|
|
---
|
|
|
|
[Docs index](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)
|