API reference

# pip install trove-sdk
from trove_sdk import TroveClient

client = TroveClient(api_key="trove-sk-...", namespace="my-agent")

# Write a file
client.write("workspace/notes.md", "# Notes")

# Run any shell command — returns stdout, raises TroveExecError on
# non-zero exit. Use exec_detailed() if you'd rather inspect the
# exit code than catch.
print(client.exec("ls -la workspace/"))

# Simple case: returns stdout as a string. Raises TroveExecError on
# non-zero exit (carries exit_code, stdout, stderr) so a failing
# command never silently looks like normal output.
output = client.exec('grep -r "TODO" workspace/')
print(output)

# Want to inspect the exit code without an exception? Use exec_detailed —
# returns ExecResult(exit_code, stdout, stderr, duration_ms).
result = client.exec_detailed("pytest tests/")
if result.exit_code != 0:
    print("failures on stderr:", result.stderr)

result = client.write("workspace/notes.md", "# Notes\n...")
print(result.path, result.size_bytes)

with open("report.pdf", "rb") as f:
    result = client.upload("workspace/report.pdf", f)
print(result.size_bytes)

client.delete("workspace/notes.md")

import anthropic
from trove_sdk import TroveClient

trove = TroveClient(api_key="trove-sk-...", namespace="session-123")
client = anthropic.Anthropic()

tools = [{
    "name": "bash",
    "description": "Run a shell command in the agent's filesystem.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

def run_agent(prompt: str) -> str:
    messages = [{"role": "user", "content": prompt}]
    while True:
        resp = client.messages.create(
            model="claude-opus-4-7",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
        if resp.stop_reason == "end_turn":
            return next(b.text for b in resp.content if hasattr(b, "text"))
        for block in resp.content:
            if block.type == "tool_use" and block.name == "bash":
                # exec_detailed gives us a structured result so a non-zero
                # exit doesn't get blended into stdout when we hand it back
                # to the model.
                r = trove.exec_detailed(block.input["command"])
                tool_output = r.stdout if r.exit_code == 0 else (
                    f"[exit {r.exit_code}]\n{r.stderr}".rstrip()
                )
                messages += [
                    {"role": "assistant", "content": resp.content},
                    {"role": "user", "content": [{
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": tool_output,
                        "is_error": r.exit_code != 0,
                    }]},
                ]

from trove_sdk import TroveAdminClient, TroveClient

# ── On customer signup (your backend, never the browser) ──────────────────────
admin = TroveAdminClient(
    api_key=TROVE_ADMIN_KEY,        # your long-lived admin key
    workspace_id=TROVE_WORKSPACE_ID,
)

key = admin.create_key(
    f"customer-{customer_id}",
    namespace=f"customer-{customer_id}",
)
# Store key.key_id in your DB — you'll need it to revoke
# Give key.api_key to the backend service running this customer's agent

# ── Customer agent ────────────────────────────────────────────────────────────
# Scoped key auto-defaults X-Namespace — namespace arg here is optional
trove = TroveClient(api_key=customer_key, namespace=f"customer-{customer_id}")

trove.write("workspace/memory/prefs.md", "prefers bullet points")
trove.exec("cat workspace/memory/prefs.md")

# ── On churn / account deletion ───────────────────────────────────────────────
admin.revoke_key(stored_key_id)
# Any request using that key immediately returns 401

# provision.py — backend, holds the admin key
import os
from trove_sdk import TroveAdminClient

admin = TroveAdminClient(
    api_key=os.environ["TROVE_ADMIN_KEY"],     # never leaves your backend
    workspace_id=os.environ["TROVE_WORKSPACE_ID"],
)

def start_session(session_id: str) -> dict:
    """Mint a throwaway key bound to this session's namespace."""
    namespace = f"session-{session_id}"
    key = admin.create_key(name=f"agent:{session_id}", namespace=namespace)
    # Persist key.key_id with your session record — you'll need it to revoke
    return {"namespace": namespace, "key_id": key.key_id, "api_key": key.api_key}

def end_session(key_id: str) -> None:
    """Revoke. In-flight requests with this key now return 401."""
    admin.revoke_key(key_id)