Use Undercurrent from Python

The aixand-undercurrent-sdk package provides an async Python 3.11+ client for starting local terminal sessions, delivering input, reading output, observing state, and stopping processes. Import it as undercurrent. These pages describe release 0.1.0-beta in this checkout. Python packaging normalizes that same release to 0.1.0b0. Use the daemon and uc-python-bridge built from the same revision.

Python owns the connection and observation helpers. The external daemon owns sessions, durable state, and process supervision. Closing a client detaches; stopping a session is an explicit operation. Application success, agent identity, credentials, and workflow budgets remain the caller's responsibility.

await client.stop(session_id, graceful_only=True) requests a graceful stop without automatic forced escalation. It requires a daemon supporting the graceful_only stop field and cannot be combined with force=True. Inspect or wait for terminal lifecycle before treating a process as stopped; a timeout does not establish termination.

Choose a reading path

Setup and examples

Follow the Linux quickstart to install the package, select matching native executables, and start an isolated daemon. Installing the Python package alone does not install Rust binaries.

The maintained input round trip demonstrates async with Client(), starting a child, an application acknowledgment, output pagination, and cleanup. Wait for state, observe a session, and copy retained output without changing its process.

The API does not start a daemon, compile a bridge, or replay a failed mutation automatically. Preserve session IDs and delivery IDs and follow the operation-specific recovery rules. The repository overview and Rust SDK orientation provide wider context.

Connection ownership

This diagram shows the runtime boundaries relevant to a Python caller.

%%{init: {"flowchart": {"useMaxWidth": false}}}%%
flowchart TD
    accTitle: Python client context
    accDescr: An asyncio application communicates with its child bridge over standard IO. The bridge uses the public Rust SDK to reach the external daemon over authenticated local IPC. The daemon supervises sessions independently of the Python connection.
    P[Python application and<br/>async Client] -->|private JSON lines over<br/>stdio| B[uc-python-bridge child]
    B -->|public Rust SDK and<br/>authenticated local IPC| D[uc-daemon]
    D -->|supervises through<br/>runtime| S[Managed terminal<br/>sessions]
    D -->|owns durable records| R[(Runtime home)]

The bridge is a client adapter; neither the Python package nor its bridge embeds the daemon or reads its database. See the maintainer source map.