dejima — Python client

Thin Python client for the Dejima API: run a fleet of AI coding agents on hardware you own.

Alpha (0.x). The API is stable in shape (v1/-prefixed) but fields may change until 1.0. This client is hand-written over the REST surface and mirrors openapi.yaml; the only non-generated piece is the PTY Session helper.

Install

pip install dejima-sdk            # REST client
pip install 'dejima[ws]'      # + WebSocket PTY attach()

Quickstart

from dejima import Client

# host/token from $DEJIMA_HOST and $DEJIMA_TOKEN, or pass explicitly:
dj = Client(host="100.101.102.103:7273")

isl = dj.create_island(repo="git@github.com:you/foo.git", agent="claude-code")
print(isl["name"], isl["state"])

# add a second agent on its own worktree
dj.add_agent(isl["name"], type="codex")

# one-shot command
out = dj.exec(isl["name"], ["git", "status", "--short"])
print(out["stdout"], "exit", out["exit_code"])

# fleet view
for i in dj.list_islands():
    print(i["name"], i["state"], len(i.get("agents", [])), "agents")

print(dj.overview())   # daemon health, VM memory, rollup

Interactive sessions

attach() opens the multi-attach PTY stream (needs the ws extra). The daemon speaks a small JSON-envelope protocol over the WebSocket — Session hides that, so you deal in raw bytes:

with dj.attach(isl["name"]) as s:   # or agent="p2"
    s.resize(40, 120)
    s.send(b"ls -la\n")
    print(s.recv())                 # bytes of PTY output, or None when closed

dj.attach_terminal("t1") does the same for an operator host terminal.

API coverage

The client covers the full v1 surface:

Islands — list/create/get/update/delete, hibernate/wake/reset/upgrade, clone, resources, workspace-ready, events.
Agents — list/add/get/update/remove, configure (provider/model).
Exec & files — exec, file read/write, logs.
Port broker — scopes (list/grant/revoke), intake/export/write.
Capability broker — grants (list/grant/revoke), execute.
MCP broker — grants (list/grant/revoke), mcp_call.
Credentials — Claude push/status, GitHub identities + repos, LLM providers.
Operator tokens — create/list/revoke (owner-only; role + island scope).
Events — webhook subscribe/list/unsubscribe.
Activity — team activity feed (activity, filterable).
Daemon — overview, agent-types, healthz, audit (filters + jsonl/csv export), clients, sessions-revoke, panic, admin-update, image-build, SSH account keys.
Host terminals — list/create/delete/relabel + attach_terminal.
Sessions — attach / attach_terminal (PTY) and session_url.

Every non-2xx response raises dejima.DejimaError (.status, .message).

Auth

Operator (unix socket / tailnet) needs no token.
Autonomy path (an agent driving its own/child islands) uses a per-island bearer token — set DEJIMA_TOKEN or pass token=.

Development

pip install -e '.[dev]'
pytest

Tests run against a stdlib http.server stub — no running daemon required.

Metadata

Release files for dejima-sdk 0.8.99

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dejima-sdk 0.8.99
File	Size	Uploaded
dejima_sdk-0.8.99.tar.gz	15.3 kB	Sep 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dejima-sdk 0.8.99
File	Interpreter	ABI	Platform	Reset
dejima_sdk-0.8.99-py3-none-any.whl 12.4 kB Sep 3, 2026	Python 3	none	any	Details

Total release size: 27.7 kB

Release files / dejima_sdk-0.8.99.tar.gz

Download URL	dejima_sdk-0.8.99.tar.gz
Size	15.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`a83256543751060e76c95c6ad1677b6d563d3804db3e1d50b2683fd94db7cae3`
BLAKE2b-256 checksum How to use checksums	`06e5f9813e147c7bbdecb29708adc3e1b63365ab23343d6504870ff664cc6308`
Upload date	Sep 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / dejima_sdk-0.8.99-py3-none-any.whl

Download URL	dejima_sdk-0.8.99-py3-none-any.whl
Size	12.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5bdb274223199ecf4fe1907409c5e6826796deb4f93478da6ee5f4637915f8a4`
BLAKE2b-256 checksum How to use checksums	`71405cf0a67b9333da539650b76d76d542f8dadd522e90e74798a3e400b9eb14`
Upload date	Sep 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`