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

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.5
File Size Uploaded Provenance Actions
optio_opencode-0.6.5.tar.gz 127.8 kB Without provenance Details for optio_opencode-0.6.5.tar.gz

Built distribution (wheel)

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

Total release size: 193.8 kB

Release files / optio_opencode-0.6.5.tar.gz

Download URL optio_opencode-0.6.5.tar.gz
Size 127.8 kB
Tags Source
SHA-256 checksum
How to use checksums
6bc8a07d21130214376d9c26f51d2086f21162d93942e53b6cb19eebb3cfec09
BLAKE2b-256 checksum
How to use checksums
c86271119926a0d6594745005732b70da26c754a3436bcd4ef5b7fa6f72fb9ab
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.5-py3-none-any.whl

Download URL optio_opencode-0.6.5-py3-none-any.whl
Size 66.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0662e1fd93732839e842eb75112a169bc8503d7e033d720d1dce70c5c0c88d2c
BLAKE2b-256 checksum
How to use checksums
e4bd74d14f514a215d2e0cda21da4a6430fb080ccae3684191fd0326bfa04b36
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.5

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