Skip to content

Commit 8528cef

Browse files
usus
committed
docs(sdk): add README files for Python and TypeScript SDKs
Add comprehensive README.md to both SDK packages with quick start examples, storage/snapshot usage, feature lists, and cost story. Also bump SDK versions to 0.0.6 and add PyPI metadata (classifiers, keywords, project URLs).
1 parent c1c32ca commit 8528cef

5 files changed

Lines changed: 242 additions & 3 deletions

File tree

‎sdk/python/README.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# den-sdk
2+
3+
Python SDK for [Den](https://github.com/us/den) — the self-hosted sandbox runtime for AI agents.
4+
5+
> **100 sandboxes on E2B = ~$600/hour. 100 sandboxes on Den = one $5/month server.**
6+
7+
## Installation
8+
9+
```bash
10+
pip install den-sdk
11+
# or
12+
uv add den-sdk
13+
```
14+
15+
## Quick Start
16+
17+
```python
18+
from den import Den
19+
20+
client = Den("http://localhost:8080", api_key="your-key")
21+
22+
# Create a sandbox
23+
sandbox = client.create(image="ubuntu:22.04")
24+
25+
# Execute a command
26+
result = sandbox.exec(["python3", "-c", "print('Hello from Den!')"])
27+
print(result.stdout) # Hello from Den!
28+
29+
# Read/write files
30+
sandbox.write_file("/tmp/hello.py", "print('hello world')")
31+
content = sandbox.read_file("/tmp/hello.py")
32+
33+
# Clean up
34+
sandbox.destroy()
35+
```
36+
37+
## Async Support
38+
39+
```python
40+
import asyncio
41+
from den import Den
42+
43+
async def main():
44+
client = Den("http://localhost:8080", api_key="your-key")
45+
46+
sandbox = await client.acreate(image="ubuntu:22.04")
47+
result = await sandbox.aexec(["echo", "async works!"])
48+
print(result.stdout)
49+
await sandbox.adestroy()
50+
51+
asyncio.run(main())
52+
```
53+
54+
## Storage
55+
56+
```python
57+
from den import Den, SandboxConfig, StorageConfig, VolumeMount
58+
59+
client = Den("http://localhost:8080")
60+
61+
# Persistent volume
62+
sandbox = client.create(
63+
image="ubuntu:22.04",
64+
storage=StorageConfig(
65+
volumes=[VolumeMount(name="my-data", mount_path="/data")]
66+
),
67+
)
68+
69+
# S3 import/export
70+
sandbox.s3_import(
71+
bucket="my-bucket",
72+
key="data/input.csv",
73+
dest_path="/home/sandbox/input.csv",
74+
)
75+
76+
sandbox.s3_export(
77+
source_path="/home/sandbox/output.csv",
78+
bucket="my-bucket",
79+
key="results/output.csv",
80+
)
81+
```
82+
83+
## Snapshots
84+
85+
```python
86+
# Save state
87+
snapshot = sandbox.snapshot(name="after-setup")
88+
89+
# Restore later
90+
restored = client.restore_snapshot(snapshot.id)
91+
```
92+
93+
## Features
94+
95+
- Sandbox lifecycle management (create, list, get, stop, destroy)
96+
- Command execution with timeout and environment variables
97+
- File operations (read, write, list, mkdir, delete, upload, download)
98+
- Persistent volumes, shared volumes, tmpfs configuration
99+
- S3 integration (hooks, on-demand, FUSE)
100+
- Snapshot/restore
101+
- Port forwarding
102+
- Async support via `httpx`
103+
- Type-safe with Pydantic models
104+
105+
## Requirements
106+
107+
- Python >= 3.10
108+
- Den server running (see [Den repo](https://github.com/us/den))
109+
110+
## License
111+
112+
MIT

‎sdk/python/pyproject.toml‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,29 @@ build-backend = "hatchling.build"
44

55
[project]
66
name = "den-sdk"
7-
version = "0.0.5"
7+
version = "0.0.6"
88
description = "Python SDK for the Den sandbox API"
9+
readme = "README.md"
910
license = "MIT"
1011
requires-python = ">=3.10"
12+
keywords = ["den", "sandbox", "sdk", "docker", "ai", "code-execution"]
13+
classifiers = [
14+
"Development Status :: 3 - Alpha",
15+
"Intended Audience :: Developers",
16+
"License :: OSI Approved :: MIT License",
17+
"Programming Language :: Python :: 3",
18+
"Programming Language :: Python :: 3.10",
19+
"Programming Language :: Python :: 3.11",
20+
"Programming Language :: Python :: 3.12",
21+
"Programming Language :: Python :: 3.13",
22+
"Topic :: Software Development :: Libraries",
23+
]
24+
25+
[project.urls]
26+
Homepage = "https://github.com/us/den"
27+
Repository = "https://github.com/us/den"
28+
Documentation = "https://github.com/us/den/tree/main/sdk/python"
29+
Issues = "https://github.com/us/den/issues"
1130
dependencies = [
1231
"httpx>=0.27.0",
1332
"pydantic>=2.0.0",

‎sdk/python/src/den/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,4 +53,4 @@
5353
"VolumeMount",
5454
]
5555

56-
__version__ = "0.0.2"
56+
__version__ = "0.0.6"

‎sdk/typescript/README.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# @us4/den
2+
3+
TypeScript SDK for [Den](https://github.com/us/den) — the self-hosted sandbox runtime for AI agents.
4+
5+
> **100 sandboxes on E2B = ~$600/hour. 100 sandboxes on Den = one $5/month server.**
6+
7+
## Installation
8+
9+
```bash
10+
bun add @us4/den
11+
# or
12+
npm install @us4/den
13+
```
14+
15+
## Quick Start
16+
17+
```typescript
18+
import { Den } from "@us4/den";
19+
20+
const client = new Den("http://localhost:8080", { apiKey: "your-key" });
21+
22+
// Create a sandbox
23+
const sandbox = await client.create({ image: "ubuntu:22.04" });
24+
25+
// Execute a command
26+
const result = await sandbox.exec(["python3", "-c", "print('Hello from Den!')"]);
27+
console.log(result.stdout); // Hello from Den!
28+
29+
// Read/write files
30+
await sandbox.writeFile("/tmp/hello.py", "print('hello world')");
31+
const content = await sandbox.readFile("/tmp/hello.py");
32+
33+
// Clean up
34+
await sandbox.destroy();
35+
```
36+
37+
## Storage
38+
39+
```typescript
40+
import { Den } from "@us4/den";
41+
42+
const client = new Den("http://localhost:8080");
43+
44+
// Persistent volume
45+
const sandbox = await client.create({
46+
image: "ubuntu:22.04",
47+
storage: {
48+
volumes: [{ name: "my-data", mountPath: "/data" }],
49+
},
50+
});
51+
52+
// S3 import/export
53+
await sandbox.s3Import({
54+
bucket: "my-bucket",
55+
key: "data/input.csv",
56+
destPath: "/home/sandbox/input.csv",
57+
});
58+
59+
await sandbox.s3Export({
60+
sourcePath: "/home/sandbox/output.csv",
61+
bucket: "my-bucket",
62+
key: "results/output.csv",
63+
});
64+
```
65+
66+
## Snapshots
67+
68+
```typescript
69+
// Save state
70+
const snapshot = await sandbox.snapshot("after-setup");
71+
72+
// Restore later
73+
const restored = await client.restoreSnapshot(snapshot.id);
74+
```
75+
76+
## WebSocket Streaming
77+
78+
```typescript
79+
// Stream command output in real-time
80+
const stream = await sandbox.execStream(["python3", "long_script.py"]);
81+
82+
for await (const message of stream) {
83+
if (message.type === "stdout") process.stdout.write(message.data);
84+
if (message.type === "stderr") process.stderr.write(message.data);
85+
if (message.type === "exit") console.log(`Exit code: ${message.data}`);
86+
}
87+
```
88+
89+
## Features
90+
91+
- Sandbox lifecycle management (create, list, get, stop, destroy)
92+
- Command execution with timeout and environment variables
93+
- WebSocket streaming for real-time output
94+
- File operations (read, write, list, mkdir, delete, upload, download)
95+
- Persistent volumes, shared volumes, tmpfs configuration
96+
- S3 integration (hooks, on-demand, FUSE)
97+
- Snapshot/restore
98+
- Port forwarding
99+
- Full TypeScript types
100+
101+
## Requirements
102+
103+
- Node.js >= 18 or Bun
104+
- Den server running (see [Den repo](https://github.com/us/den))
105+
106+
## License
107+
108+
MIT

‎sdk/typescript/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@us4/den",
3-
"version": "0.0.5",
3+
"version": "0.0.6",
44
"description": "TypeScript SDK for the Den sandbox API",
55
"main": "dist/index.js",
66
"types": "dist/index.d.ts",

0 commit comments

Comments
 (0)