Skip to main contentClaim $5 in free credit — one-time, per account. Claim $5 free
Krova CloudKrova Cloud

Python SDK

The official Python SDK for Krova Cloud: create and manage Cubes, run commands and move files over the Cube's own SSH, and hand an agent its own machine through LangChain, CrewAI or the OpenAI Agents SDK.

The krova package is the official Python client for Krova Cloud. Create a Cube, wait until it's running, run commands on it, move files in and out, and hand the same connection to an agent as three tools. The source is MIT licensed and public at github.com/krovacloud/krova-python.

Install

Python 3.11 or newer. Install a release straight from GitHub by tag, and replace v0.1.2 with the release you want.

pip install "krova @ git+https://github.com/krovacloud/krova-python@v0.1.2"

Every release also attaches its wheel and source archive to the GitHub Release, with a SHA256SUMS file, if you would rather install the wheel directly or check the hash first.

Authenticate

Create an API key from Settings → API keys (see API keys) and export it with your space id. The client reads both from the environment, or you can pass api_key and space_id yourself. It reads an optional KROVA_BASE_URL too, and uses https://krova.cloud when you set nothing.

export KROVA_API_KEY=kro_...
export KROVA_SPACE_ID=...

Quickstart

Create a Cube, wait for it to boot, print its SSH details, then delete it. image is an id from the images catalog; ubuntu-24.04 below is a placeholder for one of them.

from krova import Krova

with Krova() as krova:
    cube = krova.cubes.create(
        name="agent-box",
        image="ubuntu-24.04",
        vcpu=2,
        ram_gb=4,
        disk_gb=40,
        ssh_public_key=open("id_ed25519.pub").read().strip(),
    )
    cube.wait_until_running(timeout=300)

    ssh = cube.ssh()
    print(f"ssh {ssh.user}@{ssh.host} -p {ssh.port}")

    cube.delete()

The other calls are krova.cubes.get(id), krova.cubes.list(), krova.cubes.delete(id), krova.cubes.power_off(id) and krova.cubes.ssh(id). Rename a Cube with krova.cubes.rename(id, name), resize it with krova.cubes.resize(id, vcpu=..., ram_gb=..., disk_gb=...), and set its idle auto-stop with krova.cubes.set_idle_timeout(id, minutes). Each is also a method on the cube you already hold.

resize changes only the sizes you pass and returns the queued job; disk can only grow. Idle auto-stop powers a Cube off after the idle minutes you set (10 to 10080) and keeps its disk. Pass idle_timeout_minutes=30 to create to set it from the start, or None to set_idle_timeout to turn it off. A Cube now carries idle_timeout_minutes and last_active_at.

Run commands and move files

Commands and files go over the Cube's own SSH, with the private key that matches the ssh_public_key you gave the Cube. Open a connection with connect, and it closes when the block ends.

with krova.cubes.connect(cube.id, private_key=open("id_ed25519").read()) as shell:
    result = shell.run(["git", "status"], cwd="/srv/app", env={"CI": "1"}, timeout=60)
    print(result.exit_code, result.stdout, result.stderr)

    shell.files.write("/srv/app/.env", "MODE=prod\n")
    data = shell.files.read("/srv/app/.env")
    shell.files.upload("build.tar.gz", "/tmp/build.tar.gz")
    shell.files.download("/var/log/app.log", "app.log")

run takes a string, which the Cube's shell runs as written, or a list, where each item is quoted as one argument. The cwd and env values are quoted for you. A non-zero exit code comes back in exit_code and doesn't raise an error; a command that outlasts timeout raises RunTimeoutError. File paths are used as written, so ~ isn't expanded.

private_key is an OpenSSH or PEM string (Ed25519, ECDSA or RSA) or a paramiko.PKey, and passphrase= covers an encrypted key. The SDK uses only the key you pass, never your SSH agent or ~/.ssh.

Every connection checks the Cube's host keys, which Krova provides through the API. If the server presents any other key, or the Cube has no keys yet because it's still booting, the SDK raises HostKeyMismatchError and sends nothing. Pass host_keys=[...] to use keys you already hold.

Give an agent a Cube

An agent gets three tools bound to one open connection: krova_run runs a shell command and returns the exit code, stdout and stderr, krova_read_file reads a text file, and krova_write_file writes one. A failure comes back as text starting with Error:, so the model can react to it. Output is cut at 32 KB for each of stdout, stderr and a file read, and the result says when it was; pass max_output_bytes= to krova_tools to change that.

Commands run as the user you connected with, so the agent can do anything that user can on the Cube. Give each agent a Cube of its own, and close the connection when the run ends. Each framework is an optional extra:

pip install "krova[langchain] @ git+https://github.com/krovacloud/krova-python@v0.1.2"
pip install "krova[crewai] @ git+https://github.com/krovacloud/krova-python@v0.1.2"
pip install "krova[openai-agents] @ git+https://github.com/krovacloud/krova-python@v0.1.2"

krova[crewai] and krova[openai-agents] need different openai major versions, so install one of the two in a given environment.

# LangChain
from krova.integrations.langchain import krova_tools

with krova.cubes.connect(cube.id, private_key=key) as shell:
    tools = krova_tools(shell)  # a list of BaseTool, for example model.bind_tools(tools)

# CrewAI
from crewai import Agent
from krova.integrations.crewai import krova_tools

with krova.cubes.connect(cube.id, private_key=key) as shell:
    coder = Agent(role="Engineer", goal="Fix the build", backstory="...", tools=krova_tools(shell))

# OpenAI Agents SDK
from agents import Agent, Runner
from krova.integrations.openai_agents import krova_tools

with krova.cubes.connect(cube.id, private_key=key) as shell:
    agent = Agent(name="Engineer", instructions="Fix the build.", tools=krova_tools(shell))
    result = Runner.run_sync(agent, "Run the tests in /srv/app")

On the TypeScript side, @krovacloud/ai-sdk gives the same three tools to the Vercel AI SDK. See the TypeScript SDK page.

Errors

A failed call raises krova.KrovaError with status, code, message and request_id; quote the request id when you contact support. Deleting a Cube that has termination protection on raises it with status 409 and code termination_protected. wait_until_running raises WaitTimeoutError on timeout, and CubeFailedError if the Cube ends up in error, deleted, stopped or stopping. Those, HostKeyMismatchError, PrivateKeyError and RunTimeoutError are all subclasses of KrovaError.

Next steps

  • API keys — create the key the SDK authenticates with.
  • TypeScript SDK — the same API from Node.js, with typed helpers for domains, snapshots, backups and webhooks.
  • CLI — the same API from your terminal.
  • AI agents — why a Cube suits an agent, and what it costs.