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

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.2
File Size Uploaded Provenance Actions
optio_opencode-0.6.2.tar.gz 125.6 kB Without provenance Details for optio_opencode-0.6.2.tar.gz

Built distribution (wheel)

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

Total release size: 191.0 kB

Release files / optio_opencode-0.6.2.tar.gz

Download URL optio_opencode-0.6.2.tar.gz
Size 125.6 kB
Tags Source
SHA-256 checksum
How to use checksums
4f851c509a85a8d9a146834c2c3614b4fc445dcf95232ef363a712ce6add6aa0
BLAKE2b-256 checksum
How to use checksums
bf92594bf80f62c14e1362933844ae33ad83d1254f448216b9f866f4eb703fc4
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.2-py3-none-any.whl

Download URL optio_opencode-0.6.2-py3-none-any.whl
Size 65.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
34de5ca13a0d3b1bbbf54fc13c0c5dde98f3528228bd1a5f794fcd074b65a9aa
BLAKE2b-256 checksum
How to use checksums
951ac964bbaa8bd4b17763deaa37aceb35dbff0d1b6973e8197babcbf08b9465
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.2

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