Dejima alpha

Up and running in minutes

A few commands to install, one word to run. The installer handles Docker, the background service, and — if you're setting up a server for other machines to reach — Tailscale, so there's no infrastructure to build.

Get started

Three ways to run it. Most people want the first one.

Run it locally → Set up a server → Join a server → Need help?

Run it locally on your computer

most common

Your daily computer. The server and the client end up on the same box, with nothing separate to connect. Works on Windows too, by way of WSL2.

Install it

Install Dejima.
```
curl -fsSL https://dejima.tech/install.sh | DEJIMA_SETUP=local bash
```
Sets up Docker (on macOS), the island image, and the background daemon. No Tailscale and nothing kept awake — that's what DEJIMA_SETUP=local means. Drop it and the installer asks; local is the default answer. Idempotent, so it's safe to re-run.

First time on a Mac?

It asks before installing anything, and Docker Desktop's first launch has a licence screen you have to accept before it can finish. What the installer asks you, including the pause that looks like a hang.

Enable Linux on Windows. Safe to run even if you already have WSL.
```
RUN AS ADMINwsl --install --no-distribution
```
If that flag is rejected

Older wsl.exe builds don't know it. Run plain wsl --install, reboot, then wsl --update.
Reboot.
Install Dejima, and let it build the Linux host. A normal PowerShell, not Command Prompt. Two questions, both answered by Enter.
```
irm https://dejima.tech/install-client.ps1 | iex
```
The two questions

Where will your islands run? Answer [1] on this machine, the default. That skips the Tailscale setup and the server-address prompt, neither of which applies when the host is this same box.

Run 'dejima wsl setup' now? Answer Y, the default. That's the step that builds the Linux host, and the installer runs it for you.

What it builds, and what not to do first

dejima wsl setup creates the dejima distro, installs Docker and the daemon inside it, builds the island image, and points your client at it. It goes quiet while it downloads and builds, so don't interrupt it; it gives itself 45 minutes.

Let it create the distro. If you open the new distro first and give it a user and a sudo password, setup's unattended steps fail on a permissions error that doesn't point back to the cause.

Declining the offer is fine. It's idempotent, so run it yourself whenever you like — but close and reopen PowerShell first, because the installer has just put dejima on your PATH and this window still has the old one.

Already keep a WSL distro for other work? dejima wsl setup --distro <name> uses that one. It has to be WSL 2: WSL 1 has no real kernel and can't run Docker.

2Run it

dejima

The dashboard opens and walks you to your first sandboxed agent. That's the whole setup.

Run it as a server (e.g. Mac mini), use it from any computer

The daemon runs on an always-on box, a Mac mini in the closet or a Linux server, and you drive it from any computer. Set up the server first, then each computer you connect from.

First

On the server

The always-on box that hosts the islands. macOS or Linux.

1Install

curl -fsSL https://dejima.tech/install.sh | bash

Write down the address it prints. Near the end it says Your DEJIMA_HOST is: 100.101.102.103:7273. That is what every other computer needs to reach this server, and it is the one thing from this run you have to carry elsewhere.

Scrolled past it? Run tailscale ip -4 on this machine and add :7273.

On a fresh Mac this stops to ask you a couple of questions and waits on Docker Desktop's licence screen. Here's what to expect, including the pause that looks like a hang.

2Provision the host

dejima onboard --provision-host

macOS: turns a fresh Mac mini into a server in one command — never-sleep power, Tailscale, Docker, the daemon.

Linux: step 1 already registered the service, so you can skip this. Run dejima to confirm it's up.

Then

On your computer

The client CLI that drives the server. macOS, Linux, or Windows.

1Install the client

curl -fsSL https://dejima.tech/install-client.sh | bash

On a fresh Mac this installs to ~/.local/bin and adds it to your PATH, so open a new terminal before the next step. To stay in this one: export PATH="$HOME/.local/bin:$PATH".

Open PowerShell (Press Win+X → Terminal / Windows PowerShell) — not Command Prompt. It asks where your islands run: answer [2] on another machine, since your server is the box above.

irm https://dejima.tech/install-client.ps1 | iex

If you see 'irm' is not recognized as an internal or external command, you're in Command Prompt (cmd.exe) — irm and iex are PowerShell commands. Reopen in PowerShell, or paste this, which works from Command Prompt too:

powershell -NoProfile -Command "irm https://dejima.tech/install-client.ps1 | iex"

Prefer a package manager like brew or npm?

brew install Scusi-Inc/dejima/dejima

npm i -g dejima

Homebrew (macOS) or npm (any platform, handy on Windows or if you already use Node). These install just the CLI, so you point it at your server in step 2.

2Connect

dejima

If you used the guided installer above, it captured your server's address, so this just connects.

Installed with brew or npm instead?

Those install only the CLI, so point it at your server once, using the address from On the server step 1:

dejima profile add mini 100.101.102.103:7273
dejima profile switch mini

Joining a teammate's server instead? That's the third option below.

Join a server someone else runs

A teammate — or your own Mac mini — is already running Dejima, and you want to drive it from this computer. Nothing is installed here but the CLI: no Docker, no daemon, no island image.

Install the CLI

brew install aoos/dejima/dejima

Or npm install -g dejima, which also covers Windows. Don't use the curl installer for this — it builds a server you don't need.

Point it at the server

dejima join <invite>

Whoever runs the server mints the invite. It carries the address, the credentials and your role, so there is nothing else to copy. No invite yet? Ask them to run dejima invite. Full flow, including Tailscale MagicDNS so the invite carries a stable name: connect to a server.

Good to know

The commands above assume a couple of things. On most machines the installer handles them for you; here's what they are, in case you need to set them up by hand.

Dejima needs Tailscale

Tailscale is a private network that links your machines directly, so a server and the computers that drive it can reach each other with no public port to open. The installer offers to set it up and walks you through signing in, or you can install it yourself from tailscale.com. The server and each computer just need to be on the same Tailscale network.

Connecting a second computer, or a teammate? See connect to a server.

On a Mac? Prefer iTerm2 or another modern terminal

macOS Terminal.app can't open agents as tabs (you get a new window per agent) and doesn't accept the clipboard sequence agents use, so copying an auth URL out of an agent silently fails. Run Dejima in iTerm2, WezTerm, kitty, or Ghostty instead — all support tabs and clipboard.

Details, and how to copy a URL out of an agent by hand: connect to a server.

What the macOS installer asks you, and the pause that isn't a hang

On a Mac with nothing on it yet, the installer stops and asks before it changes anything. It's worth knowing what's coming, because one of the steps looks like a freeze and isn't.

It asks first. Installing Tailscale and installing Docker Desktop are both prompts, not something it does behind your back. Answer no to either and it carries on. Skipping Tailscale costs you remote access only: the daemon comes up on a local socket, so driving it from the same machine works exactly as before, and you can add Tailscale later. If Tailscale fails to install, that's the same story, and setup keeps going.

One password prompt, up front. It asks for your sudo password once, at the point it needs it, and tells you what it's for. Your typing won't echo, which is normal. If a bare Password: ever appears partway through with no explanation, that's a bug worth reporting.

Docker Desktop's first launch is the slow part. A freshly installed Docker Desktop has no daemon until it has been opened once, and its first run puts a licence screen in front of you. The installer opens it for you, so there's nothing to go click, but you do have to accept that licence before anything can continue. Until you do, the installer sits and waits.

It waits up to five minutes and prints a line every 30 seconds so you can see it's still alive. Don't Ctrl-C it. Interrupting here is what leaves Docker.app half-installed, and the error you get afterwards (-10673) is macOS refusing to open a quarantined app rather than anything to do with Dejima. If you hit it:

xattr -dr com.apple.quarantine /Applications/Docker.app

If the five minutes run out, finish Docker's first-run setup by hand and run the installer again. It's idempotent and picks up where it stopped:

curl -fsSL https://dejima.tech/install.sh | bash

On Linux, expect to run the installer twice

The installer handles Docker on Linux as well as macOS. If it's missing, it offers to install it through Docker's official script, starts the service, and adds you to the docker group.

That group is why there are two passes. Membership only applies to a new login, and without it every later Docker call would need sudo, including the daemon's own, which doesn't run as root. So the installer stops there and tells you to log out, log back in, and run the same line again. It's idempotent and picks up where it stopped.

Prefer your package manager? Install Docker yourself first and the installer skips the whole step:

sudo apt install docker.io          # Debian / Ubuntu
# sudo dnf install docker            # Fedora
# sudo pacman -S docker              # Arch
sudo systemctl enable --now docker
sudo usermod -aG docker $USER       # log out and back in for the group to take effect

The server needs a Unix host — including on Windows

The Dejima server (the daemon) needs Docker on a Unix host, so it runs natively on macOS or Linux: a Mac mini, an always-on Linux box, or a VPS.

Windows gets there through WSL2, which is a real Linux kernel running a real Docker. dejima wsl setup installs the daemon into a WSL2 distro and connects your native Windows client to it, so a Windows PC can run the whole thing locally. The client talks to the daemon's Unix socket through the distro, so nothing new listens on the network and the security model is unchanged.

A Windows PC can also just be a client that drives a server elsewhere, if that suits you better.

Setting up a headless server, like a Mac mini in the closet?

Provisioning a machine you'll run without a monitor (the account, remote login, Tailscale, and finding its address) is automated by a wizard you run on the server itself:

dejima onboard --provision-host

Run it on the machine that will host the islands, not on your laptop. The setup guides have the full walkthrough for each platform.

Add a teammate

Someone else can drive your server from their own computer, with their own private fleet on it. You mint them an invite, share the server over Tailscale, and they run dejima join. That same flow also covers pointing your own laptop at a remote server.

Set up a teammate, step by step →

Setting up a specific platform? The setup guides walk through each one end to end: Mac mini, Linux server, cloud VM, and your local machine.

Stuck? Have an AI help

Installation question or an error you can't place? Paste this into your own AI, fill in your specifics, and it'll help using Dejima's own docs.

If the macOS or Linux installer failed, it wrote a transcript to ~/dejima-install-<timestamp>.log and printed that path. Attach it to a GitHub issue — it says what happened and in what order, which a description of the failure can't. The Windows installer doesn't write one.

Open in Claude → Open in ChatGPT → Opens in your own AI. Nothing is sent to us.

Run it yourself

In the dashboard, everything is a keypress; outside it, everything is a one-shot command.

dejima                              # the dashboard

# In the dashboard:
#   n → pick a repo + agent, launch       + → add another agent
#   ⏎ → open an island/agent in a window   ? → all keys

dejima init --repo git@github.com:you/foo.git    # or --local-copy for unpushed work
dejima ls                                         # all islands, last-used first
dejima agent add foo --type codex                 # a 2nd agent in foo's island
dejima connect foo                                # attach to the island shell
dejima connect foo/a1                             # attach to a specific agent (e.g. a1)
DEJIMA_HOST=mac-mini.tailnet:7273 dejima connect foo   # …from your laptop

Detach, don't exit. To leave a session, press Ctrl-b then d — it detaches and leaves the agent running. Typing exit can drop you into a reconnect loop. To reach a specific agent rather than a plain /workspace shell, attach by island/agent (e.g. dejima connect foo/a1).

CLI reference

Command	Purpose
`dejima`	Interactive dashboard — browse, manage, and launch islands. `n` new · `?` help.
`dejima init`	Provision a new island from a git URL or a local path.
`dejima connect`	Attach to an island's session (multi-attach).
`dejima ls`	List all islands.
`dejima status`	One island in detail: presence, memory, CPU.
`dejima hibernate` / `wake`	Stop / restart the container; volumes preserved.
`dejima reset`	Clear agent state. Preserves workspace.
`dejima exec` / `cp` / `logs`	One-shot command, file copy, log tail — no session attach.
`dejima doctor`	Health check: daemon, Docker, image, projects, webhooks.
`dejima service`	Install / uninstall `dejimad` as a host service.
`dejima webhook`	Subscribe a URL to receive state-change events.
`dejima purge`	Destroy island and volumes.

Concepts

Term	Meaning
`Island`	The container holding one project and one or more agents.
`Agent`	One CLI (Claude Code, Codex) or headless process inside an island, on its own git worktree.
`Bridge`	The brokered I/O channel between host and island.
`Trade`	A brokered, append-only export of changes from island to host.
`Intake`	Read-only files brokered into the island from the host.
`Ledger`	A tamper-evident, hash-chained audit log of every brokered transaction.

Intake / Trade / Ledger are the brokered-context primitives — the seam a memory or context layer attaches to without breaking island isolation. See the positioning note.

Uninstall

Get your work out first. Dejima never touches your host folders — but work done inside an island lives in that island's Docker volume, and dejima purge destroys it. Before removing anything, make sure each island's work is pushed to its remote (or copied out):

dejima exec foo -- git status        # anything uncommitted or unpushed?
dejima exec foo -- git push          # send it to your remote
dejima cp foo:/workspace/file ./     # or copy files out directly

Then remove Dejima from the server:

dejima purge <name>                  # each island: container + volumes
dejima service uninstall             # stop + deregister the daemon
sudo rm /usr/local/bin/dejima /usr/local/bin/dejimad
rm -rf ~/.dejima ~/.dejima-src       # state + config, source checkout

On a Mac or Linux client device, uninstalling is just deleting the dejima binary and removing DEJIMA_HOST from your shell profile. Docker and Tailscale are left in place — Dejima uses them but didn't install-own them; remove them separately if nothing else needs them.

On Windows, three things outlive the uninstall. dejima uninstall --client removes the saved connection and nothing more, so after it you still have a working dejima on your PATH. That's deliberate rather than broken: a running .exe is locked and can't delete itself, and an uninstaller silently rewriting your PATH is worse than one that tells you. Remove them yourself, in PowerShell:

Remove-Item -Recurse "$env:LOCALAPPDATA\dejima"   # dejima.exe and any .old-* copies
[Environment]::SetEnvironmentVariable('DEJIMA_HOST', $null, 'User')
$p = [Environment]::GetEnvironmentVariable('Path','User') -split ';' |
       Where-Object { $_ -ne "$env:LOCALAPPDATA\dejima" }
[Environment]::SetEnvironmentVariable('Path', ($p -join ';'), 'User')

Close any other windows running dejima first, or the first line can't delete the binary. If you installed with DEJIMA_PREFIX set, substitute that path in all three. Don't skip the DEJIMA_HOST line: that variable outranks every saved profile, so a leftover one stays in force even though --client reported removing the saved connection. Reinstall later and the client keeps dialling the old server, with nothing on screen explaining why.