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

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.9
File Size Uploaded Provenance Actions
optio_opencode-0.6.9.tar.gz 131.8 kB Without provenance Details for optio_opencode-0.6.9.tar.gz

Built distribution (wheel)

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

Total release size: 198.2 kB

Release files / optio_opencode-0.6.9.tar.gz

Download URL optio_opencode-0.6.9.tar.gz
Size 131.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c9d7959fc731b1fdc29cd2bfd247e9885c76418596565629d47f14cad863b5c9
BLAKE2b-256 checksum
How to use checksums
4d4ff6290051fa481d677249a26eb47d1424b774a91df6f7581da730b7b569fa
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.9-py3-none-any.whl

Download URL optio_opencode-0.6.9-py3-none-any.whl
Size 66.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
823e5815b231c5915e220bd669d9e994fc895de2a1ca3d5e4b3c13d03b51af55
BLAKE2b-256 checksum
How to use checksums
ab1625be11f03059419cf1511e9e370d73bcb91cbc30cff0750d08c1d2bcdf5e
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.9

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