# How ShinBot works Source: https://adarshdigievo.github.io/shinbot/docs/developers/architecture.html ShinBot adds a personal-assistant application around Pi Durable: a place to talk to bots, watch their browser, save notes, manage routines and review new capabilities. Python owns the product. A small TypeScript service connects it to the unmodified Pi packages. ## Six parts | Part | Responsibility | Components | | --- | --- | --- | | Agent | Model calls, tool calls, conversation state and context compaction | Pi Durable, Pi AI and Chord | | Gateway | Web app, CLI API, authentication, approvals and task coordination | Python, FastAPI, plain HTML/CSS/JavaScript | | Computer | Workspace files, commands, executable plugins and browser interaction | Python worker, MCP, Playwright, Chromium, Xvfb, TigerVNC and noVNC | | Notebook | Editable pages, explicitly saved memories, search and exports | SQLite FTS5 and Markdown | | Jobs | Scheduled tasks and run history | Python coordinator, croniter and SQLite | | Plugins | Skills, MCP tools and optional channels from repository catalogs | Versioned manifests, content hashes and separate processes | SQLite stores application state. Pi Durable and Chord keep the agent's execution state. ShinBot integrates published packages through their public APIs. ## Service boundaries Docker Compose starts four core services. | Service | Network access | Persistent storage | | --- | --- | --- | | `control` | The only published port; connects to internal services | Tasks, profiles, notes, approvals, schedules and plugin packages | | `runtime` | Gateway and model providers | Provider credentials and agent state | | `computer` | Gateway and outbound network | Execution journal and a shared workspace | | `browser` | Gateway and websites | Browser profiles and execution journal | Internal services authenticate requests with separate credentials. Containers do not mount the Docker socket or host home directory. Commands and executable plugins run under an unprivileged identity in the Computer. They have workspace and network access; plugin permission descriptions do not impose a separate network sandbox. ## From a message to an action 1. The gateway authenticates the user and creates a task with the selected bot profile and pinned plugin versions. 2. The coordinator sends work to the runtime. Pi calls the selected provider with the conversation, instructions and available tools. 3. A tool request returns to the gateway. ShinBot checks permissions and asks for approval when needed. 4. The responsible service records the action before executing it. The result returns to Pi and appears in the conversation. 5. The coordinator records progress, usage and the final task state. The UI receives updates from the gateway. Repeated delivery of a completed action returns its recorded outcome. Image payloads use an in-memory cache capped at 8 MB and two minutes in each gateway and executor process. Journals keep text and a replay placeholder; a replay after cache expiry may require a fresh observation. Pi stores the image in conversation history when it receives the result. An interrupted action whose effect is unknown requires inspection before retrying. Durable execution cannot guarantee exactly-once effects on arbitrary websites or shell commands. ## State and concurrency Pi Durable persists model retry checkpoints and wake times. ShinBot configures retries for transient provider failures with backoff capped at 30 seconds. A provider adapter built on Pi's public stream API aborts connections after 60 seconds without progress and returns a retryable error. Provider events reset that deadline. SDK retries are disabled so Pi owns the persistent retry schedule; explicit cancellation remains an abort. Authentication and billing failures are not treated as connection outages. The runtime retries idempotent gateway requests using their existing action IDs. The gateway persists executor retry deadlines in SQLite and queries the Computer or browser journal before dispatching again. A missing receipt permits dispatch with the same ID, a completed receipt supplies the saved result, and an unfinished receipt after an executor restart requires owner review. Tool response waits are capped at 30 seconds; a command can continue running in the executor while the gateway polls its receipt. Bots have separate conversation histories and memories. Notebook pages and workspace files belong to the installation. Browser cookies can belong to one bot, a group, or all bots. Browser profiles open on demand on one interactive display, so browser operations are serialized. Other model and file work can continue concurrently. The coordinator reuses HTTP clients, caps concurrent runs, backs off unchanged polls, and sleeps between checks. Idle services do not call a model. Chromium starts on first browser use; it stays open afterward to preserve the interactive session. Runtime history and user files remain persistent, so monitor disk usage and keep backups. The scheduler records due runs in SQLite, coalesces missed runs after downtime, checks lateness and skips overlaps. Restores pause scheduling and establish a recovery hold before work resumes. See [jobs](../user-guide/scheduled-jobs.html) and [backup and recovery](../user-guide/backups-and-upgrades.html). ## Product knowledge and release checks The `status` tool reports the conversation's identity, model, permissions, usable extensions and browser profile. `bots list` reads current profiles. The `shinbot_help` tool loads product guidance on demand, including the plugin manifest schema and an executable MCP example. Keep this help aligned with implemented behavior; static descriptions must not imply an optional plugin is active. The gateway caches public GitHub and PyPI release metadata in SQLite. Automatic checks run independently of the model and task coordinator, and can be disabled. The host launcher checks its own Python compatibility before installing a verified stable version. The gateway cannot run host updates. The `--latest` path hands off to a fresh interpreter after upgrading the launcher, then uses the existing checkpoint, health-check and rollback flow. ## Where to make a change | Location | Owns | | --- | --- | | `src/shinbot/app.py`, `core.py`, `coordinator.py` | HTTP API and product coordination | | `src/shinbot/tasks.py`, `jobs.py`, `db.py` | Task lifecycle, scheduling and storage | | `src/shinbot/bots.py`, `notebook.py`, `plugins.py` | Profiles, notes, memories and extension catalogs | | `src/shinbot/sources.py`, `learning.py` | Source inspection, portable adapters and evidence-backed skill proposals | | `src/shinbot/services/` | Computer, browser and channel services | | `src/shinbot/web/` | Packaged web application and vendored assets | | `src/shinbot/cli.py` | Installation, local deployment and CLI | | `runtime/src/` | Pi adapter and provider authentication | | `deploy/` | Container targets and Compose definitions | | `marketplaces/` | Official starter plugin and template catalogs | Optional plugins add connections, tools, sidebar pages, themes, UI patches and lifecycle hooks. Trusted UI modules load through authenticated, bot-scoped asset routes. Python hooks run as short-lived Computer workers; gateway and Computer receipts retain their results across reconnects. Hook-transformed tool arguments pass through the normal approval checks. Put a service-specific capability in a plugin when possible. Change the core when the behavior needs shared authentication, durable coordination, permissions or a new shared extension point. Keep provider-specific logic in the runtime adapter. # Develop and test Source: https://adarshdigievo.github.io/shinbot/docs/developers/development.html ## Set up a checkout Use Python 3.13 or newer, uv, Node.js 22 and Docker Compose. CI pins exact tool versions in `.github/workflows/ci.yml`. ```sh git clone https://github.com/adarshdigievo/shinbot.git cd shinbot uv sync --frozen --extra computer --extra security --extra telegram npm --prefix runtime ci --ignore-scripts npm --prefix computer ci --ignore-scripts npm --prefix runtime run build node scripts/copy_web_assets.mjs uv run --frozen shinbot start --build ``` This starts a real installation. For disposable development and testing, use the integration runner below. Do not point tests at a personal installation or reuse its credentials. `shinbot serve` runs only the Python gateway. It is useful when working on that service, but it does not start Pi, the browser or the Computer. ## Run checks ```sh uv run --frozen ruff check src tests scripts uv run --frozen --extra computer --extra security --extra telegram pytest npm --prefix runtime run build npm --prefix runtime test npm --prefix runtime audit --audit-level=low npm --prefix computer audit --audit-level=low uv run --frozen python scripts/release.py check uv build --out-dir dist/check uv run --frozen python scripts/release.py check-wheel dist/check ``` Use an empty wheel output directory. CI checks the locked Node packages for published advisories; the release workflow also checks locked Python packages through PyPI. These checks do not replace license reviews or platform audits. The packaging check verifies metadata, every web asset and the bundled release Compose file. Vendored browser libraries come from the pinned runtime dependencies; run `node scripts/copy_web_assets.mjs` after changing their versions and review the resulting files and license notices. The browser-only suite starts an isolated gateway with fixture data: ```sh uv run --frozen playwright install chromium uv run --frozen python tests/run_onboarding.py ``` On Linux, install browser system dependencies with `playwright install --with-deps chromium` where administrative access is available. ## Exercise services without Docker ```sh uv run --frozen --extra computer --extra security python tests/run_local_services.py ``` This runner starts the gateway, Pi Durable, Computer, Chromium and a deterministic model fixture on localhost. It checks tool dispatch, learned skills, memory refresh, browser forms and takeover, Kanban continuation, service restarts, and the UI in light, dark and mobile layouts. It records idle CPU and memory samples and writes screenshots under `tmp/reference/production/local-services/`. The runner enables the development Computer executor in a temporary workspace. It does not load personal credentials, test Linux container isolation, or measure production model quality. Run the container journeys before releasing images. The attachment journey runs the Pi runtime, Computer and Camoufox with a deterministic model. It checks file creation, screenshot delivery, authenticated downloads, automatic browser cleanup and restart recovery: ```sh uv sync --frozen --extra computer --extra browser --extra security uv run --no-sync python -m camoufox fetch official/stable/156.0.1-beta.36 uv run --no-sync python tests/run_attachments.py ``` On Linux, run `uv run --no-sync playwright install-deps firefox` before the Camoufox journey. ## Container integration tests Build the images from the checkout, then run the isolated journeys: ```sh version=$(uv run --frozen python -c 'from shinbot import __version__; print(__version__)') for service in control runtime computer browser telegram; do docker buildx build --load --file deploy/Dockerfile --target "$service" \ --tag "shinbot-dev/shinbot:$version-$service" . done uv run --frozen python tests/run_e2e.py ``` The runner creates a temporary home, a unique Compose project and a separate localhost port. It uses a local model fixture and removes only its own containers and volumes. It checks chat, approvals, plugins, compaction, scheduled jobs, browser profiles, backup/restore and wheel uninstall/reinstall. It does not test a paid provider's live sign-in or account eligibility. Use `--only ui` or `--only reinstall` to run one journey. `--prepare-only` leaves an isolated app available for manual testing and prints its URL and cleanup command. Individual journey scripts require the runner's context and reject the default personal project and port. These builds use `shinbot-dev/shinbot` tags, separate from the published image tags a personal installation uses. The test runner saves that image repository in its isolated deployment. Use `--image-repository NAME` if you built a different local image set. CI uses the same build loop in its `Container integration` job. ## Build the website The custom landing page lives in `site/`. Great Docs builds the authored guides from `docs/` using `great-docs.yml`. Install [Quarto](https://quarto.org/docs/get-started/) at the version used in `site-build.yml`, then run: ```sh uv sync --frozen --group docs uv run --frozen --group docs python scripts/build_site.py uv run --frozen --group docs python scripts/check_site.py uv run --frozen --group docs playwright install chromium uv run --frozen --group docs python tests/run_site.py ``` The assembled site is `_site/`: its root is the landing page and its `docs/` directory contains Great Docs output. `great-docs/` and `_site/` are generated and ignored. Edit the source pages, not generated HTML. The link checker checks the rendered pages and assets, including GitHub Pages' `/shinbot/` prefix. The website browser check exercises screenshot tabs, command copying, documentation search, theme persistence and mobile navigation. It saves review images under `test-results/site/`. Great Docs is a development dependency and is not installed by `pip install shinbot`. ## Contributing a change Describe the user-visible problem and how to reproduce it. Keep changes focused and add a behavioral test when it protects a real failure mode. Include rendered screenshots for interface changes and verify narrow screens, keyboard access, and both themes. Keep new dependencies small and review their full dependency graph and licenses. Use upstream packages unchanged. Update the relevant user guide when a command, setting or workflow changes. Avoid putting credentials, private task transcripts or generated test data in a pull request. # Write a plugin Source: https://adarshdigievo.github.io/shinbot/docs/developers/plugins.html A plugin is a versioned directory. Use a skill for instructions, MCP for tools, or an extension for sidebar pages, themes, UI patches and lifecycle hooks. Extensions can include MCP tools in the same package. Channel plugins run as separately managed services and need host integration. ## A skill package ```text plugins/writing-style/ shinbot-plugin.json SKILL.md LICENSE ``` ```json { "schema_version": 1, "id": "writing-style", "name": "Writing style", "version": "1.0.0", "description": "Apply a personal writing guide.", "kind": "skill", "license": "MIT", "files": ["SKILL.md", "LICENSE"] } ``` Write clear instructions in `SKILL.md`: when to use the skill, the information it needs, the steps to follow and how to check the result. Skills load on demand. Include a complete license in `LICENSE`. ## An MCP tool The Python runner has the standard library and MCP dependencies available. This example normalizes whitespace without touching files or the network. `server.py`: ```python from mcp.server.fastmcp import FastMCP mcp = FastMCP("Text tools") @mcp.tool() def normalize(text: str) -> str: """Collapse repeated whitespace in text.""" return " ".join(text.split()) if __name__ == "__main__": mcp.run() ``` `shinbot-plugin.json`: ```json { "schema_version": 1, "id": "text-tools", "name": "Text tools", "version": "1.0.0", "description": "Normalize whitespace in text.", "kind": "mcp", "license": "MIT", "files": ["server.py", "LICENSE"], "entrypoint": "server.py", "tools": [{ "name": "normalize", "description": "Collapse repeated whitespace in text.", "input_schema": { "type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"] } }] } ``` Activation checks the running MCP server's tool list against the manifest. Tool names must be unique lowercase identifiers. The namespaced form `plg____` must fit within 64 characters. The `files` list must match the package exactly, excluding the manifest itself. Packages cannot contain symlinks, hidden files or paths outside the directory. The package limit is 2 MB, with at most 100 declared files and 100 tools. ## Credentials and settings Declare a `configuration` array when a tool needs an API token or an account setting: ```json "configuration": [ { "key": "SHINBOT_PLUGIN_EXAMPLE_TOKEN", "label": "API token", "description": "Create a token for the account you want to connect.", "secret": true, "required": true } ] ``` Keys must begin with `SHINBOT_PLUGIN_` and use uppercase letters, digits and underscores. The UI and `shinbot plugins configure PLUGIN VERSION` prompt for these fields. Required values must be set before MCP activation. Read them from the plugin process environment, not tool arguments. Do not print them or include them in exceptions. The gateway stores settings outside the Computer workspace, in an authenticated-encryption vault readable only by the gateway user. The vault key is stored in a separate mode-0600 file in the same control volume; host administrators and full backups can access both. Legacy JSON settings migrate on use. Native GitHub inbox and Google Calendar requests resolve their credentials inside the control service. It passes only the selected plugin’s declared settings to its process. Settings are shared by versions from the same marketplace and excluded from task arguments and executor journal payloads. A local package is bound to its exact content hash and must be configured again when it changes. A different marketplace or local replacement cannot inherit another source’s credentials. This does not isolate mutually untrusted plugins running under the shared Computer identity. Set `"requires_confirmation": true` on a manifest tool to require owner approval even with automatic Computer access. An owner can remember an approval for matching arguments from chat. The GitHub plugin uses this for all write operations. A plugin can return an MCP `CallToolResult` with `isError: true` and `_meta: {"shinbot_outcome": "uncertain"}` when an external write may have completed without acknowledgement. The Computer records an uncertain receipt and pauses the task for owner review. Use ordinary MCP errors for rejected inputs that did not cause a change. Inspect `marketplaces/official/plugins/github/` for a complete example using the existing HTTPX and MCP dependencies. ## Test and activate ```sh shinbot plugins install /path/to/text-tools shinbot plugins activate text-tools 1.0.0 ``` Start a new conversation and ask for a small test with a known result. Executable activation requires extension and Computer permission and a completed security scan with no high or critical findings. Scan reports are tied to the exact package digest, scanner version and ShinBot policy. Check failures, timeouts, malformed input and interrupted execution before sharing a tool that changes external state. ShinBot pins active versions when a conversation starts. Publishing a newer version does not change a running conversation. Disable a plugin with `shinbot plugins disable text-tools` to block further calls, including calls from existing conversations. Activate a previously installed version to roll back. ## Publish a marketplace Put packages under `plugins//` in a GitHub repository. From a ShinBot source checkout, generate the catalog: ```sh uv run python scripts/build_marketplace.py /path/to/your-shinbot-plugins ``` Commit the packages, license and generated `shinbot-marketplace.json` to your repository. Users can add it with: ```sh shinbot marketplace add your-name/your-shinbot-plugins ``` The catalog records each package ID, version, directory and content hash. Refresh resolves a repository commit and verifies the package against that hash. Never change the bytes of a released plugin version; publish a new version instead. The official repository is [shinbot-official-plugins](https://github.com/adarshdigievo/shinbot-official-plugins). Submit a pull request with a small purpose, clear instructions, a license and a way to reproduce the tool's behavior. Public personal repositories use the same format. ## Execution and dependencies Executable plugins run in the Computer with access to its workspace and outbound network. They do not receive mounted gateway data, provider credentials, browser profiles or the Docker socket. This is a shared trust boundary: it is not a separate VM or per-plugin network sandbox. The manifest's `requires` list must be empty in the default runner. Additional dependencies need a host license review and a prepared runner image. A plugin cannot install arbitrary packages into the gateway or runtime. Supported manifest license identifiers are `MIT`, `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `0BSD`, `Unlicense` and `CC0-1.0`. ShinBot can write, test and stage its own skills and tools. Activation remains a reviewed change; newly activated tools become available in a new conversation. ## Direct MCP connections and standard skills `POST /api/plugins/mcp/connect` accepts `id`, `name`, `version`, `server` and `access`. `server` selects `stdio` with `command`, `args` and `env`, or `http`/`sse` with `url` and `headers`. Discovery runs in the unprivileged Computer worker. ShinBot stores schemas in an immutable plugin manifest and saves credentials separately. Reconnecting with changed configuration or schemas requires a new version. Direct MCP tools require confirmation. `POST /api/plugins/skills/install` accepts a `command` such as `npx skills add owner/repo --skill NAME`, the verified upstream `license`, and `access`. The pinned Skills CLI runs in a temporary workspace directory. Its text files become an immutable skill package; their content hash determines the version. `POST /api/plugins/skills/import` accepts a text `files` map instead for host-side imports. Neither import path executes skill scripts. Use `PUT /api/plugins/{id}/access` with `{"mode":"shared","bots":[]}` or `{"mode":"bots","bots":["BOT_ID"]}`. Access is stored separately from the package. Task creation selects available versions, and dispatch checks current access again. The `plugins read_skill` agent tool checks both task selection and current bot access before returning instructions or reference files. This is routing control within a trusted single-owner installation, not process isolation. Agent tool schemas live in `runtime/src/tools.ts`; orchestration and approval checks live in `src/shinbot/core.py`. Keep those schemas, system instructions and setup endpoints aligned when adding capabilities. `bots save_template` validates and stores portable profiles in the local template library. Saving a template does not publish it to a repository. ## Native toolkits Projects and Kanban use `kind: builtin`. Their backend operations and UI are shipped with ShinBot, while their manifests are distributed in the official marketplace and installed explicitly. A native package must match the bundled files byte for byte. Custom packages use `kind: extension` for their own UI and hooks, or MCP and skills for tools and instructions. Native toolkit code changes currently require a ShinBot release. The Projects toolkit owns repository registration, worktree lifecycle and delegation policy. Core task records carry working-directory and parent-task references so ordinary file tools, commands, cancellation and durable scheduling apply to project work. Git operations run under the Computer worker identity. Repository registration and worktree creation do not execute setup scripts or install project dependencies. ## Sidebar apps, themes and UI patches Use `kind: extension`. The following fields add a Paint page, its stylesheet and a composer shortcut. Include each referenced file in the top-level `files` array, along with `LICENSE`. ```json { "permissions": ["ui.pages", "ui.styles", "ui.patch"], "ui": { "pages": [{"id": "canvas", "title": "Paint", "icon": "pencil", "entrypoint": "paint.js"}], "styles": ["paint.css"], "patches": ["toolbar.js"], "assets": [] } } ``` A page exports `mount(root, sdk)`. ShinBot supplies a content element beneath the page title. A patch exports `activate(sdk)` and runs while the plugin is enabled for the selected bot. Both functions may be async and may return a cleanup function. Return cleanup for timers and subscriptions, and use `sdk.signal` for requests and event listeners. Check `sdk.signal.aborted` after awaiting work before touching the interface. ```javascript export function activate(sdk) { const button = document.createElement('button'); button.textContent = 'Review'; button.onclick = () => sdk.compose('Review the current changes and report the checks you ran.'); return sdk.mount('composer-actions', button); } ``` The UI SDK provides: | API | Use | | --- | --- | | `sdk.plugin`, `sdk.botId`, `sdk.taskId` | Plugin identity, selected bot and current conversation | | `sdk.storage.get(key)`, `sdk.storage.set(key, value)`, `sdk.storage.delete(key)` | Persistent JSON storage per plugin and bot, retained across version changes | | `sdk.asset(path)` | URL for a declared package asset | | `sdk.api(path, method, body)` | Authenticated ShinBot API requests | | `sdk.compose(text)` | Open an unsent chat draft for the current bot | | `sdk.navigate(view)` | Open a core page or `plugin/PLUGIN_ID/PAGE_ID` | | `sdk.toast(text, isError)` | Show feedback | | `sdk.on(event, handler)` | Subscribe to `navigate`, `snapshot` or `appearance`; returns an unsubscribe function | | `sdk.mount(slot, element)` | Mount an element in `composer-actions`, `sidebar-footer` or `topbar`; returns cleanup | | `sdk.signal` | Abort signal for the page or patch lifetime | Mounted slot elements follow page rerenders and are removed on disable or a bot change. A page's scope ends when the user leaves it. `navigate` events contain `view`, `botId` and `taskId`; `snapshot` contains the task and notification snapshot; `appearance` contains `preference` and `theme`. Styles are ordinary CSS. Use ShinBot's variables such as `--paper`, `--surface`, `--ink` and `--accent`, and use `[data-theme="light"]` and `[data-theme="dark"]` to respect the owner's appearance choice. Scope page styles to `[data-plugin="YOUR_ID"]`. A theme plugin can override the variables globally. A stylesheet applies while its plugin is enabled; disabling it restores the underlying theme. Page and patch entrypoints must be JavaScript modules. Declare imported helpers, images, fonts and JSON files in `ui.assets`. Only declared UI assets are served, and asset requests check activation and bot access. Storage keys use letters, numbers, underscores and hyphens. Values are limited to 200 KB, with 2 MB total and 200 keys per plugin and bot. Use Computer files through a tool for larger documents. UI modules and styles are trusted app code. They run in the signed-in app, can read or change its interface, and can call its APIs. Bot scoping controls when code is loaded; it does not sandbox a plugin after execution. The activation screen explains this access. Avoid global side effects at module import time and clean up everything created by `activate`. A clean page reload removes a disabled plugin's loaded JavaScript. Open `/?extensions=off` to skip every plugin UI contribution, then disable or roll back the faulty version in Plugins. The query affects that browser session's UI only; it does not disable server hooks or tools. Optional packages in `examples/plugins/paint`, `examples/plugins/ocean-theme` and `examples/plugins/workflow-hooks` demonstrate a saved drawing, a theme and a composer shortcut. Install them with the usual CLI commands. None is installed automatically. ## Chat and tool hooks Declare handlers alongside UI or tools, or in an extension containing only hooks: ```json { "permissions": ["hooks"], "hooks": [ {"event": "before_chat", "entrypoint": "hooks.py", "timeout": 10}, {"event": "before_tool", "entrypoint": "hooks.py", "timeout": 10}, {"event": "after_tool", "entrypoint": "hooks.py", "timeout": 10}, {"event": "after_response", "entrypoint": "hooks.py", "timeout": 10} ] } ``` Each Python entrypoint exports a synchronous `handle(event, context)` function. It receives `event_id`, `task_id`, `bot_id`, `data` and a persistent `data_dir` under the Computer workspace. Declare credentials through `configuration`; only that plugin's settings are supplied to its process. Return a JSON object or `None`. | Event | `context["data"]` | Allowed return fields | | --- | --- | --- | | `before_chat` | Submitted `content`, accumulated `context` text | `context` to supply model instructions; `block` with a reason to stop the turn | | `before_tool` | `tool`, `args` | `args` to replace arguments; `block` with a reason to stop the call | | `after_tool` | `tool`, `args`, completed `result` | `result` to replace the result given to the model | | `after_response` | `answer`, `status`, `error` | Empty object; observe the finished turn without replacing its answer | ```python def handle(event, context): data = context["data"] if event == "before_chat": return {"context": data["context"] + "\nReport which checks actually ran."} if event == "before_tool" and data["tool"] == "run_command": if "git push --force" in data["args"].get("command", ""): return {"block": "This workflow does not allow force pushes."} return {} ``` The string check above illustrates a hook, not a shell security policy. ShinBot still evaluates approvals after a hook changes arguments. A hook result cannot approve an action or change the selected tool. `before_tool` and `after_tool` wrap completed tool calls throughout the model's tool loop. Failed or denied tools do not trigger `after_tool`. Hooks run in deterministic plugin-ID order, using the versions pinned to the conversation. Later hooks see earlier changes. New conversations select newly activated versions. Removing bot access or disabling a plugin stops its future hooks and tool calls. A hook already executing can finish. Computer records an invocation before running it and reuses completed results after reconnects and restarts. An interrupted invocation is marked uncertain and is not executed again automatically. Before-hook failures stop the turn or tool with a reason. After-hook failures leave the original tool result or answer available and create a plugin event. Use the stable `event_id` as an idempotency key when calling another service: no local journal can guarantee an external system's outcome after a lost connection. Hooks have Computer file and network access and run automatically once activated. Activation grants that execution; their internal operations do not each produce a chat approval. Keep them short, use the existing runtime dependencies, and set a timeout between 1 and 60 seconds. Return at most 200 KB. Context and blocking text are limited to 20,000 characters. # Publish bot templates Source: https://adarshdigievo.github.io/shinbot/docs/developers/templates.html A template shares a bot's configuration without sharing the owner's conversations, memories, workspace, credentials or browser state. Templates describe either one bot or a group of bots. ## Repository layout ```text shinbot-templates.json LICENSE templates/ research-pair/ template.json ``` `template.json`: ```json { "schema_version": 1, "id": "research-pair", "version": "1.0.0", "name": "Research pair", "description": "Research and writing for a shared project.", "kind": "group", "license": "MIT", "profiles": [ { "name": "Researcher", "instructions": "Check primary sources and save findings in the notebook.", "starters": ["Help me research a topic and keep a source list."], "browser": "group" }, { "name": "Writer", "instructions": "Turn shared research notes into a draft. Preserve source links.", "browser": "group" } ] } ``` Use `kind: "bot"` with exactly one profile for an individual template. A group can contain up to 12 profiles. ## Profile fields | Field | Meaning | | --- | --- | | `name` | Required name, up to 80 characters | | `color` | `blue`, `teal`, `amber`, `rose`, `violet` or `slate`; omit it to assign a colour during import | | `description` | Short role description, up to 500 characters | | `instructions` | Working instructions, up to 12,000 characters | | `starters` | Up to six nonempty prompts, each up to 1,000 characters | | `browser` | `private`, `group` or `shared`; defaults to `private` | | `provider`, `model` | Set both for a model override, or omit both to inherit the installation's model | Group browser sharing requires a group template. Imports use private or newly created group profiles by default. Access to existing shared sign-ins requires an explicit choice in the import preview. Importing a template does not grant permissions or enable scheduled jobs. Template IDs use lowercase letters, numbers and hyphens, beginning with a letter. Versions use `MAJOR.MINOR.PATCH`. Include an accepted license, such as MIT, and the corresponding license text. Unknown fields are rejected so spelling mistakes do not silently change behavior. ## Validate and share From a ShinBot source checkout: ```sh uv run python scripts/build_templates.py /path/to/your-bot-templates ``` The builder validates every `templates/*/template.json` and writes `shinbot-templates.json` with paths and SHA-256 hashes. Commit that catalog with the templates. Users can add the repository from Home or run: ```sh shinbot bots add-repository your-name/your-bot-templates ``` You can also export an existing bot and import the file directly: ```sh shinbot bots export BOT_ID ./template.json shinbot bots import ./template.json ``` Read the instructions before sharing an export: configuration can still contain names or private information that someone typed into a profile. Test with a new installation, check that inherited model settings work, and keep shared-browser access optional. Submit official templates through pull requests to [shinbot-official-templates](https://github.com/adarshdigievo/shinbot-official-templates). Starter examples are included in the ShinBot checkout under `marketplaces/templates/`. # CI and releases Source: https://adarshdigievo.github.io/shinbot/docs/developers/releases.html GitHub Actions checks pull requests and builds releases from a GitHub Release tag. PyPI publishing uses GitHub's OIDC identity. Docker Hub publishing uses a scoped access token. Pull requests receive neither publishing credential. ## Configure the repository ### GitHub Pages In **Settings → Pages**, choose **GitHub Actions** as the source. Configure the `github-pages` environment to allow release tags matching `v*`. The project site is `https://adarshdigievo.github.io/shinbot/`. The landing page is at that root; Great Docs is at `https://adarshdigievo.github.io/shinbot/docs/`. This is a project site, so `/shinbot/` is part of both URLs. ### PyPI trusted publishing Create a pending publisher for a new PyPI project, or add a trusted publisher to the existing project. Use these exact values: | Setting | Value | | --- | --- | | PyPI project | `shinbot` | | GitHub owner | `adarshdigievo` | | Repository | `shinbot` | | Workflow filename | `release.yml` | | Environment | `pypi` | Create the matching `pypi` environment in GitHub. Restrict deployment to release tags; add required reviewers if desired. No PyPI API token belongs in GitHub secrets. See [PyPI's publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/). ### Docker Hub Create the public repository `adarshd96/shinbot`. Create a Docker Hub personal access token with **Read & Write** access, without Delete access. Add these values to the GitHub `dockerhub` environment: | Type | Name | Value | | --- | --- | --- | | Actions variable | `DOCKERHUB_USERNAME` | `adarshd96` | | Actions secret | `DOCKERHUB_TOKEN` | The Docker Hub access token | Restrict the `dockerhub` environment to `v*` tags. Store the token only in that environment, not as a repository-wide secret. Rotate it through the environment's secrets; do not place it in workflow files or release notes. The Docker owner is **adarshd96**; the GitHub owner is **adarshdigievo**. ## What runs | Workflow | Trigger | Result | | --- | --- | --- | | `ci.yml` | Pull request, push to `main`, manual run, release caller | Python checks on Linux and macOS; runtime tests; browser journeys; wheel checks; isolated container integration | | `site-build.yml` | Called by Website checks or Release | Great Docs build, landing-page assembly and rendered-link checks | | `pages.yml` | Pull request, push to `main`, manual run | Validates the site without deploying it | | `release.yml` | Published GitHub Release or manual retry on a release tag | Checks the tag and versions; runs CI and site checks; publishes images, then PyPI, then the website and documentation | Actions use reviewed commit pins; the actionlint container uses a verified image digest. Python and runtime lockfiles are checked in. Documentation dependencies are isolated in the `docs` dependency group. ## Prepare a version Work from a clean checkout. Update the synchronized version fields with: ```sh uv run python scripts/release.py set-version 0.1.0a2 uv lock uv run python scripts/release.py check ``` The helper updates the Python package, TypeScript package and lock root, both Compose files and the integration fixture's image tag. `uv lock` refreshes the Python lock metadata. It accepts stable versions such as `0.1.0` and prereleases such as `0.1.0a2`, `0.1.0b1` and `0.1.0rc1`. Review dependency/license changes, run CI and the site build, then commit the version change. Create a tag such as `v0.1.0a2` at that commit and publish a GitHub Release for it. Set GitHub's **prerelease** flag for `a`, `b` and `rc` versions. The release check rejects a mismatched flag or tag. ## Published artifacts Every release produces a Python wheel and source archive, four core Docker images, and images for desktop mode and the optional Telegram plugin: ```text adarshd96/shinbot:VERSION-control adarshd96/shinbot:VERSION-runtime adarshd96/shinbot:VERSION-computer adarshd96/shinbot:VERSION-browser adarshd96/shinbot:VERSION-desktop adarshd96/shinbot:VERSION-telegram ``` Images are built for `linux/amd64` and `linux/arm64`, with build provenance and SBOM attestations. Container journeys run on the Linux CI host; cross-platform image builds do not replace native runtime testing on every architecture. BuildKit stores reusable layers in `buildcache-` tags in the same Docker Hub repository. These tags are build caches, not runnable releases. They can be removed to reclaim storage; the next release will rebuild the layers. After PyPI publishing, a serialized promotion job checks the current latest release before updating `latest-control`, `latest-runtime`, `latest-computer`, `latest-browser`, `latest-desktop` and `latest-telegram`. Prereleases keep versioned tags. The launcher uses the exact image set bundled with its package, never the mutable `latest-*` aliases. PyPI publishing waits for all image builds and pushes, so a newly installable package has its matching containers. Package attestations are produced by the PyPI publishing action. ## Handle a failed release Inspect the failed job before retrying. A failed matrix can leave some versioned Docker tags published; rerun failed jobs to finish the set. PyPI versions cannot be overwritten. If a version is already published and needs different code, make a new release rather than moving its tag. For a publishing-only retry after CI has passed, select the existing release tag and explicitly skip the repeated CI jobs: ```sh gh workflow run release.yml --ref v0.1.0a2 -f skip_checks=true ``` This still validates the release identity and dependency advisories, builds and checks the site and distributions, and publishes the service images. Normal releases and manual runs without `skip_checks` run the full CI suite. The release workflow deploys the landing page and documentation built from the release tag after PyPI publishing succeeds. Pushes to `main`, pull requests and manual website checks do not publish anything. Each successful release deploys its tagged website, including prereleases. A website deployment can fail without unpublishing the package; rerun the failed deployment job. Use its deployment URL and test both the root and `/docs/`. For local troubleshooting, build `_site/` and run the same scripts used by CI. GitHub account settings, environment protections and registry permissions are only verified by an actual GitHub Actions run. # CLI commands Source: https://adarshdigievo.github.io/shinbot/docs/reference/cli.html Run `shinbot --help` for the installed command list. Each command and group accepts `--help`. Chat and configuration commands use the same gateway as the web app. Installation, backup and recovery commands run on the host and can work while the gateway is unavailable. ## Installation and recovery | Command | Purpose | | --- | --- | | `shinbot start` | Start the versioned Docker services and open the web app | | `shinbot start --no-open-browser` | Start on a headless host | | `shinbot start --build` | Build service images from a source checkout | | `shinbot setup-token` | Print the unclaimed installation's one-time setup token | | `shinbot status` | Show Compose service status | | `shinbot doctor` | Check the gateway and connected services | | `shinbot stop` | Stop services while keeping data volumes | | `shinbot backup PATH` | Back up host settings, plugins and all persistent volumes | | `shinbot backup-info PATH` | Verify an archive without exposing its credentials | | `shinbot update --check` | Check GitHub and PyPI for a stable release | | `shinbot update --latest` | Upgrade a supported launcher and apply the matching service release | | `shinbot update` | Apply the installed package’s release with a restore point and health checks | | `shinbot update --build` | Build and apply a source release with the same recovery checks | | `shinbot rollback` | Restore the previous release and its data after an update | | `shinbot restore PATH --replace` | Back up existing data and restore an archive under a recovery hold | | `shinbot version` | Print the package version | ## Conversations and notes ```sh shinbot login shinbot login --url https://bot.example.com shinbot chat "Research a topic and save a note" shinbot chat "Continue with the next step" --task TASK_ID shinbot chat "Plan my day" --bot BOT_ID shinbot notes list --query "research" shinbot notes add "Packing list" "Passport, charger, notebook" ``` Login prompts for the password and stores a revocable bearer token in the launcher home. Avoid putting passwords or provider secrets in command arguments. When a task needs approval, the CLI prints the web app address and exits. Complete the approval in the web app; there is no CLI approval command. ## Bots and jobs ```sh shinbot bots list shinbot bots create "Researcher" --instructions "Keep a source list." --browser private shinbot bots export BOT_ID ./template.json shinbot bots import ./template.json shinbot bots add-repository your-name/your-bot-templates shinbot jobs list shinbot jobs add "Morning reading" "Find useful updates" "0 9 * * 1-5" --timezone Asia/Kolkata shinbot jobs pause JOB_ID ``` Use the web app to configure one-time and interval jobs, edit routines, manage groups and preview imported templates. ## Plugins ```sh shinbot marketplace add your-name/your-shinbot-plugins shinbot marketplace list shinbot plugins list shinbot plugins install /path/to/plugin shinbot plugins configure PLUGIN VERSION shinbot plugins activate PLUGIN_ID VERSION shinbot plugins disable PLUGIN_ID ``` The marketplace command accepts `--ref` when a specific repository ref is needed. Local installation stages a package; activation is a separate step. See [plugins](../user-guide/plugins.html) for installation, activation and access settings. ### Optional Telegram plugin Use these commands to set up or stop the [official Telegram plugin](../user-guide/telegram.html): ```sh shinbot telegram-setup shinbot telegram-stop ``` ## MCP connections and skills | Command | Purpose | | --- | --- | | `shinbot plugins connect-mcp config.json --bot BOT_ID` | Connect and inspect a server from JSON configuration | | `shinbot plugins install-skills 'npx skills add owner/repo --skill NAME' MIT --bot BOT_ID` | Install skills inside Computer and stage them | | `shinbot plugins import-skill .agents/skills/NAME MIT --bot BOT_ID` | Import skills installed on the host | | `shinbot plugins access ID --shared` | Share an extension with all bots | | `shinbot plugins access ID --bot BOT_ID` | Limit an extension to selected bots; repeat `--bot` for more than one | Replace `MIT` with the upstream license. Omit `--bot` when setup should use shared access. After installation, review and activate the version in Plugins. See [Plugins, MCP and skills](../user-guide/plugins.html) for JSON fields and supported transports. # Configuration and data Source: https://adarshdigievo.github.io/shinbot/docs/reference/configuration.html Configure model providers, permissions, budgets and appearance in **Settings**. Configure a bot's role, starter prompts, browser sharing and optional model override from **Home**. ## Launcher settings The launcher stores installation details in `~/.shinbot/deploy.env` and CLI connection details in `~/.shinbot/client.json`. These files are private and may contain credentials. Do not commit or paste them into an issue. | Setting | Purpose | | --- | --- | | `SHINBOT_HOME` | Override the launcher's directory; set this in the host environment before running the CLI | | `SHINBOT_PORT` | Published gateway port; defaults to `8765` | | `SHINBOT_BIND` | Published bind address; defaults to `127.0.0.1` | | `SHINBOT_ORIGIN` | Exact browser-facing origin, including scheme and non-default port | | `SHINBOT_PROJECT` | Saved Compose project identity; do not change it during an upgrade | | `SHINBOT_DOCKER_CONTEXT` | Saved Docker context; use the same engine for an existing installation | | `SHINBOT_IMAGE` | Override the image repository while preserving the versioned service tags | | `SHINBOT_SAFE_MODE` | Set to `1` to hold background execution while inspecting an installation | | `SHINBOT_COMPOSE_FILE` | Advanced host override for a custom Compose file | The launcher generates internal service tokens and saves the engine identity. Keep those values intact. Do not expose internal runtime, Computer, browser or VNC ports. For remote access and TLS, follow the [server access guide](../user-guide/remote-access.html). Restart with `shinbot start` after editing deployment settings. After a rollback, ShinBot uses its saved service snapshot; run `shinbot update` with the intended launcher release to apply deployment changes. A custom port must agree with `SHINBOT_ORIGIN` and the address used in the browser. ## Persistent data | Location | Contents | | --- | --- | | Launcher home | Deployment configuration, service credentials and CLI session | | `control-data` volume | SQLite application state, notes, plugins and artifacts | | `runtime-data` volume | Agent state and model provider credentials | | `computer-data` volume | Computer execution journal and plugin state | | `browser-data` volume | Persistent browser profiles and browser execution journal | | `workspace` volume | Files used by tools and commands | Compose prefixes volume names with the saved project name. Removing or reinstalling the Python package does not delete these locations. Deleting volumes, changing Docker engines or removing the launcher home can break that continuity. Use [backup and restore](../user-guide/backups-and-upgrades.html) to move an installation. ## Defaults and scope ShinBot has one owner account. Bot profiles are roles within that account, not separate security principals. Notes and workspace files are shared; memories and conversations belong to their bots. Browser sharing is explicit. New installations start with preference memory on, optional token caps off, no selected model, and no installed plugins. Choose a model during setup or in Settings; bot profiles can override it. Existing saved choices remain intact when ShinBot is upgraded. Setup suggests the browser’s timezone. Change it in **Settings → Workspace**. ShinBot stores timestamps as UTC instants and displays them in the selected timezone, including chats, jobs, notifications and Calendar. Each recurring job also keeps its scheduling timezone so daylight-saving changes follow that schedule. Appearance defaults to the system preference. Light, Dark and System choices are saved in that browser. Provider credentials and task data stay on the server; selected model providers receive the context needed for model calls. ## HTTP integration The web app and CLI use the gateway API in `src/shinbot/app.py`. The HTTP API is an internal product interface and may change between versions. Prefer the CLI for automation and MCP plugins for new agent tools. Do not send internal service credentials from a browser or third-party client. # Licenses and dependencies Source: https://adarshdigievo.github.io/shinbot/docs/reference/licenses.html ShinBot is distributed under the [MIT license](https://github.com/adarshdigievo/shinbot/blob/main/LICENSE). It uses published upstream packages unchanged. Keep their copyright and license notices when redistributing ShinBot packages or images. ## Application dependencies The Python and JavaScript lockfiles record the selected dependency graphs. `computer/package-lock.json` pins Skills CLI 1.7.2 and its dependencies under MIT, ISC and [Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0). Their notices remain in the Computer image. Installed skills and user-configured MCP servers have separate licenses that must be reviewed before use. Pi Durable, Pi AI, Chord, FastAPI, MCP and Playwright use permissive licenses. Lucide icons are distributed with their ISC and MIT notices. DOMPurify provides Apache-2.0 as a license choice. Reviewed open-source exceptions include **noVNC and certifi under MPL-2.0**, and the optional **python-telegram-bot connector under LGPL-3.0**. Their notice, source and applicable relinking obligations continue to apply. An MIT license on ShinBot does not replace upstream licenses. The bundled standard-license fingerprints record their SPDX source revision in `src/shinbot/bundled/license-hashes.json`. Unknown or modified texts need review; matching a notice does not establish the license of every file. New plugin manifests accept the supported permissive identifiers described in the [plugin guide](../developers/03-plugins.qmd). Additional plugin dependencies require a host review before they can enter a runner image. The landing page uses the unmodified Figtree font under the SIL Open Font License 1.1. Its copyright notice and license ship alongside the font in `site/assets/fonts/OFL.txt`. ## Browser backends Camoufox's Python package is MIT-licensed. Its selected dependency graph includes permissive licenses and reviewed MPL-2.0 components (`certifi`, `orjson`, and the Windows terminal dependencies `jinxed` and `ansicon`). Its Firefox-derived browser is MPL-2.0 and includes third-party notices. Browser downloads retain upstream files unchanged; ShinBot disables optional automatic addon downloads. `browser/package-lock.json` pins agent-browser 0.41.0 under Apache-2.0. Its published native binaries bundle axe-core under MPL-2.0 and include the associated third-party license notices. Preserve the package's license files when redistributing the browser image. Chromium and Camoufox browser binaries have platform and third-party licenses separate from their Python and npm wrappers. ## Extension scanner The gateway’s security extra pins unmodified Cisco Skill Scanner 2.3.1 under Apache-2.0. The lockfile includes its complete dependency graph, including dependencies used by optional upstream analyzers. ShinBot uses its local default static analyzer in a separate process. Reviewed scanner dependencies include `pcodedmp` under GPL-3.0-or-later, `certifi` under MPL-2.0 and `tqdm` under MPL-2.0 and MIT. Keep their notices and provide corresponding source when redistributing an image, including the [pcodedmp source](https://pypi.org/project/pcodedmp/1.2.6/). LiteLLM 1.103.9’s selected distribution contains the MIT-covered package; its upstream license excludes the separate enterprise directory. Review that boundary again before upgrading. Bundled native libraries also carry notices retained in their packages. ## Documentation tools Great Docs 0.17.0 is MIT-licensed. Its selected Griffe packages use ISC. The docs-only graph also includes `fqdn` under MPL-2.0. Great Docs and its dependencies are in the `docs` development group and are not part of a normal ShinBot installation. The pinned Hatchling build backend is MIT-licensed. Its build-time dependencies include `pathspec` under MPL-2.0. Build dependencies are separate from the installed application's dependency graph. Quarto and the Quarto GitHub Action include GPL terms and are used as build tools. Generated documentation is a separate output; retain notices for any redistributed frontend assets included by the renderer. ## Platform components Linux and TigerVNC include GPL terms. Chromium contains BSD-style code and third-party components. Debian base images contain packages with their own licenses. Docker-compatible host runtimes have separate terms. These platform licenses are separate from the Python and JavaScript application audit. Docker releases request SBOM and provenance attestations. These provide a starting inventory, not a complete distribution compliance review. Review base-image and system-package licenses when changing images or preparing a downstream distribution. The optional Mac desktop backend uses Apple's unmodified Container CLI under Apache-2.0. The Linux desktop includes Xfce components under GPL/LGPL terms, xdotool under BSD-3-Clause, and scrot under its MIT-style license with an acknowledgement requirement. ShinBot uses scrot to capture desktop screenshots. Debian package copyright files remain in `/usr/share/doc`; preserve these notices and corresponding-source obligations when redistributing the desktop image. The host macOS virtualization framework has separate platform terms. ## Review a dependency change From a source checkout, collect the selected lockfile inventory: ```sh uv run python scripts/audit_dependencies.py /tmp/shinbot-dependencies.json ``` Read upstream license files for missing or ambiguous metadata. Review transitive dependencies as well as the package being added. Do not infer approval from an older experiment lockfile or remove a required dependency to make an audit pass. # Install ShinBot Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/installation.html ## Requirements Use Linux or macOS, Python 3.13 or newer, and a running Docker-compatible engine with Docker Compose v2. The Python package provides the launcher and CLI. `shinbot start` runs the application services in Docker. ## Install the release [Install uv](https://docs.astral.sh/uv/getting-started/installation/) if you do not have it, then run: ```sh uv tool install --prerelease allow shinbot shinbot start ``` To install a specific release, use `uv tool install shinbot==VERSION` with the version from the [release page](https://github.com/adarshdigievo/shinbot/releases). For a one-command launch with uv already installed: ```sh uvx --prerelease allow --from shinbot shinbot start ``` You can also use pip inside a virtual environment: ```sh python3 -m venv .venv . .venv/bin/activate python -m pip install --pre shinbot shinbot start ``` The first start pulls the versioned service images from `adarshd96/shinbot`. Published images support `linux/amd64` and `linux/arm64`. The launcher generates private service credentials and opens `http://localhost:8765` with a setup link. ## Build from source ```sh git clone https://github.com/adarshdigievo/shinbot.git cd shinbot uv run --frozen shinbot start --build ``` Use the source path when developing ShinBot. It builds the same services from `deploy/Dockerfile` instead of relying on published images. ## Headless or remote host Start without opening a browser: ```sh shinbot start --no-open-browser shinbot setup-token ``` Connect through an [SSH tunnel](31-remote-access.qmd), open Home, and paste the installation token. Treat the token as a temporary installation credential. Do not share it or include it in screenshots. ## Stop and check the services ```sh shinbot status shinbot doctor shinbot stop ``` `stop` keeps your data. The services restart after a Docker engine restart, subject to the engine starting at boot. On a laptop, jobs cannot run while the host or its container VM is asleep. Continue with [first-time setup](02-first-steps.qmd). # First-time setup Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/first-steps.html ## Create your workspace Open the address printed by `shinbot start`. A local first start includes the installation token in the setup link. If Home asks for it, run `shinbot setup-token` on the host and paste the result. Choose a password with at least 12 characters. You can reveal it while typing. Starter templates are optional; a selected template appears beside the setup form and can be removed before creating the workspace. Setup suggests your browser’s timezone. Keep it or choose another; change it later in **Settings → Workspace**. ## Connect a model Choose **Connect your model** on Home. You can provide an API key, use a supported subscription sign-in, or connect a local or OpenAI-compatible endpoint. [Model connections](03-models.qmd) explains the options. Once a model is connected, choose **Start chatting**. **Help me get started** sends a request to the selected model to help you choose a first task. That action uses your provider's allowance. ## Try a small task Start with a task you can check: > Help me plan tomorrow. Ask about my commitments first, then write a short plan in a note. Or try a browser task: > Open the project website and find its installation instructions. Tell me what you found before downloading anything. When ShinBot asks for approval, read the action and its arguments. Use Computer to watch a website, take over a step, and hand control back. ## Make the workspace comfortable Open **Settings → Appearance** to choose System, Light or Dark. System is the default and follows the device setting. The choice is saved in this browser and applies immediately. Appearance is also available before sign-in. Use the sidebar to switch between bots and recent chats. Press **Cmd K** on macOS or **Ctrl K** on Linux to search the workspace. Message drafts stay with their bot or conversation when you switch pages. # Connect models Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/models.html Choose a provider and model in **Settings → Connections**. Use a model that supports tool calling. You can connect with an API key, a supported subscription sign-in or a compatible local endpoint. ## API key Open **Settings → Connections**, select a provider, paste its key and choose **Save key**. In **Settings → Workspace**, choose the **Default provider**, **Default model** and **Default thinking effort**, then save. The thinking levels depend on the selected model. These defaults apply to new chats; existing chats keep their settings. A bot profile can override the provider and model, and the chat model picker lets you change the model and thinking effort for one conversation. Keys are kept in the private runtime volume. They are not returned to the browser after saving. Local administrators and anyone with access to the runtime volume or backups can read stored credentials. ## Subscription sign-in Connections lists sign-in buttons only for providers with a supported OAuth flow. Follow the provider's authorization page and return to ShinBot. On a remote host, finish the flow locally and paste the full callback URL when prompted. Account eligibility and usage limits depend on the provider. If sign-in fails, read the provider's error and try an API key or another model. ## Local or compatible endpoint In **Connections → Local or compatible model**, enter: | Field | Example | | --- | --- | | Provider ID | `custom-local` | | Endpoint | `http://host.docker.internal:11434/v1` | | Model name | The exact model identifier served by your endpoint | | API key | Leave blank if the endpoint does not require one | The endpoint must be reachable from the runtime container. `localhost` inside that container means the container itself. The release configuration supplies `host.docker.internal` for services running on the Docker host. ## Limits and changing models Workspace settings include a per-message token budget and a rolling 24-hour budget. Usage is checked between model calls; an in-flight call can exceed the remaining allowance. Your provider's usage records determine billing. Choose a model before starting a new conversation. Existing conversations keep their recorded configuration. If a selected provider has no saved credentials, ShinBot keeps your draft and asks you to connect it. # Conversations and approvals Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/conversations.html A conversation belongs to a bot. Open an existing conversation from Recent chats or choose **New chat** to start another. Ask for an outcome, provide relevant context, and say which actions you want to review first. ## Queue messages or steer the current task Messages sent while a bot is working wait above the message box. ShinBot processes them one at a time, in order. Each prompt enters the conversation when processing starts, followed by its response. The queue survives refreshes and service restarts. To change what the bot is doing now, write a message and choose **Steer**. You can also choose **Steer** beside a queued message. Steering takes priority over ordinary follow-ups and joins the current conversation at the next model or tool boundary. It does not stop an action already in progress or undo completed work. A pending approval still needs a decision. Use **Stop** to cancel the task and its queued messages. Steering keeps the current run’s token allowance; it does not reset an exhausted budget. ## Choose a model and thinking effort Use the controls below the message box to choose a connected model and its thinking effort. The model list supports search. Effort choices depend on the model; models without an adjustable effort show **Thinking off**. Changes stay with this conversation and apply to your next message. Wait for an active reply to finish before changing its model or effort. Open **Settings** from the picker to connect providers or manage account details. ## Watch work and approve actions ShinBot keeps responses and activity traces in conversation order. The approval control applies to the current chat: - **Auto** is the default. Routine navigation, page reading and recognized search controls proceed without repeated prompts. Destructive or unclear actions ask for a decision. Browser checks inspect the live element and its form, link and control metadata, then recheck before execution. These checks are conservative rules, not a guarantee that an arbitrary website is safe. - **Ask** requests approval before commands and browser actions. Eligible saved permissions still apply. - **Full access** runs actions without approval, including actions that can change or delete data. Choose it only for work you intend to run with that access. Human browser takeover, extension scans, plugin access restrictions and recovery holds still apply. A pending action shows its arguments and why it needs review. Choose **Allow once** or **Decline**. Actions eligible for standing permission also offer **Allow for this chat** and **Always allow**. Auto still requires a separate decision for destructive or unclear actions; a broad saved rule cannot bypass that check. A changed browser target needs another decision. Review or remove saved rules in **Settings → Permissions**, where you can also choose the default mode for new conversations. **Stop** cancels ongoing work where possible. An external action that already completed is not undone by stopping the conversation. ## Optional usage caps Token caps are off by default. In **Settings → Workspace**, leave a cap blank for unlimited use, or set a per-message or rolling 24-hour cap. Each delegated conversation has its own per-message allowance. Use the rolling 24-hour cap to limit combined usage across bots and their delegated work. These are usage guardrails, not spending guarantees: in-flight model requests can exceed the remaining allowance. Kanban cards have a run limit and an optional total token budget, which is unlimited by default. Workspace caps still apply to their runs. Model context limits and automatic compaction apply independently of usage caps. ## Prompt suggestions An empty message box offers a starter prompt or a follow-up based on the conversation. Press **Tab** while the message box is focused, or select the suggestion, to fill the draft. You can edit it before sending. **Escape** dismisses the current suggestion; **Shift+Tab** keeps its normal keyboard navigation. Suggestions use your selected model and recent conversation, with a bot-specific starter available while the model responds. They never send a message or run a tool. Model-generated suggestions are cached and count toward the workspace’s rolling 24-hour token allowance. ## Context and history Pi Durable automatically compacts model context as it fills. Older context is summarized so work can continue. The model's active context is different from the conversation history shown in ShinBot. For occasional manual use, open the conversation's **…** menu and choose **Compact now**. It is unavailable during an active task or another compaction. A progress message appears while context is being managed. Compaction can call the model and use its allowance. ## Interrupted work Closing the web app or signing out leaves submitted work running on the server. If a model connection or an internal service connection fails temporarily, ShinBot shows a waiting message and retries with increasing delays of up to 30 seconds. Saved work resumes when the connection returns, including after a service restart. Invalid credentials, exhausted account credit and other permanent errors still need your attention. **Stop** cancels waiting work too. A model connection that stops sending progress is retried after about a minute. An incomplete streamed tool call is discarded before the model retries; it does not execute as an action. Long-running commands keep running in the Computer service while ShinBot checks their saved status. ShinBot records tool actions before dispatch. If a response is lost, it checks the original action's receipt. A completed action returns its saved result; an action still executing is allowed to finish. If a service crashed during an action and its outcome is unknown, ShinBot asks you to inspect the destination instead of running it again. It cannot guarantee exactly-once effects on arbitrary websites, commands or external services. A website or plugin that reports an uncertain external operation also needs review. The host and Docker must be running for work to continue. Sleep and shutdown stop execution. Container restart policies take effect when Docker starts again; they do not keep a sleeping computer awake. Do not repeat an uncertain send or payment without checking what happened first. [Recovery](30-backups-and-upgrades.qmd) covers restored installations and held work. Message bylines show the date and time in the timezone selected in **Settings → Workspace**. Your message shows when it was sent; a completed reply shows when it finished. # Bots, groups and templates Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/bots-and-templates.html Use different bots for recurring kinds of work, such as research, writing and planning. A bot profile contains its name, description, instructions, starter prompts, model override and browser-sharing choice. Each bot has its own conversation history and saved memories. ## Create a bot On Home, choose **Create bot**. Give it a name and describe how it should help. Select a group if you want to organize it with related bots. Role and browser changes apply to new conversations. New bots receive a random colour from six options, favouring colours your other bots use least. To change it, choose **Edit** on the bot’s Home card, select a **Bot colour**, and save. The colour appears in the sidebar, profile card and chats, and stays saved across devices and restarts. Notebook pages and Computer workspace files are shared across the installation. Separate bot profiles do not create separate human accounts or filesystem sandboxes. ## Choose browser sharing | Choice | Cookies and website sign-ins | | --- | --- | | Just this bot | A private persistent browser profile for this bot | | This group | One profile shared by bots in the group | | All bots | The installation's shared browser profile | The browser service has one interactive display and serializes browser work. It opens profiles on demand and preserves their cookies when switching. A private browser profile is a separate login store, not a separate virtual machine. ## Start from a template Home lists bundled templates. Open a preview to inspect its profiles, instructions and sharing choices before importing it. Templates can describe one bot or a group of bots. The official catalog is [adarshdigievo/shinbot-official-templates](https://github.com/adarshdigievo/shinbot-official-templates). Add a personal repository with **Template repository** or: ```sh shinbot bots add-repository your-name/your-bot-templates ``` ## Share a template Use **Share template** on a bot or **Export group template** for a group. The CLI supports individual exports: ```sh shinbot bots list shinbot bots export BOT_ID ./template.json shinbot bots import ./template.json ``` Exports contain configuration, not conversations, memories, files, credentials or browser cookies. Read the instructions for private details before sharing. Imports do not grant permissions or start jobs. Access to shared sign-ins requires an explicit choice; otherwise imports use a private browser or a new group. To contribute a reusable template, see [the template authoring guide](../developers/templates.html) and submit a pull request to the official repository. ## Save a template with your bot Ask a bot to export its current profile or group, then save the result as a local template with a name and version. It asks for approval before saving. The template appears in Home under **Saved templates** and can be installed again. The export contains profile settings and instructions, not conversations, memories or account credentials. Publishing to a repository or submitting a pull request is a separate action. # Browser and files Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/browser-and-files.html ## Work in the browser When a bot browses, a small live viewer appears at the bottom of the sidebar. On a phone it appears under the top bar. It shows which bot is using the browser and the page address, and it stays visible on every page without covering your conversation. Drag the viewer to float it anywhere on screen, and use its dock button to put it back. Minimize it to keep it out of the way, or expand it to inspect the full browser. **Show browser** in the top bar restores a minimized viewer. Open **Computer** to inspect the active browser. Watching does not interrupt the bot or switch its profile. When the browser is idle, Computer opens the selected bot's profile. The browser runs on your server and keeps its sign-ins between restarts. Choose the takeover control when you need to sign in, enter information yourself or finish a step. Agent browser actions wait while you have control. Hand it back when you are ready for ShinBot to continue. Browser sharing is set in the [bot profile](11-bots-and-templates.qmd). A bot with access to a signed-in profile can act through those website accounts when permitted. ## Choose a browser Open **Settings → Browser** to choose the default backend: - **Camoufox** uses Firefox with fingerprint protection and is the default for new installations. - **Chromium** uses Playwright. Existing installations keep their saved browser choice. - **agent-browser** uses Vercel's CLI to operate Chromium. ShinBot still provides approvals, persistent profiles and the live Computer view. The installed-browser list shows which options are ready and gives installation commands for missing backends. A change applies when the next session opens. Each backend stores separate profiles, so switching does not overwrite another browser's sign-ins. Website verification and account restrictions can still apply. For a source installation, install the browser service and its default browser with: ```sh uv sync --inexact --extra browser uv run --no-sync python -m camoufox fetch official/stable/156.0.1-beta.36 ``` To use Chromium or agent-browser, also run: ```sh npm ci --prefix browser --ignore-scripts node browser/node_modules/agent-browser/scripts/postinstall.js uv run --no-sync python -m playwright install chromium ``` The npm installer requires Node.js 24 or newer. The installed agent-browser binary runs without Node. For a Python package installation, use `uv pip install 'shinbot[browser]'` in the browser service's environment, then `python -m camoufox fetch official/stable/156.0.1-beta.36`. Install the CLI with `npm install -g agent-browser@0.41.0`. A service with a restricted PATH can use `SHINBOT_AGENT_BROWSER_EXECUTABLE` to point to that executable. The Docker browser image includes Camoufox, Chromium and agent-browser. Browser files stay in the browser data volume. ## Close a browser after a task **Close the browser after a task finishes** is on by default in **Settings → Browser**. It closes the browser after a successful task and keeps saved sign-ins and profile data. Browsers under human control stay open. Failed tasks leave their browser available for inspection. Turn this setting off to leave completed work open. A bot can also use its browser's `close` action when it no longer needs the session. ## Use the Computer workspace The Computer provides commands, file tools and executable plugins in a persistent `/workspace` directory. File tools are restricted to that workspace. Commands and plugins run as an unprivileged worker and can access the workspace and outbound network. The Computer does not automatically have access to your laptop's files, host applications, gateway database or model credentials. The Docker socket is not mounted into the worker. In the standard Docker setup, browser profiles live in a separate service volume. The optional desktop backend runs both services in one Linux environment. ## Use a Linux desktop on a Mac The optional desktop backend runs a Linux desktop through Apple's `container` runtime on Apple silicon. ShinBot's Python backend stays on your Mac. The desktop contains a terminal, file manager and browser windows, and shares the bot's persistent workspace. Install [Apple Container](https://github.com/apple/container#requirements) and start it with `container system start`. From a ShinBot source checkout, build and enable the desktop: ```sh container build --target desktop -f deploy/Dockerfile -t shinbot-desktop:local . shinbot native desktop-enable --runtime "$(command -v container)" --image shinbot-desktop:local ``` Finish or pause active tasks before switching. ShinBot stops its services, backs up configuration and service data, then restarts with the desktop backend. Your workspace stays in the native data directory. Browser profiles, executor receipts and plugin files live in a persistent Apple Container volume; disabling the desktop preserves that volume. The Linux browser uses a separate profile, so sign in to websites again; your previous Mac browser profiles remain available. Open **Computer** to see the desktop. **Take control** enables keyboard and mouse input. Use **Browser**, **Files** or **Terminal** to open an application. Bot browser, desktop and workspace actions wait until you select **Hand back**. If an action is already finishing, wait and try taking control again. Ask the bot to use the `desktop` tool to inspect or interact with applications. Desktop input requires approval in Auto and Ask modes. The browser tool retains its more specific approval checks for web actions. A desktop screenshot can be attached to chat. Closing the browser returns to the desktop and keeps its saved profile. Run `shinbot native desktop-backup` while tasks are idle to save configuration, workspace and Linux service data together. Backups are stored in the native installation's `backups` directory and include credentials. Keep them private. To return to native execution: ```sh shinbot native desktop-disable ``` ShinBot saves an offline copy of the desktop service data under the native installation's `backups` directory and transfers Computer receipts and plugin files back to native storage. Browser profiles stay separate. Software installed for Linux may need its macOS equivalent when switching back. Native execution requires the permission previously granted to use your macOS account. ## Receive files in chat Ask the bot to create and attach a file, such as a CSV report or a document. Files up to 10 MB appear in the conversation with a **Download** link. Supported images also have an inline preview that opens at full size. Files remain available after refreshing the page or restarting ShinBot, even if the original workspace file changes. For browser screenshots, ask “Take a screenshot and show it here.” The bot captures the current viewport and attaches it to the chat. Screenshots remain available after the browser closes. Images from routine browser observations are for the model; they are not added to the conversation automatically. Attachment links require you to sign in to this ShinBot installation. They are not public sharing links. Bots use `attach_file` with a relative workspace path for existing files, or the browser's `screenshot` action for a page capture. ## When the view is unavailable Use **Try again**, then inspect **Settings** and run `shinbot status` or `shinbot doctor` on the host. A stopped browser service cannot provide a live view. Do not expose the browser or VNC ports directly to the internet; use the authenticated gateway. # Notes and memory Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/notes-and-memory.html Open **Notebook** for two different kinds of saved information. ## Notes Notes are editable pages shared by all bots. Create a note, give it a title and save its contents. Ask ShinBot to draft a plan, keep research findings or update an existing note. Notes persist between conversations and service restarts. From the CLI: ```sh shinbot notes list shinbot notes list --query "weekly plan" shinbot notes add "Weekly plan" "Finish the outline before Friday." ``` ## Memory Memory stores selected personal facts for the active bot, such as a writing preference or a recurring constraint. A saved fact is separate from the model's current context and from a normal notebook page. New installations let bots remember clear preferences and corrections you share. **Remember preferences and corrections I share without asking each time** is on by default in **Settings → Permissions**. Turn it off to require approval for new memories. Existing saved facts remain available until you delete them. For example, a bot can remember that you prefer short answers without a separate “remember this” request. It should tell you what it saved. Learning depends on the model calling the memory tool; a chat reply alone does not save a fact. Preference learning is separate from **reusable skills**. Bots can propose a procedure after testing it, with links to successful tool actions. A learned skill is staged as a versioned plugin for review. Activation follows your extension permissions. You can disable it or activate a previous version in Plugins. Review saved facts in the Memory tab and remove anything you no longer want the bot to use. Forgetting a fact does not erase mentions in old conversations, notes or backups. ## Storage Notes are also saved as Markdown. [Installation backups](30-backups-and-upgrades.qmd) include both notes and memories. # Scheduled jobs Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/scheduled-jobs.html Jobs run a task once or on a schedule. Open **Jobs**, choose **New job**, write the task and set its timing. You can also ask ShinBot to propose a routine; creating a schedule through the agent requires approval. ## Timing options - **Once:** run at a chosen time. - **Interval:** run repeatedly, with a minimum interval of one minute. - **Cron:** use a five-field cron expression and an IANA timezone. For weekday planning at 9am in India: ```sh shinbot jobs add "Morning planning" "Read my notes and suggest three priorities." "0 9 * * 1-5" --timezone Asia/Kolkata ``` Use `UTC`, `Europe/London`, or another valid timezone for schedules elsewhere. Consider daylight-saving changes when choosing a local time. ## Inspect and change a routine The Jobs page shows the next run and current status. Open History to inspect previous runs, pause a job to stop future runs, or edit its prompt and schedule. A job uses the task system and the same action permissions as other work; a run can wait for approval. ## Service behavior Jobs keep running after you close the web app. Keep the host, Docker engine and ShinBot services running for scheduled work to execute. Sleep and shutdown pause execution. After a backup restore, schedules are paused. Inspect the restored installation, stop the old copy, release its recovery hold, and re-enable schedules individually. When a scheduled job skips a run because its preceding task is still active or uncertain, the activity log links to that task. Resolve it before expecting the routine to run again. # Extending ShinBot Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/extending.html Add capabilities from **Plugins**, or use **Home** to create and share bot profiles. Extensions can be available to one bot or shared across your bots. ## Choose what to add | You want to | Use | | --- | --- | | Connect a service or add executable tools | A [plugin](plugins.html#find-a-plugin) or [MCP server](plugins.html#connect-an-mcp-server) | | Add a sidebar app, theme or chat shortcut | A [UI extension](../developers/plugins.html#sidebar-apps-themes-and-ui-patches) | | Add chat context, check tool calls or handle finished replies | [Lifecycle hooks](../developers/plugins.html#chat-and-tool-hooks) | | Teach a repeatable procedure or writing style | A [skill](plugins.html#install-agent-skills) | | Reuse a bot's role, prompts and browser settings | A [bot template](bots-and-templates.html#start-from-a-template) | | Save a procedure a bot has tested | A [learned skill](plugins.html#learn-from-completed-work), reviewed before activation | ## Install from a repository Open **Plugins** to browse the official marketplace, or choose **Add marketplace** to add a personal or community repository. Stage a package, review its files, configure any credentials, and activate it. Start a new conversation to use the active version. The [official plugin repository](https://github.com/adarshdigievo/shinbot-official-plugins) contains optional integrations. Each plugin has its own setup requirements. The [plugin guide](plugins.html) covers installation, MCP connections, skills and bot access. For templates, open a preview on Home and inspect the instructions and browser-sharing choices before importing. Add the [official template repository](https://github.com/adarshdigievo/shinbot-official-templates) or a repository of your own. Templates can contain an individual bot or a group. ## Ask your bot to help Describe the capability and when you will use it: > Check the marketplace for a writing-style skill. If none fits, create one that uses short paragraphs and keeps source links. Show me the files before activation. ShinBot can search marketplaces, inspect packages, and write and test tools, sidebar apps, themes and hooks before staging them for review. It can also export a bot profile and save it as a local template. Setup and activation follow your permissions; enter credentials through the Plugins settings. ## Build and share your own - [Write a plugin](../developers/plugins.html) for a skill, tool, UI contribution or workflow hook, then publish a marketplace repository. - [Publish bot templates](../developers/templates.html) for individual bots or groups, with validated profiles and a repository catalog. - [Share an existing bot](bots-and-templates.html#share-a-template) from Home or the CLI. Use your own repository for personal extensions, or submit a pull request to the official plugin or template repository. Include setup instructions, a license and a way to check that the extension works. # Plugins, MCP and skills Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/plugins.html Plugins add instructions, tools, sidebar apps, themes, chat shortcuts and automatic workflows. The official catalog is available on a new installation; no plugins are installed or staged automatically. Choose and activate the capabilities you need. ## Find a plugin Open **Plugins** to browse installed packages and marketplace catalogs. The [official plugin repository](https://github.com/adarshdigievo/shinbot-official-plugins) contains optional integrations and their setup instructions. Choose the plugins you need, review their files and configure them before activation. Add a community or personal repository through **Add marketplace** or: ```sh shinbot marketplace add your-name/your-shinbot-plugins shinbot marketplace list ``` Refreshing resolves the repository to a commit and verifies package hashes. It does not run code or replace active plugins automatically. Repository discovery currently uses public GitHub repositories; use local installation for a private package. ## Stage, review and activate 1. Stage the version you want. 2. Check the security scan, then choose **Review files** to read its findings, manifest, instructions, code, license and source information. 3. If the plugin has a **Configure** button, enter its credentials and settings. 4. Activate it. Sidebar pages and styles appear immediately; start a new conversation to use newly enabled tools and hooks. Local packages must use an ID that is not already listed in a marketplace. The installed list and configuration dialog show where each package came from. For a local package: ```sh shinbot plugins install ./my-plugin shinbot plugins activate my-plugin 1.0.0 shinbot plugins list ``` Existing conversations keep their pinned versions. Activate another installed version to roll back. `shinbot plugins disable my-plugin` also blocks further calls from existing conversations. ## Security scans ShinBot runs [Cisco Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) locally when staging marketplace packages, local plugins, imported skills and skills created by a bot. Imported and saved bot templates are scanned too. The scan uses upstream static rules and sends no extension content to a model or external scanning service. High or critical findings block activation. An unavailable, incomplete or timed-out scan also blocks activation. Open **Review files → Run scan again** to retry. Findings remain visible in Plugins. Approval rules and automatic permissions cannot bypass this check. A changed package needs a new version and scan. Scans cover ShinBot’s managed imports and activation. Computer commands have separate permissions; arbitrary commands do not pass through this scanner. A completed scan does not prove an extension is safe. Review warnings and code before granting access. MCP connection scans cover the supplied configuration and discovered tool descriptions; they cannot inspect a remote implementation or packages downloaded by its launch command. The Docker gateway includes the scanner. For a backend run directly from source, install the security extra with `uv sync --extra security`; for a directly installed Python backend, use `uv pip install 'shinbot[security]'` in that backend’s environment. ## Coding projects and parallel tasks Install and activate the optional official **Projects** plugin to add **Projects** to the sidebar. Choose **Add repository** and browse to an existing Git repository on ShinBot’s Computer. These folders are on the server, not the device running your browser. In Docker, clone repositories into `/workspace` using the Computer tools, or explicitly mount a host repository beneath `/workspace` in your Compose configuration. The repository needs at least one commit. Choose **New task**, select a bot and describe the change. ShinBot creates a branch and worktree from the repository’s committed HEAD. It does not copy uncommitted changes. Start another task to work on a second feature in parallel, including with the same bot profile. The global concurrency and token limits still apply. Open a task’s chat to prompt the bot. Select its title in Projects to inspect tracked changes, browse files, read new files and open delegated tasks. Commands and file tools start in that task’s worktree. Worktrees separate checkouts; executable tools still share the Computer environment and are not security-isolated from other worktrees. A bot with Projects access can delegate a task to another bot after your approval. The child gets a new worktree, its own conversation and permissions no broader than the requester’s. Its result returns to the requesting conversation. Each task can create up to four children, with three delegation levels and sixteen children across the workflow. Stopping the requesting task also stops active children. An archived parent receives results in its saved conversation without restarting. Use delegation for separate features, investigations or reviews with an explicit scope. New worktrees do not include the parent’s uncommitted edits, so a reviewer must be directed to inspect those files or their diff. To use an external coding CLI, install and authenticate it in the Computer environment, then ask a bot to invoke it through approved commands. **Archive worktree** removes a clean, inactive checkout and retains its branch and conversation. It refuses changed, untracked or ignored files, and files hidden from Git status. Commit or otherwise save work yourself before archiving. ShinBot does not automatically commit, push, merge or delete branches. Repositories and worktrees persist in the Computer workspace volume and are included in native backups. ## Kanban board Install and activate the optional official **Kanban** plugin first. Then use **Board → New card** for work that may need several runs. Write the goal and acceptance checks, choose a bot, and set a run limit. Token budgets are optional and off by default: leave **Total token budget** blank for no limit, or enter a cap for the entire card across its runs. Workspace usage caps still apply. Move the card to **Ready** to start. A bot can also draft cards from chat; you decide when they begin. Each run records its summary, evidence and next step. With automatic continuation enabled, the next run starts when the bot is available and budget remains. Completed work moves to **Review**, where you can inspect the evidence and conversation before marking it **Done**. A failed run, a missing requirement or an exhausted budget stops continuation. Work without a completion report also needs review. **Pause** stops a running card. Review the current action before resuming if its outcome is uncertain. Edit a paused card to change its goal or budget. Card history and budgets survive service restarts. Clearing a paused card’s token budget removes its cap without clearing its usage or history. Kanban 1.1.0 also lets bots explicitly set a card’s token budget to `0` for no limit. Token limits are checked before each generation; an in-flight model request can exceed the remaining allowance. The coordinator admits four active bot runs by default, with one active run per bot for ordinary chats and work cards. Projects tasks in separate worktrees can run concurrently with the same bot. Change **Concurrent bot runs** in Settings to suit your host. Cards wait while their bot has an active conversation or approval request. Jobs and Board work use the same permissions and daily allowance as chat. ## GitHub attention inbox Install and activate **Projects 1.1.0** in Plugins, then open **Projects → GitHub inbox → Connect GitHub**. Connect your account and select repositories or organizations to follow. Use **Manage sources** to change your selection. You can follow up to ten repositories and organizations in total. The inbox groups review requests, assignments, mentions and other activity. **New activity** means the issue has changed since you marked it seen in ShinBot. **Involved / subscribed** includes GitHub notification activity; it is not a complete inventory of your subscriptions. A fine-grained token needs Issues and Pull requests read access to its selected repositories. GitHub's notifications endpoint requires a classic token with `notifications` scope, plus `repo` for private repository activity. If that feed is unavailable, the inbox still searches repository issues and review requests and shows a warning. Use **Refresh** to check GitHub, including changes you made outside ShinBot. Merged pull requests and closed issues leave **Needs attention** and remain in **All open / activity**. Opening the inbox also refreshes a snapshot older than five minutes. Each source includes up to 100 recently updated open matches per search, with separate searches for your involvement and requested reviews. The notification feed includes up to 300 entries. Each refresh checks the current status of up to 100 items, prioritizing unresolved work. Warnings identify incomplete coverage. When a status cannot be verified, the item keeps its last known status and is labelled **Last known activity**. Open it to check GitHub directly. Bots can also refresh the inbox and read current issue or pull request details through the Projects tools. Open an issue to read its description and the first 50 comments. **Ask a bot** starts a ShinBot conversation with the issue context. **Remind me** creates a one-time job linked to the issue; the bot follows up at your chosen time while ShinBot is running. Manage or pause reminders in Jobs. **Snooze 1 day** hides an item locally until tomorrow. Marking an item seen or snoozing it does not change GitHub notifications. Posting comments or changing GitHub issues uses the separate GitHub agent-tools plugin and requires approval. Projects opens in **Workspaces**, where your repository folders, coding tasks, worktrees and file reviews appear. The **Workspaces** and **GitHub inbox** tabs stay visible in both views. Switching between them preserves your selected repository and inbox filter. ## Google Calendar Install and activate the optional **Calendar** plugin. In **Calendar → Connection settings**, enter a Google OAuth Web application client ID and client secret. Enable the Google Calendar API in that Google Cloud project and register the exact redirect URI shown in the form. Self-hosted installations need HTTPS; localhost HTTP is supported for development. If your Google consent screen is in testing mode, add your Google account as a test user; Google may expire testing refresh tokens after seven days. Select **Save and connect Google**, sign in on Google's site, and approve read-only Calendar access. Choose up to ten calendars using **Choose calendars**. The agenda includes Google events, issue reminders, and the next occurrence of enabled ShinBot jobs. Google events are expanded across the selected date range, including recurring and all-day events. Times use your browser's timezone. Event invitations, creation and editing are not supported by this read-only connection. Use **Disconnect account** to remove ShinBot's saved Google tokens. You can also revoke the application's access from your Google account. Calendar remains usable for local jobs when Google is disconnected or unavailable. ## Enter and manage secrets Open **Settings → Secrets** to find credential forms for installed plugins and native connections. Fields are masked, saved values are not returned to the browser, and secrets are not inserted into conversations. Leave a saved password field blank to keep its value; use its remove control to delete it. Integration and plugin settings are encrypted with authenticated encryption in the control service's private `secrets` directory. Existing plugin-setting files migrate when they are next opened or used. Back up the vault together with its key. A missing key stops decryption instead of creating a replacement. The vault and key are included in full installation backups, so those backups must remain private. Encryption does not protect against someone who controls the server or has both the vault and key. Native GitHub inbox and Google Calendar credentials stay in the control service. Executable plugins receive their declared settings when they run in Computer. Those plugins share a trust boundary and must be trusted with their credentials. Literal credential echoes in plugin results are redacted before the executor stores them; transformed values and malicious plugins are not a secure isolation boundary. Model-provider credentials use the runtime's separate connection storage. ## Connect an MCP server Open **Plugins → Connect MCP**. Give the connection a name and a short ID, then choose its transport: - **Local command (stdio)** runs an executable in the Computer service. Enter the command, such as `npx`, `uvx` or `python`, and its arguments as a JSON array. Use explicit package versions. The Computer image includes Node, npm, uv and Python. - **Streamable HTTP** connects to an MCP endpoint such as `https://example.com/mcp`. - **SSE** connects to a server that uses the older SSE transport. Enter credentials in the environment variables or headers field as a JSON object. For example, a remote server may need `{"Authorization":"Bearer YOUR_TOKEN"}`. Keep tokens out of the URL, command arguments and chat. OAuth sign-in for remote MCP servers is not supported yet. Choose the bots that can use the connection, then select **Connect and inspect tools**. This starts the command or contacts the endpoint to discover its tools. Review the tool list before activating the connection. Start a new chat to use it. MCP calls from direct connections require approval. Connections are short-lived: each tool call opens a new session and stdio starts a fresh process. Use servers that keep required state outside the connection or process. Tokens embedded in paths or arguments are not protected settings; use headers or environment variables instead. A connection supports up to 100 tools; large tool catalogs use more model context. ShinBot saves the discovered schemas with the connection version. If the server changes its tools or inputs, reconnect it with a new version and review the changes. Use **Configure** to replace saved credentials without changing the connection. Local commands and plugins share the Computer workspace and network access, so run code you trust. Review the server's license and dependencies before installation. ## Install Agent Skills Open **Plugins → Install skills** and paste a [Skills CLI](https://github.com/vercel-labs/skills) command: ```sh npx skills add owner/repo --skill skill-name ``` Choose the license stated by the skill author and the bots that should use it. For public GitHub sources, ShinBot resolves the repository to a commit before running its pinned, unmodified Skills CLI in the Computer service. The imported files must match that revision, and ShinBot preserves the applicable license and notice files. It stages copies of `SKILL.md` and accompanying text files for review. Installing does not run bundled scripts. Activate the skill, then start a new chat. The bot sees its description and can load its instructions and references when relevant. Use `--skill NAME` to select specific skills. A batch can contain up to 20 skills and 350 KB of text, with up to 90 files per skill. Binary files, hidden files and symlinks are not accepted. The package must include the actual upstream license text; a license name alone is insufficient. Skills with missing, conflicting or unrecognized licenses need a host review. Local imports should include the applicable repository license alongside `SKILL.md`. Keep the author's license and notice files with any skill you redistribute. You can also install a skill on your own computer and import it: ```sh npx skills add owner/repo --skill skill-name --agent codex --copy --yes shinbot plugins import-skill .agents/skills/skill-name MIT --bot BOT_ID ``` Replace `MIT` with the skill's actual license. To run the same installation through ShinBot's Computer service: ```sh shinbot plugins install-skills 'npx skills add owner/repo --skill skill-name' MIT --bot BOT_ID ``` Ask ShinBot to do this for you, for example: > Install the helpful-notes skill from my repository for this bot. Check its license and show me what it adds before activation. Ask the bot to read its plugin authoring guide before building an extension. The guide includes the current manifest schema, a working MCP example and the steps for testing, staging and activation. The bot can also write a new `SKILL.md` or plugin package, test it in Computer, stage the tested directory, and request activation. Installation and access changes initiated through its setup tools require approval. Credentials belong in the Plugins UI. ## Import from another agent Choose **Import from a link** and paste a public GitHub repository, directory or file URL. ShinBot lists portable skills and Markdown command files, identifies their license notices, and pins the preview to a commit. Choose a file and its bot access, then stage it for review. Agent Skills retain their instructions and accompanying text files. Command files become skills with a small ShinBot wrapper; the original command remains in `references/original.md`. The wrapper does not install the original agent's hooks or run shell substitutions. **Review files** includes `SHINBOT-SOURCE.json`, which records the source, revision and content hash. For a Pi extension, OpenClaw plugin or another executable format, share the link in chat and ask ShinBot to inspect its interfaces, write an adapter, and test it. Some extensions require dependencies or host capabilities that the Computer image does not provide. ShinBot can prepare that work but cannot make arbitrary code compatible automatically. For private repositories, download the package yourself and use local installation. Other website links can be inspected through the browser. All imported content remains untrusted. Review its behavior, dependencies and full license terms before activation. A recognized license notice does not audit every file in a repository. ## Learn from completed work When a bot solves a problem that is likely to recur, it can propose a skill containing the procedure and how to verify it. A proposal must cite successful tool actions from the same task. Its evidence file records action IDs and hashes without copying their arguments or results. Review the proposal in **Plugins → Review files**. It is initially available only to that bot. Activation uses the normal extension permission, and new conversations load the active version. Earlier versions remain available for rollback. Disabling a learned skill prevents the bot from automatically recreating that procedure under the same name. Learning is limited to one proposal per task and three per bot per day. Bots are instructed to save reusable methods, omit secrets and personal facts, and skip routine work. Evidence references show what the bot tested; they do not prove that the procedure is correct for every future task. Turn off **Let bots propose reusable skills** in Settings to disable this path. ## Share extensions between bots Every installed skill, packaged plugin and MCP connection has a bot-access button. Choose **All bots** or **Selected bots**. New chats select the active versions available to their bot. Existing chats keep their versions, but removing access blocks subsequent calls and skill reads immediately. ```sh shinbot plugins access my-server --bot BOT_ID shinbot plugins access skill-helpful-notes --shared ``` Bot access controls which instructions and tools ShinBot offers each bot. It does not create separate operating-system accounts or private Computer workspaces. Shell commands and executable plugins share the Computer user account; approved code can inspect other processes running under that account, including plugin credentials in use. Install executable code you trust and grant commands the same level of trust. Credentials for a shared connection refer to the same account. Create separate connection IDs when bots need different accounts. ## Connect GitHub Stage **GitHub 1.0.0** from the official catalog, then choose **Configure**. Enter a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) and the repositories you want to connect, separated by commas, such as `your-name/project, your-name/notes`. Restrict the token to those repositories. Use **Contents: Read**, **Issues: Read** and **Pull requests: Read** for browsing. Give Issues or Pull requests write access only if you want ShinBot to create or update those items. Organization approval may be required. GitHub documents the [permissions for each REST endpoint](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens). Save, activate the plugin, and start a new conversation. Try: > Check my GitHub connection, then summarize the open issues in your-name/project. The plugin can read repository details, text files, issue conversations and pull-request changes. It can create issues, add comments, close or reopen issues, and create pull requests from existing branches. Writes ask for approval even with automatic Computer access, unless you saved an approval for that exact tool request. New pull requests default to drafts. It does not push commits, merge changes or delete repositories. You can also configure it from the host without putting the token in shell history: ```sh shinbot plugins configure github 1.0.0 ``` Credentials are saved in private files in the gateway’s data directory and passed to the selected plugin process when it runs. They are not shown in chat or returned by the settings API. Executable plugins share the Computer environment, so install only code you trust. Include the gateway data volume in backups and protect those backups as credentials. A saved token stays unchanged when its field is left blank. Use **Remove saved GitHub token** to clear it. If GitHub denies access, check the token’s expiration, selected repositories, permissions and organization approval. If GitHub does not confirm a write, ShinBot pauses the task for inspection. Check GitHub before resolving the uncertain action or trying again. A plugin installed from a different marketplace or changed local package needs its credentials entered again. ## Telegram plugin The optional official [Telegram plugin](telegram.html) lets you chat with your bots from Telegram. Follow its setup guide to connect a BotFather bot and your private chat. ## Ask ShinBot to extend itself For example: > Check the installed plugins and marketplace for a writing-style skill. If none fits, draft one that uses short paragraphs and checks claims. Show me the files before activation. ShinBot can create, test and stage skills or plugins using its tools. Executable activation requires the extension and Computer permissions. New capabilities are loaded into new conversations. ## Add and share bot templates Templates save a bot's role, instructions, starter prompts, model choice and browser-sharing settings. Use Home to preview a template, import a bot or group, or export a setup you want to share. See [Bots, groups and templates](bots-and-templates.html#start-from-a-template) for importing and sharing, and [Publish bot templates](../developers/templates.html) for the repository format and validation commands. ## Understand executable access Skill packages supply instructions and load on demand. MCP plugins execute code in the Computer service, with workspace and outbound network access. They do not receive mounted gateway databases, provider credentials, browser profiles or the Docker socket. A manifest's permission description is not an independent per-plugin network sandbox. Packaged Python MCP plugins use the installed Python and MCP dependencies. Direct command connections can also use Node, npm and uv in Computer; review any packages they download. Adding dependencies to a packaged Python plugin still requires a reviewed runner image and license audit. See [Build a plugin](../developers/plugins.html) for the supported manifest and runner contract. ## Apps, themes and automatic workflows A custom plugin can add a sidebar page such as Paint, style ShinBot with a theme, or add a button beside the chat controls. Ask your bot to build one, test it and stage it for review, or install a package from a trusted marketplace. The bot can read ShinBot's plugin SDK through its built-in help. Plugins can also run hooks before a chat, before or after a tool call, and after a reply. These can add context, check a proposed action or record a finished workflow. Hooks run automatically with Computer access once you enable the plugin. The setup screen lists their events and permissions. Choose **All bots** or **Selected bots** to control where an extension is available. UI contributions follow the selected bot; tools and hooks follow the conversation's pinned version. Disable a plugin from Plugins to remove its pages and styles and stop future hook calls. Plugin data remains available when you enable it again. UI plugins have access to the signed-in app, so review their source before enabling them. If a plugin breaks the interface, open ShinBot with `?extensions=off` at the end of its root URL, then disable the plugin in Plugins. Reload normally after fixing or rolling back its version. This recovery option skips UI plugins only; disable the package to stop its hooks and tools too. # Telegram plugin Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/telegram.html The official Telegram plugin lets you chat with your ShinBot profiles from a private Telegram chat. Set it up when you want this connection. It runs as a separate service and uses your existing bots, model settings and permissions. ## Configure the connection 1. Create a Telegram bot with [BotFather](https://t.me/BotFather). 2. Obtain your numeric Telegram user ID. 3. On the ShinBot host, run: ```sh shinbot telegram-setup ``` The interactive command asks for the bot token and owner ID, verifies the Telegram bot, then starts the connector. Use a dedicated BotFather bot without an existing webhook. From a source checkout, use `uv run shinbot telegram-setup --build`. Keep the token private. Only the configured owner ID can use this connector. Model requests still use your configured provider and task permissions. ## Chat with your bots Open the Telegram link printed by setup and send `/start`. Only your configured private chat is accepted. Group chats and messages from other users are ignored. | Command | What it does | | --- | --- | | `/start` or `/help` | Show the available commands | | `/bots` | List your ShinBot profiles and their IDs | | `/bot NAME` or `/bot ID` | Switch profiles; your next message starts a new conversation | | `/new` | Start a new conversation with the selected profile | | `/status` | Show the selected bot and conversation status | Send an ordinary text message to work with the selected bot. Profile selection survives connector restarts. These conversations use the same model settings, saved memories and permissions as the web app. When an action needs approval, Telegram sends a link to your ShinBot instance. Photos, attachments and voice messages are not supported. Scheduled jobs with notifications enabled also send their results to your configured private chat. Long replies are split into multiple messages without truncating the answer. To stop the connection without deleting history or settings: ```sh shinbot telegram-stop ``` ## Delivery and recovery Conversations and complete replies remain available in the web app. If delivery fails or its outcome is uncertain, check the Telegram chat before sending the message again. ShinBot preserves delivery records across restarts. Changing the connected Telegram account stops pending delivery to the old account. If messages stop arriving, run `shinbot status` and inspect the connector logs. # Data, backups and upgrades Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/backups-and-upgrades.html ## Where data lives | Location | Contents | | --- | --- | | `~/.shinbot` or `SHINBOT_HOME` | Launcher settings, connection details and service credentials | | `control-data` volume | SQLite task history, bots, notes, memories, jobs and plugin records | | `runtime-data` volume | Pi conversation state and provider credentials | | `computer-data` volume | Executor records and installed executable packages | | `workspace` volume | Files the Computer works with | | `browser-data` volume | Persistent browser profiles, cookies and sign-ins | The volume names are prefixed by the saved Compose project. Removing or reinstalling the Python package does not delete these locations. Keep the same OS account, `SHINBOT_HOME` and Docker context to reconnect to the same installation. The launcher rejects a changed engine or missing saved data volume instead of silently starting with empty data. ## Back up ```sh shinbot backup /safe/location/shinbot.tar.gz shinbot backup-info /safe/location/shinbot.tar.gz ``` Backup briefly stops the running services, saves all five volumes and restarts those services. It includes bots, preferences, learned skills, installed plugins and their versions, plugin settings and secrets, provider credentials, browser sign-ins, files and host deployment settings. CLI login sessions are excluded. The archive stores release metadata, but does not embed Docker images or the Python package. Keep a matching release available for a move to another host. Local update rollbacks use the retained Docker images. The archive uses owner-only permissions and checksums. It is **not encrypted**. Store it privately on another disk or host so it survives loss of this machine. `backup-info` checks the archive without changing the installation or printing credentials. Archives from older ShinBot versions remain readable, but those archives contain volumes only. ## Upgrade with a restore point The launcher records the running release when you run `shinbot start`. Do this once before upgrading an existing launcher that has not recorded a release yet. Open **Settings → Updates** to see the installed gateway version, the latest verified stable release and release notes. ShinBot checks GitHub and PyPI daily; turn off **Check for updates daily** to use manual checks only. A missing release, network failure or publication still in progress appears as its own state. Checking never installs anything or sends your chats and settings. On the installation host, check without making changes: ```sh shinbot update --check ``` To check, upgrade the launcher and apply the matching service release: ```sh shinbot update --latest ``` This command supports uv tool installations and Python virtual environments. It checks the host's Python compatibility and installs the exact verified version using uv, or pip when uv is unavailable in a venv. It keeps the services running while the launcher and images are downloaded. It does not automatically downgrade. Run it in the host terminal, not a bot's Computer workspace. Copy the command from **Settings → Updates**. For other package-manager installations, upgrade the launcher with that manager, then run `shinbot update`. A uv tool installation can also use: ```sh uv tool upgrade shinbot shinbot update ``` For pip, upgrade in the same environment with `python -m pip install --upgrade shinbot`, then run `shinbot update`. Use the package manager's prerelease option if you deliberately use a prerelease version. `shinbot update` applies the service images selected by the installed Python package. It: 1. Downloads the images before stopping the current services. A failed download leaves the current services running. 2. Saves a complete backup under `SHINBOT_HOME/backups` and retains the previous images locally. 3. Starts the new services with automated work held and checks the gateway, runtime, Computer and Browser. 4. Enables normal operation after those checks pass. If startup fails, it restores the previous images, configuration and data. For a source installation, update the checkout and run `uv run --frozen shinbot update --build`. Use `--timeout 300` if this host needs more than the default 120 seconds for each health check. Updating never removes your named volumes. The health check verifies service readiness, not every provider or plugin. Test your usual workflows after an update. Keep enough free disk space for the full backup and both releases. Do not prune retained Docker images while you need their rollback checkpoint. ## Roll back ```sh shinbot rollback ``` Rollback runs from the host CLI and does not need the web app, a model provider or an Internet connection. It returns to the last update's saved release **and data**. It first backs up work created after a successful update so that you can recover it separately. Older restore points remain in `SHINBOT_HOME/backups`; use `shinbot backup-info` to inspect them. If the host stops during an update, `shinbot start` reports the incomplete operation. Run `shinbot rollback` to finish recovery. If Docker or the disk is unavailable, resolve that problem and retry the same command. The checkpoint stays on disk until recovery completes. Running rollback again after success leaves the restored data alone. A rollback restores the services, not the Python package installed by uv or pip. It keeps a private Compose snapshot so subsequent starts use the restored services. Install a corrected launcher and run `shinbot update` when you are ready to try another release. ## Restore a backup ```sh shinbot restore /safe/location/shinbot.tar.gz --replace ``` Restore validates the archive before stopping services and saves the current state in `SHINBOT_HOME/backups`. It restores persistent data and plugin settings while preserving this destination's Docker engine, project, ports, public address and service credentials. The archive also contains the original deployment settings for reference; they are not blindly applied to another host. Restore revokes sessions, pauses schedules and changes the installation's execution identity. Sign in and inspect Recovery in Settings. Stop any old copy of the installation before releasing the recovery hold. Review uncertain actions and re-enable schedules individually. This also applies after an automatic update fallback or a manual rollback. ### Move to a new host 1. Install the same ShinBot version that created the backup, along with Docker and Compose. 2. Run `shinbot start --no-open-browser` on the destination to create its deployment and volumes. You do not need to claim this empty installation. 3. Copy the archive privately and run `shinbot restore /path/to/shinbot.tar.gz --replace`. 4. Sign in with the restored account's password. Check conversations, plugins, files, provider access and browser profiles. Restart any optional plugin services you want to use on the new host, following their setup guides. 5. Stop the old installation, inspect Recovery in Settings, release the hold and re-enable the schedules you want. Keep the original backup until you have checked the destination. An older package may not understand data written by a newer release. Use a matching release and backup when restoring or downgrading. # Remote access and permissions Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/remote-access.html ## Use an SSH tunnel The gateway binds to loopback by default. On your local computer: ```sh ssh -N -L 8765:127.0.0.1:8765 user@your-server ``` Open `http://localhost:8765`. The browser interface talks to the remote installation through the tunnel. Only the host's SSH service needs remote exposure. ## Use an HTTPS reverse proxy Set `SHINBOT_ORIGIN` in the host's `~/.shinbot/deploy.env` to the exact public HTTPS origin. Adjust `SHINBOT_BIND` deliberately if the proxy needs a different bind address. Run `shinbot start` after changes. The proxy must forward WebSocket connections and avoid buffering event streams. Expose only the gateway. Keep the runtime, Computer, browser and VNC services on private container networks. Do not use an unauthenticated proxy to bypass the gateway's login or origin checks. ## Authentication Browser sessions use HttpOnly cookies and origin checks. CLI sessions use bearer tokens. **Settings → Accounts → Sign out all devices** revokes both kinds of session. A local administrator can read container volumes, so host access remains part of the security boundary. ## Standing permissions Settings separates command execution, browser interaction and extension activation. Keep approvals enabled while learning what a bot or plugin does. Executable plugins have workspace and network access; browser permission can act through accounts you have signed into. ShinBot is a single-owner application. Giving another person the workspace password gives them access to that owner's workspace, not a restricted team account. # Troubleshooting Source: https://adarshdigievo.github.io/shinbot/docs/user-guide/troubleshooting.html Start with `shinbot status` and `shinbot doctor` on the installation host. Keep error messages when reporting a problem, but remove API keys, tokens, callback URLs and private conversation content. ## Docker is unavailable Start your container engine and check that Docker Compose v2 is installed. On macOS, wait for the container VM to finish starting. Use the same Docker context that originally held your data. ## The launcher reports a changed engine or missing volume Do not delete `deploy.env` to silence the error. Switch back to the original Docker context or restore a backup. The check prevents an empty replacement installation from appearing to have lost your conversations. ## Home asks for an installation token Run `shinbot setup-token` on the host. Paste that value into Home. A setup link supplied by a normal local first start includes it automatically. ## A model is unavailable Check the selected provider and model in Settings. Add credentials in Connections or finish the supported sign-in flow. For a local model, test whether its endpoint is reachable from the runtime container; the host's `localhost` is not the runtime container's `localhost`. ## Computer cannot show the browser Retry the view and check the browser service. Keep its VNC and internal API ports private. If the page loads through a reverse proxy but live view fails, check WebSocket forwarding. ## A job did not run Check its enabled state, timezone, next run and history. Confirm the host and Docker VM were awake. A restored installation pauses jobs until you release recovery and re-enable them. An active run may be waiting for approval. ## A plugin is not available in a conversation Confirm it is activated and start a new conversation. Existing conversations retain their pinned plugin versions. Review validation errors for an invalid manifest, unexpected MCP tools or files missing from the package list. ## Report an issue Include the ShinBot version, OS, Docker engine/context, installation method and exact steps. Say whether the failure happened in the UI, CLI or a scheduled run. Use [GitHub issues](https://github.com/adarshdigievo/shinbot/issues) for reproducible bugs. Do not attach a full backup; it contains credentials and private data. # Meet ShinBot Source: https://adarshdigievo.github.io/shinbot/docs/index.html ShinBot is a personal assistant that runs on your own server. Use it to research questions, work with files, navigate websites, keep notes and run routines. Give each bot a role, choose its model and decide which browser sign-ins it can share. ShinBot supports one owner with multiple bot profiles. Choose a capable model with tool calling. ## Start here 1. [Install ShinBot](user-guide/installation.html) with Python and Docker. 2. [Create your workspace and connect a model](user-guide/first-steps.html). 3. [Start a conversation](user-guide/conversations.html) and approve an action when needed. ## What you can do | Capability | Where to use it | | --- | --- | | Research, plan and work with files | [Chat](user-guide/conversations.html), with a model of your choice | | Use websites and keep sign-ins | [Computer](user-guide/browser-and-files.html), with takeover and handback | | Create specialist assistants | [Bots and templates](user-guide/bots-and-templates.html), including shared groups | | Keep notes and selected personal facts | [Notebook](user-guide/notes-and-memory.html) | | Run one-time or recurring work | [Jobs](user-guide/scheduled-jobs.html), including cron and timezones | | Use the terminal | [CLI reference](reference/cli.html), connected to the same gateway | ## Extend ShinBot Add tools and connections through plugins, teach reusable procedures with skills, or share a bot setup as a template. Start with [Extending ShinBot](user-guide/extending.html) to choose what you need. - [Install plugins, connect MCP servers and add skills](user-guide/plugins.html). - [Import and share bot templates](user-guide/bots-and-templates.html#start-from-a-template). - [Write a plugin](developers/plugins.html) or [publish a template repository](developers/templates.html). Browse the [official plugin marketplace](https://github.com/adarshdigievo/shinbot-official-plugins) for optional integrations. ## What stays on your server Conversations, notes, workspace files, browser profiles and saved credentials persist in your installation. Reinstalling the Python package does not delete them. Your model provider receives the prompts, tool results and other content needed for its requests. Websites and plugins receive data when you use them. [Backups and upgrades](user-guide/backups-and-upgrades.html) explains where data lives and how to move an installation. [Remote access](user-guide/remote-access.html) explains the recommended SSH tunnel and HTTPS options. [ShinBot website](https://adarshdigievo.github.io/shinbot/) · [Source code](https://github.com/adarshdigievo/shinbot) · [Releases](https://github.com/adarshdigievo/shinbot/releases)