ruos

Ultra-lite Python client for ruOS: your cloud desktops, ruOS Lite browsers, and the hosted ruOS MCP tools, from Python.

The library is a single compiled Rust extension (PyO3, abi3 wheels for Python 3.8+). It has no Python dependencies, uses rustls (no OpenSSL), and releases the GIL during every network call.

pip install ruos

Sign in

The Python package has no login flow of its own. Use one of these:

1. npx ruos login, which stores tokens in ~/.config/ruos/credentials.json (mode 0600; $RUOS_CONFIG_DIR or $XDG_CONFIG_HOME/ruos if set). The Python client reads the same file and refreshes the access token automatically. On refresh it writes the file back in the format npx ruos expects (version: 1, expires_at in epoch milliseconds, all other fields kept), so one login covers both tools.
2. Set RUOS_TOKEN to an access token or a tenant API token (ruos_mcp_…, minted in the dashboard).
3. Pass Client(token="...").

Precedence is token=, then RUOS_TOKEN, then the credentials file. Only file-based credentials are refreshed.

Use

import ruos

c = ruos.Client()

c.whoami()          # {"tier": "pro", "token_source": "credentials_file", "plan": {...}, ...}
c.desktops()        # [{"machine_id": "...", "name": "dev", "state": "started", ...}, ...]
c.lite()            # saved ruOS Lite browsers ([] if none)

c.start("dev")      # by machine id, Fly id, name or display name; or "lite"
c.stop("dev")

c.tools()           # hosted MCP tools/list
c.call("desktop_status")                       # hosted MCP tools/call
c.call("desktop_exec", machine_id="...", command="uname -a")

png_or_jpeg = c.screenshot()                   # machine="lite" by default
open("screen.jpg", "wb").write(png_or_jpeg)

c.act("lite", "click", x=640, y=360)
c.act("lite", "type", text="hello")
c.act("lite", "key", keys="ctrl+l")

print(ruos.__version__)

act takes these actions: mouse_move, click, double_click, drag, scroll, type, key, cursor_position, screen_size. Its keyword arguments are x, y, to_x, to_y, button, direction, amount, text and keys. Anything else raises ValueError before a request is sent.

Jobs

A job is a command that runs detached on a desktop for up to six hours. Its output stays on the desktop, and you read it by byte offset (ADR-105).

job = c.jobs_start("dev", "cargo test --workspace", timeout=3600)
job["job_id"], job["idempotency_key"]          # retry with key=... to get the same job

for chunk in c.jobs_follow(job["job_id"]):     # bytes, until the job ends
    sys.stdout.buffer.write(chunk)

p = c.jobs_poll(job["job_id"], offset=0, wait_ms=25000)
p["chunk"], p["next_offset"], p["state"], p["exit_code"]

c.jobs_list()                                  # newest first; or jobs_list("dev")
c.jobs_cancel(job["job_id"])

The command must be one line. jobs_start refuses ruOS Lite. A reused key with a different command raises RuosError (HTTP 409). More than 4 active jobs raises RateLimited. An unknown job id raises NotFound. jobs_follow releases the GIL while it long-polls. It polls every second while output flows and backs off to every 10 s when it does not. Its job attribute holds the final state and exit_code.

Options

ruos.Client(
    token=None,              # explicit bearer
    base_url=None,           # default: $RUOS_BASE_URL or https://ruos.cognitum.one
    credentials_path=None,   # default: ~/.config/ruos/credentials.json
    timeout=None,            # seconds, default 60
)

Errors

Every API error is a ruos.RuosError:

Invalid arguments raise ValueError or TypeError. Tokens never appear in exception messages or repr(Client).

Notes

• whoami() reports the tenant's plan and where the token came from. ruOS does not yet have a route that returns your identity.
• The hosted MCP endpoint (/mcp) is stateless Streamable HTTP. The client sends each JSON-RPC request on its own and accepts both SSE and JSON replies.
• Source: packages/ruos-py. Design: ADR-100.

License: MIT OR Apache-2.0.