toolkami 0.1.4

Python gRPC client for the local toolkami daemon

toolkami

Python gRPC client for the local toolkami daemon.

Install

pip install toolkami

The packaged distribution downloads the matching Linux x64 daemon and guest-agent from the GitHub release for the package version on first client start. Repository checkouts use the local Cargo debug binary.

Usage

from toolkami import Client

client = Client.open(tcp_address="127.0.0.1:50061")
print(client.get_version().version)
print(client.ping("python").message)
client.close()

Daemon Launch and NBD Permissions

The daemon now requires read/write access to NBD block devices (/dev/nbd*).

• Default behavior: Client.open(...) reuses an existing daemon at tcp_address; if not found, it auto-launches one.
• If your user lacks NBD permissions, auto-launch fails with an actionable error.
• To disable auto-launch and only connect to an already-running daemon:

client = Client.open(tcp_address="127.0.0.1:50061", auto_launch=False)

• To explicitly opt into privileged launch:

client = Client.open(tcp_address="127.0.0.1:50061", use_sudo=True)

Spawn/Restore with Folder Mounts

from toolkami import Client
from toolkami.v1.image_pb2 import BuildRequest
from toolkami.v1.instance_pb2 import FolderMount, RestoreRequest, SpawnRequest
from toolkami.v1.snapshot_pb2 import SnapshotRequest

client = Client.open(tcp_address="127.0.0.1:50061")

image = client.build(
    BuildRequest(
        dockerfile_text="FROM ubuntu:24.04\nWORKDIR /workspace",
        dockerfile_bytes_max=64_000,
    )
)
spawned = client.spawn(
    SpawnRequest(
        image_id=image.image_id,
        mounts=[
            FolderMount(
                source_host_path="/abs/path/to/repo",
                target_path="/workspace/repo",
                # access_mode defaults to read-only when omitted
            )
        ],
    )
)
snap = client.snapshot(SnapshotRequest(instance_id=spawned.instance_id))
restored = client.restore(
    RestoreRequest(
        snapshot_id=snap.snapshot_id,
        mounts=[
            FolderMount(
                source_host_path="/abs/path/to/repo",
                target_path="/workspace/repo",
            )
        ],
    )
)
print(restored.instance_id)
client.close()

Development

make proto-generate
make test
make release-build
make integration-smoke-local