Dejima alpha

Up and running in minutes

One line to install, one word to run. The installer handles Tailscale, Docker, and the background service for you, so there's no infrastructure to build.

Get started

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

Run it locally → Set up 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.

1Install it

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

Sets up Tailscale, the island image, and the background daemon (and Docker, on macOS). 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 need to accept before it can finish. See what the macOS installer asks you.

Two commands. Open PowerShell (Win+X → Terminal) — not Command Prompt. First the Windows client:

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

Then the host itself, inside WSL2:

dejima wsl setup

Creates a WSL2 distro if you don't have one, installs Docker and the daemon inside it, builds the island image, and points your client at it. Takes a while on a first run, and it's idempotent, so a failed run is safe to repeat. The dashboard's setup screen offers this as a keystroke too, if you'd rather not type it.

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

This path is new. Hosting on Windows landed recently and has had far less mileage than the macOS and Linux installs. If it breaks, an issue is genuinely useful. Driving a server from Windows as a client is the well-trodden route, and it's the section below.

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

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). On Linux the installer already registered the service, so just run dejima to confirm it's up. Either way, note the DEJIMA_HOST it prints (e.g. 100.84.12.7:7273).

On a fresh Mac, step 1 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.

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

Open PowerShell (Press Win+X → Terminal / Windows PowerShell) — not Command Prompt.

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 via brew or npm? Point it at your server once with dejima profile add mini <host>:7273 && dejima profile switch mini. Joining a teammate's server instead? They send you an invite (they run dejima token invite --role operator) and you run dejima join <invite>. See connect to a server for the full flow, including turning on Tailscale MagicDNS so the invite carries a stable name.

Good to know

The two 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.

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 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.