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.8

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.8
File Size Uploaded Provenance Actions
optio_opencode-0.6.8.tar.gz 130.5 kB Without provenance Details for optio_opencode-0.6.8.tar.gz

Built distribution (wheel)

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

Total release size: 196.7 kB

Release files / optio_opencode-0.6.8.tar.gz

Download URL optio_opencode-0.6.8.tar.gz
Size 130.5 kB
Tags Source
SHA-256 checksum
How to use checksums
56c9066f508a484afcf43970ff461d5fa5c35074ad8f9a08e4301e0f2191fa50
BLAKE2b-256 checksum
How to use checksums
330931d5052c7d6833f63184e9f90f3e90fae906e4bb648b34b1cfad305d5148
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.8-py3-none-any.whl

Download URL optio_opencode-0.6.8-py3-none-any.whl
Size 66.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7b771cb9064cf36fae506df1dba895a2e597f8bbc3d4bb310ae7999798c5a2e1
BLAKE2b-256 checksum
How to use checksums
ffdf42397f9fbf833f190eca6e7a5d8b7b166d08fd0c72df35dbe9a82897c5f4
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.8

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