🍀 Wee-Orchestrator

One platform for agents, runtimes, automation, and every client surface.

Wee-Orchestrator is a self-hosted AI-agent API. It coordinates specialized agents across GitHub Copilot, Claude, OpenCode, Gemini, Codex, Cursor, Devin, and the built-in Wee native runtime for Ollama, OpenRouter, and compatible providers. Use it from the browser Web UI, Telegram, WebEx, or the native macOS app.

What it includes

• Multi-agent chat with persistent sessions, runtime/model switching, and SSE.
• Kanban, background tasks, scheduled automations, task execution history, and agent configuration.
• Wee native tool calling: local code tools, agent delegation, and sourced web search.
• Local model support through Ollama, including long-context model discovery.
• Keychain-backed credentials in the macOS client; pairing/session auth in the API.

Current macOS app

The macOS client is a native desktop workspace for Chat, Kanban, agents, background/scheduled tasks, local models, and separate Local/Remote API settings. It can clone and bootstrap a local API checkout, manage Ollama, and open multiple workspace windows.

Download the current app from the macOS release. The app ships without credentials; configure them in Keychain-backed settings. It checks the macos-v* release stream and can download, verify, install, and relaunch future app updates from inside the client.

Why Wee-Orchestrator

Selling point	What it means
One control plane	Chat, Kanban, background work, schedules, agents, models, and session history share one authenticated API.
Choose the right runtime	Switch between CLI/SDK providers or run local and cloud models through Wee native without changing client surfaces.
Run locally or remotely	The macOS app keeps Local and Remote agents/settings distinct, can bootstrap a local API, and can use on-device Ollama models.
Automation without losing context	Background tasks and scheduled jobs retain agent/runtime configuration and expose execution history.
Built for real agent work	Native tool calls, delegated agents, sourced web search, files, permissions, and long-context model support are part of the platform.
Secure by design	Pairing/session auth and platform Keychain storage keep credentials out of source control and client preferences.

Architecture

Telegram ─┐
WebEx ────┼──► FastAPI API ──► SessionManager ──► Runtimes
Web UI ───┤         │                            ├─ CLI / SDK providers
macOS ────┘         ├──► TaskScheduler           └─ Wee native ──► Copilot SDK (BYOK)
                      │                                              └─ Ollama / OpenRouter
                      └──► History, Kanban, agents, auth, files, and settings

The API owns sessions, authorization, task orchestration, and configured agent workspaces. Clients consume the same authenticated /api/v1 surface. The macOS client can additionally supervise a local API process without mixing its agents or credentials with a remote deployment.

Install the API

macOS and Linux one-line installer

For a localhost-only API installation with a virtual environment, a private generated shared key, and a minimal local agent:

curl -fsSL https://raw.githubusercontent.com/leprachuan/Wee-Orchestrator/main/scripts/install-api.sh | bash

It downloads the latest stable, versioned API release and verifies its SHA-256 checksum before installing it. Set WEE_VERSION=api-vMAJOR.MINOR.PATCH and/or WEE_INSTALL_DIR=/your/path after the pipe to select a release or location. See API releases for the exact command and upgrade behavior. Read the script before running it if your environment requires a custom package or source policy.

Manual installation

git clone https://github.com/leprachuan/Wee-Orchestrator.git
cd Wee-Orchestrator

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env and agents.json for this host. Do not commit either file.

python agent_manager.py --api

Open http://127.0.0.1:8000/ui for the Web UI. Start telegram_connector.py and/or webex_connector.py only when those channels are configured.

For production or networked access, bind the API only to trusted interfaces; do not use API_HOST=0.0.0.0. See network access guidance.

Install and configure the macOS app

1. Download and unzip the current macOS release.
2. Move WeeOrchestrator.app to Applications and open it. The ad-hoc-signed build may require an initial macOS Open/allow action.
3. Use Remote Settings to enter your API URL and pair/sign in, or use Local Settings to clone, bootstrap, and start a local API on the Mac.
4. Use Local Models to install/start Ollama and download a 64K+ context model for the wee runtime. Optional OpenRouter access is configured in Local Settings and stored only in macOS Keychain.

Use File → New Window to open another workspace window. Use Check for Updates or the in-app update notice to install later macOS releases with one click; each update is verified against its published SHA-256 checksum before replacement.

Running local models with the Wee runtime

The wee runtime executes through the GitHub Copilot SDK in BYOK mode against an OpenAI-compatible endpoint. Two prerequisites are easy to miss and both fail in confusing ways:

Model context. The agent prompt is roughly 14 KB before you type anything. A model whose allocated context cannot hold it has no room left to generate, and the turn ends after about one token. What decides this is the num_ctx baked into the model's Modelfile — not the architecture's context length, which Ollama reports as large even for models that will not work:

curl -s http://<ollama-host>:11434/api/show -d '{"model":"<model>"}'   | python3 -c 'import json,sys; print(json.load(sys.stdin).get("parameters"))'

If num_ctx is absent, Ollama uses its own small default and the model cannot be used — pick a large-context variant, or set OLLAMA_CONTEXT_LENGTH on the Ollama host. The runtime checks this before spending a turn and names the model and its num_ctx in the error.

Web search. The SDK provides web_fetch (retrieve a known URL) but no search, so wee registers a search tool backed by SearXNG. Point it at an instance with WEE_SEARXNG_URL (default http://127.0.0.1:8888), and make sure that instance serves JSON — SearXNG enables only html by default and answers 403 otherwise, which silently degrades every search to a public-search fallback:

# searxng settings.yml
search:
  formats:
    - html
    - json

Essential configuration

Need	Configure it in
Agent workspaces and defaults	agents.json (or AGENT_CONFIG_FILE)
API host/port and runtime defaults	.env / process environment
Telegram/WebEx credentials	API secure-secret flow or host secret store
OpenRouter key for Wee native	OPENROUTER_API_KEY in the host secret environment, or macOS Local Settings
Local Ollama endpoint	WEE_OLLAMA_HOST, normally http://127.0.0.1:11434

Never commit API keys, bearer/session tokens, shared keys, bot tokens, or .env files. Every API request requires an authenticated bearer token.

Documentation hub

The README is the landing page. Detailed material that was previously embedded here now lives in the following focused references.

API, operations, and architecture

• Operations and API reference — API endpoints, slash commands, CLI usage, session behavior, Web UI, connectors, testing, troubleshooting, and operations.
• Architecture — components, deployment topology, and orchestration flow.
• API releases — supported installers, release assets, checksum verification, and the API versioning process.
• Documentation index — entry point for the remaining feature-specific documentation.

Configuration and security

• Network access guidance — trusted binding, Tailscale, and SSH access patterns.
• HTTPS and TLS — secure transport configuration.
• Secret tool — secure secret-management workflow.
• Agents and sub-agents and skill sub-agents.

Features and clients

• Local runtime and client update — local API isolation, Ollama, OpenRouter, Wee runtime search, and clients.
• Background tasks and context-window management.
• Skills panel, mobile bots, and agent settings integration.
• Release notes and change history.

Contributing

Open an issue before starting a feature or bug fix, keep credentials out of source control, and run the relevant tests before submitting changes.

Favorite Wee models

Open Settings → Favorite Models in the WebUI or macOS app to star Ollama and OpenRouter models, remove favorites, and change their order. Favorites appear in a Favorites group before provider groups in Wee model pickers. The selected model is unchanged when favorites are edited.

Preferences are shared by clients connected to the same API instance and stored in config/model_favorites.json as {"version": 1, "models": ["openrouter/openai/gpt-4.1-mini", "ollama/qwen3:8b"]}. The authenticated GET /api/v1/model-favorites and PUT /api/v1/model-favorites endpoints read and save the list; PUT accepts {"models": [...]}. IDs are qualified by provider, duplicates are removed, and temporarily unavailable favorites remain saved. Saving an empty list clears favorites. Keep the config/ directory when updating a deployment.

Wee's custom bash tool explicitly overrides the SDK's built-in tool, and Wee tool results are adapted to the current Copilot SDK response contract. OpenRouter execution continues to use credentials from the secure store or service environment.