Running a Copilot bot

See Copilot agents for runtime requirements, supported prompt options and events, and current limitations.

InstallCopy link to heading

Use Node 24 LTS (verified with 24.16.0 on Linux x64). The package requires at least Node 22.13.0 for the shared SQLite store; minimum versions and other platforms have not been verified. The distribution artifact is the npm tarball. No Copilot-specific container image is provided in v1.

Until a release publishes this package, install the prepared tarball:

npm install /absolute/path/to/octostaff-copilot-scuba-0.7.2.tgz
mkdir -p ~/.bubble/copilot-scuba
cp node_modules/@octostaff/copilot-scuba/dist/config.example.yaml ~/.bubble/copilot-scuba/config.yaml
npx --no-install copilot-scuba --help

After publication, npm install @octostaff/copilot-scuba installs the same package layout. Normal npm installation must include optional dependencies: the pinned SDK selects its platform-specific runtime package. It does not require a global Copilot CLI, a separate Copilot login, or an umbrella checkout. Do not override the binary with a different CLI version.

ConfigurationCopy link to heading

Copy config.example.yaml to ~/.bubble/copilot-scuba/config.yaml, set the referenced environment variables, then run copilot-scuba. Use --config <file> for another JSON/YAML file, --cwd <directory> to override broker.copilot.cwd, or --help. An optional .env is loaded from the process working directory. The shared BUBBLE_HOME/legacy OCTOSTAFF_HOME rules apply.

Durable sessionsCopy link to heading

The CLI stores Octostaff checkpoints and backend session IDs in <Bubble home>/copilot-scuba/db.sqlite (unless store.path is supplied; relative paths follow the config directory). Native Copilot transcripts live in <Bubble home>/copilot-scuba/copilot, overridable with broker.copilot.baseDirectory. Preserve both locations to resume after restart. The programmatic runtime uses an in-memory Octostaff store unless store.path is set. Relative working-directory and Copilot data paths resolve against the process working directory; omitted cwd uses that directory. Each principal and thread gets its own backend session. Stopping aborts and disconnects handles, without deleting transcripts. A missing native transcript starts a fresh session; authentication, corruption and transport errors preserve the stored ID and fail attachment. Restart the bot after an unexpected backend exit. The native runtime does not persist a session until its first turn; an unused session is safely replaced on the next launch.

Session controlsCopy link to heading

The bot advertises three commands in each thread:

• /model <id> changes the model for the next turn, preserving native history. A bare /model reports the current model. BYOK model IDs are supplied by the operator; the adapter does not claim a verified model catalog. Invalid IDs may be rejected by the runtime or by the provider on the next turn.
• /cd <directory> disconnects and resumes the same native conversation in the new directory. Relative paths resolve against the current workspace; ~ expands to the bot host's home. The directory must exist. A bare /cd reports the workspace.
• /clear starts a fresh native conversation. It preserves the Octostaff delivery checkpoint, so settled messages are not sent again. It takes no argument.

Changes apply only while the bot is idle. During a turn, wait for completion or interrupt it, then retry. Commands report failure instead of claiming an unapplied setting; a failed workspace change attempts to restore the old session. If cleanup or restoration cannot be confirmed, restart the bot. Overrides are thread-local and live for the bot process: restart returns model and workspace to configuration defaults while resuming the saved conversation. Advertisements are updated after successful changes and withdrawn on stop.

Interrupt cancels native work and pending interactions. New chat input during a run queues for the next turn; in-flight steering is unsupported. Native CLI command passthrough, plan/autopilot modes and smart drain are not exposed. Thread titles use native title events and the shared first-title policy, preserving an existing user or peer title.

CredentialsCopy link to heading

Octostaff credentials and provider credentials are separate. Provider fields accept the shared { env: NAME } references. The child receives only process-launch environment variables, never the Octostaff token or ambient credentials. Only the explicit OpenAI-compatible HTTP provider is enabled; its key goes through the SDK session configuration. Configuration and backend error payloads are not logged by this adapter.

EmbeddingCopy link to heading

For embedding, import createCopilotBotRuntime and pass { config }, then call start(), wait() and stop(). One runtime owns one Copilot process and the shared amphibian runtime owns Octostaff supervision, draining and persistence.

TroubleshootingCopy link to heading

• Cannot launch the runtime: reinstall with optional dependencies enabled and check that the SDK's platform package is present. SDK 1.0.14 bundles runtime 1.0.85/protocol 3. A missing platform binary fails startup; the connector never downloads an unpinned substitute.
• Authentication or model errors: verify the Octostaff token grants access to the intended thread, and separately verify the explicit provider URL, key, Responses/Chat Completions choice and model ID. GitHub-hosted subscription authentication is not supported by this adapter yet.
• No threads or replies: invite/grant the bot principal to the thread. Supply an existing, accessible workspace; after a backend transport failure, restart the process.
• Lost context after moving hosts: preserve both the Octostaff SQLite store and native state directory. /clear intentionally starts fresh native context; missing transcripts recover with fresh context while preserving settled Octostaff input.
• A tool waits or fails: approval and question responses must match the active request; provider tools require the advertised provider to remain available. Requests expire after 60 seconds. Interrupt settles pending requests; late answers cannot revive them.

Approved native shell and file tools run with the operating-system permissions of the bot process. Octostaff grants control Octostaff data access, not host filesystem access.