Skip to main content

optio-opencode

Run opencode web as an optio task — local subprocess or remote over SSH — with opencode's UI reachable through optio's UI components.

What it does

Given an OpencodeTaskConfig (workdir contents, prompt, deliverable callback), optio-opencode:

  1. Provisions a fresh workdir on the chosen host (local or remote).
  2. Writes AGENTS.md (base prompt + your instructions) and opencode.json (your config) into it.
  3. Installs the opencode binary if missing (remote mode only).
  4. Launches opencode web with a random auth password.
  5. Registers the opencode UI as a widget that optio's UI components can embed via the widget proxy — SSH tunnel hidden from optio-api.
  6. Tails a log file the LLM writes to and translates structured lines into optio events:
    • STATUS: … → ctx.report_progress(percent, message)
    • DELIVERABLE: <path> → fetches the file, invokes your on_deliverable callback
    • DONE [summary] → clean completion
    • ERROR [message] → failure
  7. Cleans up workdir and SSH connection on teardown.

The same OpencodeTaskConfig works for local and remote modes; only SSHConfig differs.

When to use it

You want an opencode-driven assistant session as a managed optio task — surfaced through optio's UI, with progress reporting and file deliverables — without writing the host management, log parsing, or widget plumbing yourself.

Installation

pip install optio-opencode

Python 3.11+. Depends on optio-core, optio-host, and asyncssh.

Minimal example

from optio_opencode import create_opencode_task, OpencodeTaskConfig
from optio_host import SSHConfig

config = OpencodeTaskConfig(
    workdir_files={"AGENTS.md": "Do the thing.", "opencode.json": "{...}"},
    on_deliverable=lambda ctx, path, text: print(f"got {path}: {len(text)} bytes"),
    ssh=SSHConfig(host="worker-1", user="optio", key_path="~/.ssh/id_optio"),
)

task = create_opencode_task(config)
# Schedule / run via optio-core as usual.

Set ssh=None for local subprocess mode.

Messages

  • use_client_messages (bool, default False) — enable the CLIENT_MESSAGE: log keyword: the agent can push {keyword, data} messages to the browser session that launched the task (surfaced via optio-ui's onClientMessage).
  • on_caller_message (async callback, default None) — enable the CALLER_MESSAGE: log keyword: the agent can push {keyword, data} messages to your application. Signature (hook_ctx, keyword, data) -> str | None; a non-None return is sent back to the agent as feedback. Keywords that are not enabled are absent from both the parser and the agent-facing protocol documentation.

License

Apache-2.0.

Metadata

Release files for optio-opencode 0.6.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for optio-opencode 0.6.3
File Size Uploaded Provenance Actions
optio_opencode-0.6.3.tar.gz 125.6 kB Without provenance Details for optio_opencode-0.6.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for optio-opencode 0.6.3
File Interpreter ABI Platform Actions
optio_opencode-0.6.3-py3-none-any.whl Python 3 none any Details for optio_opencode-0.6.3-py3-none-any.whl

Total release size: 191.1 kB

Release files / optio_opencode-0.6.3.tar.gz

Download URL optio_opencode-0.6.3.tar.gz
Size 125.6 kB
Tags Source
SHA-256 checksum
How to use checksums
200909783c34ee87d9224e4126972c64569ec60ffd8461efb2abc67398ed97dd
BLAKE2b-256 checksum
How to use checksums
fc83452a4843d71df05dda84f27fea8321c725cbc994047f8cebb97c11fc8cd0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / optio_opencode-0.6.3-py3-none-any.whl

Download URL optio_opencode-0.6.3-py3-none-any.whl
Size 65.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4cd43519fd8b36e48f22ac412baec9c3975358eb2b40dbfcd1599189bcd84d41
BLAKE2b-256 checksum
How to use checksums
618eca7b0a8d7efaee17c6ddd2fb38f24f70901094fa1fd4f5c7382bef10a416
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for optio-opencode 0.6.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page