Connect to a Dejima server
A Dejima server hosts the islands; you reach it from another computer. This is how you connect one, whether it's a teammate's machine or your own laptop pointed at a remote box. There are two sides: the operator sets up the invite, the other person accepts it.
Same steps either way. Adding a teammate and connecting your own laptop to a remote Mac mini are the same job. The only difference is whose computer it is. If you're doing both sides yourself, do the operator part on the server, then the other part on your laptop.
The idea in one line
A Dejima server's address, something like 100.84.12.7, only exists inside Tailscale, a private network that links your machines directly. So the computer you're connecting needs two things: Tailscale (with access to that one server) and the Dejima client. There's no public port to open. Once the computer can reach the server, dejima join does the rest.
Adding someone (on the server side)
Do this as the operator, the person who runs the server. You'll send the teammate two things: a way onto the network, and a Dejima invite.
1Mint an invite
dejima token invite --role operator --owner amandaThis prints a paste-safe invite blob (it carries a secret, so treat it like a password). --owner amanda gives the teammate their own private fleet on the server, separate from yours; leave it off only if you want them acting in your islands. Use --role viewer for read-only, or scope to one island with --island foo. Revoke anytime with dejima token revoke.
The invite auto-fills the address a teammate dials — preferring the server's MagicDNS name (like minion.tailXXXX.ts.net) over its raw tailnet IP. This works whether you mint on the server or from a laptop connected to it. It matters because a shared node can show up under a different 100.x IP in the teammate's Tailscale, so an invite baked with a raw IP may not connect — the name resolves from both sides. This needs MagicDNS turned on (next step); without it the invite falls back to the raw IP and warns you. Pass --host name:7273 to override.
Prefer the dashboard? In dejima, press I to open the Team panel: pick the role and scope, fill in the server address, and it mints the same invite for you to copy. Owner-only.
2Share the server over Tailscale
In the Tailscale admin console: Machines → your server → Share → enter their email → send the link. Sharing this one machine gives them that server and nothing else on your network.
Trust them with more? You can instead invite them to your whole Tailscale network (fewer clicks, but they can reach all your devices). Sharing the single server node is the safer default.
One-time — turn on MagicDNS. In the same admin console → DNS → Enable MagicDNS. This gives your server a stable name (minion.tailXXXX.ts.net) that resolves for the teammate even though a shared node's raw 100.x IP differs on their side — it's what lets step 1 bake a name instead of a fragile IP. Verify it's on with tailscale status --json on the server: the node should report a DNSName ending in .ts.net.
Heads up: being signed in to Tailscale isn't enough — the teammate has to accept the share for the server to appear on their machine.
3Send them both
The Tailscale share link and the invite blob, over a channel you trust. Then point them at this page's next section.
You've been invited (on your computer)
You have nothing installed yet, and that's fine. Three steps and you're in.
1Get on Tailscale
Click the share link the operator sent. Tailscale walks you through installing it, signing in, and accepting that one machine, in a single flow. When it's done, your computer can reach that one server (and nothing else of theirs).
2Install the Dejima client
npm i -g dejimaOr the guided installer, which also captures the server's address for you:
curl -fsSL https://dejima.tech/install-client.sh | bashThat line is bash — macOS or Linux. On Windows, open PowerShell (not Command
Prompt) and run irm https://dejima.tech/install-client.ps1 | iex, or use npm i -g dejima
which works from either. If you get 'irm' is not recognized… you are in cmd.exe;
powershell -NoProfile -Command "irm https://dejima.tech/install-client.ps1 | iex" works there. The
client is just the CLI; it doesn't run a server of its own.
3Join, and open it
dejima join <invite>Paste the invite blob the operator sent. That saves the server and your token as your active connection. Then open the dashboard:
dejimaYou're in your own fleet on that server. Launch an island and you're working.
Connecting your own laptop to your own remote server? Same three steps. You're both the operator and the invitee: share the server to your own account (or you're already on the same network), install the client, and dejima join. If you'd rather not mint an invite for yourself, point the client at the server directly with dejima profile add mini your-server:7273 && dejima profile switch mini, then run dejima.
On a Mac? Use a modern terminal. For agent tabs and for copying things out of an agent (like an auth URL an agent prints when it asks you to sign in), run Dejima in iTerm2, WezTerm, kitty, or Ghostty. macOS Terminal.app can't open agents as tabs (Dejima falls back to a new window per agent) and doesn't accept the clipboard sequence agents use, so pressing c to copy a URL says "copied!" but nothing lands on your clipboard.
Copy a login URL out of an agent by hand: hold ⌥ Option and drag to select the URL, then ⌘C — Option bypasses tmux's mouse capture so the selection is a real one. Or, in iTerm2, turn on Settings → General → Selection → "Applications in terminal may access clipboard" and the agent's own copy key works directly. (Dejima's island tmux already forwards the clipboard sequence correctly — the gap is only the outer terminal.)
Common questions
What is Tailscale and why do I need it?
Tailscale is a private network that links your machines directly. A Dejima server's address (like 100.84.12.7) only exists inside that network, so the computer you're connecting needs Tailscale and access to that one server. There's no public port to expose.
Does my teammate see my other projects or machines?
No, if you share only the server node. Sharing one machine in Tailscale gives them that machine and nothing else. Mint their Dejima invite with --owner so they get their own private fleet on the server, separate from yours.
Can I connect my own laptop to a remote server the same way?
Yes. It's the same flow whether the second computer is a teammate's or your own. Get on Tailscale with the server, install the Dejima client, and run dejima join, or point the client at the server with dejima profile add.
The server has to be macOS or Linux, right?
Natively, yes: the daemon needs Docker on a Unix host, so it runs on macOS or Linux. But Windows can host too, through WSL2. dejima wsl setup installs Docker and the daemon into a WSL2 distro and points your native Windows client at it. Windows is also fine as a plain client driving a server elsewhere, if that's what you want. See the quickstart.
Copying a login URL out of an agent doesn't work (or new agents open in separate windows)?
You're most likely on macOS Terminal.app, which can't open agents as tabs and doesn't accept the clipboard sequence agents use — so pressing c to copy an auth URL reports success but leaves your clipboard empty. Switch to iTerm2, WezTerm, kitty, or Ghostty, which support both. To grab a URL without switching, hold ⌥ Option and drag to select it, then ⌘C — Option bypasses tmux's mouse capture. In iTerm2 you can also enable Settings → General → Selection → "Applications in terminal may access clipboard" so the agent's copy key works. Dejima's island tmux already forwards the clipboard sequence; only the outer Mac terminal is the limitation.
New here? Start with the quickstart →
Related: Dejima for teams (roles, scoped tokens, and the audit log) · platform setup guides · API reference