Metadata-Version: 2.4
Name: hotcell
Version: 0.1.16
Summary: Python client for the hotcell self-hostable agent sandbox daemon
License: Apache-2.0
Project-URL: Homepage, https://hotcell.sh
Project-URL: Repository, https://github.com/sinameraji/hotcell
Keywords: sandbox,ai-agents,hotcell
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# hotcell (Python SDK)

Dependency-free Python client for the [hotcell](https://github.com/sinameraji/hotcell)
self-hostable agent sandbox daemon. Mirrors the TypeScript SDK surface (snake_cased)
so the same workflows work from either language.

```python
from hotcell import HotcellClient

client = HotcellClient(endpoint="http://127.0.0.1:4750")  # or $HOTCELL_ENDPOINT
sandbox = client.get_sandbox()                          # create a fresh sandbox

# run a command
result = sandbox.exec("python3 -c 'print(2 + 2)'")
print(result.stdout, result.exit_code)                  # "4\n" 0

# files
sandbox.write_file("/workspace/hi.txt", "hello")
print(sandbox.read_file("/workspace/hi.txt"))           # "hello"

# stateful code interpreter
ctx = sandbox.create_code_context(language="python")
ctx.run_code("x = 21")
print(ctx.run_code("x * 2").results[0].text)            # "42"

# metrics + cost
m = sandbox.metrics()
print(m.cost.total, m.usage.cpu_seconds)

sandbox.destroy()
```

Standard library only (`urllib`, `json`) — no third-party dependencies. Requires
Python ≥ 3.9 and a running hotcell daemon.

## Surface

`HotcellClient`: `get_sandbox`, `list`, `health`, `info`, `list_backups`, `delete_backup`.

`Sandbox`: `exec`, `exec_stream`, `stop`, `start`, `destroy`, `metrics`,
`write_file`, `read_file`, `mkdir`, `list_files`, `watch`, `start_process`,
`list_processes`, `kill_process`, `stream_logs`, `wait_for_port`, `expose_port`,
`unexpose_port`, `list_exposed_ports`, `set_env_vars`, `get_env_vars`,
`create_session`, `list_sessions`, `create_backup`, `restore_backup`,
`list_backups`, `create_code_context`, `list_code_contexts`, `run_code`.

`Session`: `exec`, `exec_stream`, `set_env_vars`, `destroy`.
`CodeContext`: `run_code`, `destroy`.
