orble-sdk 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
orble/__init__.py
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
"""Orble: Linux boxes for agents, from Python. https://orble.tech/docs"""
|
|
2
|
+
import base64
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
import sys
|
|
6
|
+
import time
|
|
7
|
+
import urllib.error
|
|
8
|
+
import urllib.parse
|
|
9
|
+
import urllib.request
|
|
10
|
+
|
|
11
|
+
__version__ = "0.1.0"
|
|
12
|
+
__all__ = ["Box", "Error", "Result", "Snapshot", "boxes", "create", "snapshots"]
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class Error(Exception):
|
|
16
|
+
"""A request Orble refused or couldn't answer: status is the HTTP status (0 when no answer came)."""
|
|
17
|
+
|
|
18
|
+
def __init__(self, status, message):
|
|
19
|
+
super().__init__(f"{status}: {message}" if status else message)
|
|
20
|
+
self.status, self.message = status, message
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class Result:
|
|
24
|
+
"""What a command did: its exit code and output (the last 64 KiB of each stream)."""
|
|
25
|
+
|
|
26
|
+
def __init__(self, code, stdout, stderr, timed_out=False):
|
|
27
|
+
self.code, self.stdout, self.stderr, self.timed_out = code, stdout, stderr, timed_out
|
|
28
|
+
|
|
29
|
+
def __repr__(self):
|
|
30
|
+
return f"Result(code={self.code}, stdout={self.stdout!r}, stderr={self.stderr!r})"
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _config_dir():
|
|
34
|
+
if sys.platform == "darwin":
|
|
35
|
+
return os.path.expanduser("~/Library/Application Support/orble")
|
|
36
|
+
if os.name == "nt":
|
|
37
|
+
return os.path.join(os.environ.get("APPDATA", ""), "orble")
|
|
38
|
+
return os.path.join(os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config"), "orble")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class Client:
|
|
42
|
+
"""Talks to Orble's API. The key comes from ORBLE_API_KEY, or else from the orble CLI's sign-in."""
|
|
43
|
+
|
|
44
|
+
def __init__(self, key=None, url=None):
|
|
45
|
+
cli = {}
|
|
46
|
+
try:
|
|
47
|
+
with open(os.path.join(_config_dir(), "config.json")) as f:
|
|
48
|
+
cli = json.load(f)
|
|
49
|
+
except (OSError, ValueError):
|
|
50
|
+
pass
|
|
51
|
+
self.key = key or os.environ.get("ORBLE_API_KEY") or cli.get("token")
|
|
52
|
+
self.url = (url or os.environ.get("ORBLE_API_URL") or cli.get("api") or "https://orble.tech").rstrip("/")
|
|
53
|
+
if not self.key:
|
|
54
|
+
raise Error(0, "no API key: set ORBLE_API_KEY, or sign in with `orble login`")
|
|
55
|
+
|
|
56
|
+
def call(self, method, path, body=None, raw=None, timeout=660):
|
|
57
|
+
data, headers = None, {"Authorization": "Bearer " + self.key, "User-Agent": "orble-python/" + __version__}
|
|
58
|
+
if raw is not None:
|
|
59
|
+
data, headers["Content-Type"] = raw, "application/octet-stream"
|
|
60
|
+
elif body is not None:
|
|
61
|
+
data, headers["Content-Type"] = json.dumps(body).encode(), "application/json"
|
|
62
|
+
req = urllib.request.Request(self.url + path, data=data, method=method, headers=headers)
|
|
63
|
+
try:
|
|
64
|
+
with urllib.request.urlopen(req, timeout=timeout) as r:
|
|
65
|
+
text = r.read()
|
|
66
|
+
except urllib.error.HTTPError as e:
|
|
67
|
+
msg = e.read().decode(errors="replace")
|
|
68
|
+
try:
|
|
69
|
+
msg = json.loads(msg).get("error") or msg
|
|
70
|
+
except ValueError:
|
|
71
|
+
pass
|
|
72
|
+
raise Error(e.code, msg.strip() or e.reason) from None
|
|
73
|
+
except urllib.error.URLError as e:
|
|
74
|
+
raise Error(0, f"can't reach {self.url}: {e.reason}") from None
|
|
75
|
+
return json.loads(text) if text else {}
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
_default = None
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _client():
|
|
82
|
+
global _default
|
|
83
|
+
if _default is None:
|
|
84
|
+
_default = Client()
|
|
85
|
+
return _default
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _q(s):
|
|
89
|
+
return urllib.parse.quote(s, safe="")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
class Box:
|
|
93
|
+
"""A box, by name. Box("api") is an existing one; create() makes a new one."""
|
|
94
|
+
|
|
95
|
+
def __init__(self, name, client=None, info=None):
|
|
96
|
+
self.name, self._c, self.info = name, client or _client(), info or {}
|
|
97
|
+
|
|
98
|
+
def __repr__(self):
|
|
99
|
+
return f"Box({self.name!r})"
|
|
100
|
+
|
|
101
|
+
def _call(self, method, sub="", body=None, **kw):
|
|
102
|
+
return self._c.call(method, f"/v1/boxes/{_q(self.name)}{sub}", body, **kw)
|
|
103
|
+
|
|
104
|
+
def exec(self, command, timeout=None, env=None, cwd=None):
|
|
105
|
+
"""Run a shell command as the user agent, from /home/agent unless cwd says otherwise, and wait for it."""
|
|
106
|
+
body = {"command": command}
|
|
107
|
+
if timeout:
|
|
108
|
+
body["timeout_s"] = int(timeout)
|
|
109
|
+
if env:
|
|
110
|
+
body["env"] = env
|
|
111
|
+
if cwd:
|
|
112
|
+
body["cwd"] = cwd
|
|
113
|
+
r = self._call("POST", "/exec", body)
|
|
114
|
+
while r.get("running"): # a command still running after 50 s: wait for it again
|
|
115
|
+
r = self._call("POST", "/exec", {"job": r["job"]})
|
|
116
|
+
return Result(r.get("exit_code"), r.get("stdout", ""), r.get("stderr", ""), r.get("timed_out", False))
|
|
117
|
+
|
|
118
|
+
def read(self, path, binary=False):
|
|
119
|
+
"""A file's content: text, or bytes with binary=True. Relative paths start at /home/agent."""
|
|
120
|
+
out, offset = b"", 0
|
|
121
|
+
while True:
|
|
122
|
+
r = self._call("GET", f"/files?path={_q(path)}&offset={offset}")
|
|
123
|
+
part = r["content"].encode() if r["encoding"] == "utf-8" else base64.b64decode(r["content"])
|
|
124
|
+
out += part
|
|
125
|
+
offset += r["bytes"]
|
|
126
|
+
if not part or offset >= r["size"]:
|
|
127
|
+
return out if binary else out.decode()
|
|
128
|
+
|
|
129
|
+
def write(self, path, content):
|
|
130
|
+
"""Write a file (text or bytes), replacing it, with any missing directories."""
|
|
131
|
+
data = content.encode() if isinstance(content, str) else bytes(content)
|
|
132
|
+
self._call("PUT", f"/files?path={_q(path)}", raw=data)
|
|
133
|
+
|
|
134
|
+
def port(self, port, public=False):
|
|
135
|
+
"""Share a port at its own https address and return it. Private ports open for your account only."""
|
|
136
|
+
return self._call("PUT", f"/ports/{int(port)}", {"access": "public" if public else "private"})["url"]
|
|
137
|
+
|
|
138
|
+
def fork(self, count=1):
|
|
139
|
+
"""Copies of the box as it is now, memory and running programs included."""
|
|
140
|
+
r = self._call("POST", "/fork", {"count": count})
|
|
141
|
+
if r.get("errors") and not r.get("boxes"):
|
|
142
|
+
raise Error(0, "; ".join(r["errors"]))
|
|
143
|
+
return [Box(b["name"], self._c, b) for b in r.get("boxes", [])]
|
|
144
|
+
|
|
145
|
+
def snapshot(self, name=None):
|
|
146
|
+
"""Save the box as a snapshot, to make new boxes from later."""
|
|
147
|
+
r = self._call("POST", "/snapshot", {"name": name} if name else {})
|
|
148
|
+
return Snapshot(r["name"], self._c, r)
|
|
149
|
+
|
|
150
|
+
def suspend(self):
|
|
151
|
+
self.info = self._call("POST", "/suspend")
|
|
152
|
+
|
|
153
|
+
def resume(self):
|
|
154
|
+
self.info = self._call("POST", "/resume")
|
|
155
|
+
|
|
156
|
+
def delete(self):
|
|
157
|
+
self._call("DELETE")
|
|
158
|
+
|
|
159
|
+
def refresh(self):
|
|
160
|
+
self.info = self._call("GET")
|
|
161
|
+
return self.info
|
|
162
|
+
|
|
163
|
+
@property
|
|
164
|
+
def state(self):
|
|
165
|
+
return self.refresh()["state"]
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
class Snapshot:
|
|
169
|
+
def __init__(self, name, client=None, info=None):
|
|
170
|
+
self.name, self._c, self.info = name, client or _client(), info or {}
|
|
171
|
+
|
|
172
|
+
def __repr__(self):
|
|
173
|
+
return f"Snapshot({self.name!r})"
|
|
174
|
+
|
|
175
|
+
def delete(self):
|
|
176
|
+
self._c.call("DELETE", f"/v1/snapshots/{_q(self.name)}")
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def create(size=None, name=None, from_snapshot=None, client=None):
|
|
180
|
+
"""Make a box: size s (the default), m or l; from_snapshot names a snapshot to start from."""
|
|
181
|
+
c = client or _client()
|
|
182
|
+
body = {k: v for k, v in {"size": size, "name": name, "from": from_snapshot}.items() if v}
|
|
183
|
+
r = c.call("POST", "/v1/boxes", body)
|
|
184
|
+
return Box(r["name"], c, r)
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def boxes(client=None):
|
|
188
|
+
c = client or _client()
|
|
189
|
+
return [Box(b["name"], c, b) for b in c.call("GET", "/v1/boxes")]
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def snapshots(client=None):
|
|
193
|
+
c = client or _client()
|
|
194
|
+
return [Snapshot(s["name"], c, s) for s in c.call("GET", "/v1/snapshots")]
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: orble-sdk
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Orble: Linux boxes for agents
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
Project-URL: Homepage, https://orble.tech
|
|
7
|
+
Project-URL: Documentation, https://orble.tech/docs
|
|
8
|
+
Requires-Python: >=3.9
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Dynamic: license-file
|
|
12
|
+
|
|
13
|
+
# Orble for Python
|
|
14
|
+
|
|
15
|
+
Make Linux boxes for agents, run commands in them, fork them and save them, from Python.
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install orble-sdk
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
import orble
|
|
23
|
+
|
|
24
|
+
box = orble.create()
|
|
25
|
+
print(box.exec("echo hello").stdout)
|
|
26
|
+
box.delete()
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Run commands
|
|
30
|
+
|
|
31
|
+
```python
|
|
32
|
+
r = box.exec("npm test", cwd="app", env={"CI": "1"}, timeout=300)
|
|
33
|
+
r.code, r.stdout, r.stderr
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Commands run with `/bin/sh -c` as the user `agent` (passwordless sudo), from `/home/agent`. `exec` waits for the
|
|
37
|
+
command to finish, up to `timeout` seconds (at most 600). Each stream comes back as its last 64 KiB.
|
|
38
|
+
|
|
39
|
+
## Files
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
box.write("app/config.json", '{"port": 3000}')
|
|
43
|
+
box.read("app/config.json")
|
|
44
|
+
box.write("logo.png", data) # bytes too
|
|
45
|
+
box.read("logo.png", binary=True)
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Relative paths start at `/home/agent`. `write` makes any missing directories. A file can have up to 8 MiB.
|
|
49
|
+
|
|
50
|
+
## Fork
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
a, b, c = box.fork(3)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Each copy has the box's files, memory and running programs as they were when you forked it.
|
|
57
|
+
|
|
58
|
+
## Snapshots
|
|
59
|
+
|
|
60
|
+
```python
|
|
61
|
+
snap = box.snapshot("lab-start")
|
|
62
|
+
lab = orble.create(from_snapshot="lab-start")
|
|
63
|
+
orble.snapshots()
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Suspend and resume
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
box.suspend()
|
|
70
|
+
box.resume()
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Idle boxes suspend by themselves, and `exec`, `read` and `write` wake a suspended box.
|
|
74
|
+
|
|
75
|
+
## Ports
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
box.exec("nohup python3 -m http.server 3000 > /dev/null 2>&1 &")
|
|
79
|
+
url = box.port(3000) # its https address, for your account only
|
|
80
|
+
url = box.port(3000, public=True) # for anyone with the address
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Public ports need an account that has added credit.
|
|
84
|
+
|
|
85
|
+
## Boxes you have
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
orble.boxes()
|
|
89
|
+
box = orble.Box("k7f2")
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Auth
|
|
93
|
+
|
|
94
|
+
The SDK reads an API key from `ORBLE_API_KEY`. Make one in [Settings](https://orble.tech/settings?tab=api). Without
|
|
95
|
+
it, the SDK uses the sign-in of the [orble CLI](https://orble.tech/docs?tab=cli) (`orble login`). Errors are
|
|
96
|
+
`orble.Error`, with the HTTP `status` and Orble's `message`.
|
|
97
|
+
|
|
98
|
+
## More
|
|
99
|
+
|
|
100
|
+
- [Docs](https://orble.tech/docs)
|
|
101
|
+
- [TypeScript](https://www.npmjs.com/package/@orble/sdk): `npm install @orble/sdk`
|
|
102
|
+
|
|
103
|
+
## License
|
|
104
|
+
|
|
105
|
+
MIT
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
orble/__init__.py,sha256=n0h7r9uqVIcQwbjD8wJtVDBUNcz0i_4AJgc4D_jgUNo,7261
|
|
2
|
+
orble_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=aHiEyEtjMTLtcD9WaghKRB21cZzfU7GYaxT5Z1MBtf4,1075
|
|
3
|
+
orble_sdk-0.1.0.dist-info/METADATA,sha256=cWYMt51b7BKMYPAaiVaGPmkSKG61CXSVVuspBTtBsb4,2416
|
|
4
|
+
orble_sdk-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
5
|
+
orble_sdk-0.1.0.dist-info/top_level.txt,sha256=_4xlkVnTLLRhzG-99qzbZkI_m2aaIJqA0DcHxb8EhtY,6
|
|
6
|
+
orble_sdk-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pocket Model, Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
|
|
6
|
+
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
|
|
7
|
+
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
|
|
8
|
+
persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
9
|
+
|
|
10
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
|
|
11
|
+
Software.
|
|
12
|
+
|
|
13
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
|
|
14
|
+
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
15
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
16
|
+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
orble
|