One API for isolated, managed agents.

Your control plane on top, your compute underneath, isolation in between. Target one HTTP/WebSocket API from any language — the same one the CLI uses — instead of reinventing container lifecycle, PTY multiplexing, session management, and per-agent auth.

Read the API reference → Source on GitHub

What you get

Isolated containers

One island per project, sandboxed from the host and from each other. Provision and destroy on demand.

Multi-attach sessions

WebSocket PTY streams with tmux semantics — N clients on one screen, surviving disconnects.

Lifecycle

Create, hibernate, wake, reset, purge — volumes preserved or destroyed on your terms.

Credential injection

Per-island GitHub identity and provider keys, mounted read-only. Master credentials never reach an agent.

Agent-state events

Webhooks for lifecycle, presence, and per-agent state (waiting-for-input, task-complete) to drive dashboards and notifications.

Headless or terminal

Attach to CLI agents (Claude Code, Codex) or run background SDK loops and workers — same API for both.

The API

Target one HTTP/WebSocket surface from any language:

POST   /v1/islands                     { "repo": "...", "agent": "claude-code" }
GET    /v1/islands                      # list all islands
GET    /v1/islands/:name                # live detail: agents, presence, cpu/mem, git, health
POST   /v1/islands/:name/agents         { "type": "codex" }   # add an agent
GET    /v1/islands/:name/agents/:id/session   # websocket PTY stream, multi-attach
POST   /v1/islands/:name/exec           # one-shot command
POST   /v1/events/subscribe { "url": "https://yourapp.example.com/events" }

The substrate — container lifecycle, PTY multiplexing, credential injection, events, remote access — is done and open source. Full surface at the API reference.

SDKs

Official thin clients wrap the REST surface and the WebSocket PTY stream, so you don't hand-roll envelope framing. Both are alpha (0.x — fields may change until 1.0) and mirror openapi.yaml.

Python

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

from dejima import Client

dj = Client()                 # $DEJIMA_HOST / $DEJIMA_TOKEN
isl = dj.create_island(repo="git@github.com:you/foo.git",
                       agent="claude-code")
dj.exec(isl["name"], ["git", "status", "--short"])

with dj.attach(isl["name"]) as s:   # PTY, multi-attach
    s.send(b"ls -la\n")
    print(s.recv())

TypeScript / JavaScript

npm install dejima            # Node 18+ (ESM)

import { Client } from "dejima";

const dj = new Client();      // DEJIMA_HOST / DEJIMA_TOKEN
const isl = await dj.createIsland(
  "git@github.com:you/foo.git", { agent: "claude-code" });
await dj.exec(isl.name, ["git", "status", "--short"]);

const s = await dj.attach(isl.name);   // PTY, multi-attach
s.sendText("ls -la\n");
s.onData(bytes => process.stdout.write(bytes));

Source: sdk/python · sdk/ts. Prefer another language? The whole surface is one HTTP/WebSocket API — generate a client from the spec.

Webhooks

Subscribe a URL to get JSON POSTs on lifecycle events (island.hibernated, island.woken, …), presence (client.attached, client.detached), and agent-specific events (agent.waiting-for-input, agent.task-complete) emitted by the per-agent shims — Claude Code and Codex today, headless agents on their own via POST /v1/internal/agent-event. This is how mobile push, Slack notifications, and custom dashboards integrate. See docs/agent-adapters.md for adding your own.

dejima webhook subscribe --url https://ntfy.sh/your-private-topic

Architecture

        your app · dashboard · bot · CLI       (control plane)
                    │
                    │  websocket + HTTP API · over Tailscale
                    ▼
┌─ Dejima host · Mac mini / VPS / cloud VM ──────────────────────┐
│                                                                │
│   ┌─ island: web ──────────┐    ┌─ island: api ──────────┐     │
│   │ a1  claude-code        │    │ a1  codex              │     │
│   │ a2  headless           │    │ a2  claude-code        │     │
│   └────────────────────────┘    └────────────────────────┘     │
│                                                                │
│ per island: one container · shared home + credentials          │
│ per agent:  own git worktree · sandboxed from host & others    │
└────────────────────────────────────────────────────────────────┘

"API" here means Dejima's HTTP/WebSocket control surface — what your dashboard, bot, or CLI targets. The LLM APIs (Anthropic, OpenAI) are reached by the agents inside islands, on their own.

Build on the substrate

Container lifecycle, sessions, credentials, and events — done, and open source.

Read the API reference →