Guide · 5 min read

Run AI coding agents on a Linux server

Q: How do I keep Dejima running after I log out of the server?

Run loginctl enable-linger $USER. Dejima runs as a systemd user service, which normally stops when your login session ends. Lingering keeps it running between SSH sessions and across reboots. Check it with dejima doctor, which flags linger if it is off.

A headless Linux box is the natural home for a fleet of agents. It has no screen to babysit, it runs whether or not you're logged in, and you reach it from your laptop over your own network. This works the same on a VPS, a home server, or an old tower in the closet.

What you need

A Linux box running Ubuntu 22.04+, Debian 12+, or anything close. Two cores and 4 GB of RAM handles a few agents; more if you run many.
sudo on that box, and git plus curl. The installer handles the rest, including Docker.
Tailscale on the server and your laptop, so you can reach it without opening a port to the internet.
API keys for the agents you'll run. You bring your own.

Step 1: install Dejima

SSH into the server and run the one-liner.

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

It checks prerequisites and names a fix for anything missing, installs Docker if it's absent, builds the dejima and dejimad binaries, and registers dejimad as a systemd user service. When it's done, the daemon is running under your user.

Step 2: make it survive logout and reboots

This is the one step that's specific to a headless Linux server, and it's easy to miss. A systemd user service stops when your login session ends, which on a server you mostly stay logged out of, means the daemon would stop the moment you close SSH. Turn on lingering so it keeps running.

loginctl enable-linger $USER

Now dejimad starts at boot and stays up between your SSH sessions. You can confirm the whole setup is healthy at any time:

dejima doctor   # flags it if linger is off, Docker is down, etc.

Step 3: make an island and add agents

An island is one container with its own home, credentials, and network. Point one at a repo, then add whatever agents you want alongside the first.

dejima init --repo git@github.com:you/your-project.git

# a second terminal agent, and a headless one
dejima agent add your-project --type codex
dejima agent add your-project --type openclaw

Terminal agents (Claude Code, Codex, or a plain shell) are the ones you attach to. Headless runtimes like OpenClaw, Letta, and Hermes run on their own and stream to dejima logs.

Step 4: drive it from your laptop

You don't work on the server. You point Dejima at it from your own machine, over Tailscale, by setting one variable.

DEJIMA_HOST=your-server.your-tailnet.ts.net:7273 dejima        # the TUI
DEJIMA_HOST=your-server.your-tailnet.ts.net:7273 dejima connect your-project

The TUI lists every island and agent with status, memory, and logs. Attach to an agent, and the session keeps running on the server when you detach, drop off Wi-Fi, or switch to another device.

Why a container instead of just running agents on the server? An agent running as your user can read every repo on the box, your SSH keys, and your shell history, and nothing records what it touched. Inside an island it can't, and host access is deny-all until you grant a folder, read-only, through a logged broker. See the tmux + SSH guide for the longer version.

Day-to-day

dejima service restart bounces the daemon (or systemctl --user restart dejimad).
dejima hibernate your-project frees resources on an idle island; dejima wake brings it back.
dejima purge your-project destroys the island and its volumes. Push your work out first.

Common questions

How do I keep Dejima running after I log out of the server?

Run loginctl enable-linger $USER. Dejima runs as a systemd user service, which normally stops when your login session ends. Lingering keeps it running between SSH sessions and across reboots. Check it with dejima doctor, which flags linger if it's off.

Can I run AI coding agents on a VPS?

Yes. Any Ubuntu or Debian VPS works. Install Dejima with one command, enable linger so the daemon survives logout, and reach it from your laptop over Tailscale. A small VPS with two cores and 4 GB of RAM runs several agents.

Do I need a screen or desktop on the server?

No. Dejima is headless. You drive everything from the CLI and TUI, either over SSH or by pointing Dejima at the server from your own machine with the DEJIMA_HOST variable. The server just needs Docker and a network connection.

Have an AI walk you through it

Paste this into your own AI and it'll guide you through the steps, adapted to your setup.

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

I want to set up a Linux server (a VPS or a home box) to run AI coding agents with Dejima, headless, and I'd like you to walk me through it one step at a time.

First, FETCH and read these so your steps match Dejima's own docs rather than your training data:
- This guide: https://dejima.tech/guides/linux-server-agent-server.html
- Install and quickstart: https://dejima.tech/quickstart.html
- Overview: https://dejima.tech/

Then walk me through it:
- Before any commands, ask what I have: distro and version, whether I have sudo, whether Docker and Tailscale are installed, and which agents I want to run.
- Go one step at a time and wait for me to confirm each before the next.
- Don't skip making the daemon survive logout: remind me to run `loginctl enable-linger $USER`, then have me check with `dejima doctor`.
- Give the exact command for my setup, say what it does, and how to know it worked. If something fails, help me debug it before continuing.

Goal: a headless Linux server running my agents, each contained in its own island, that I reach from my laptop over Tailscale.

See the full quickstart →

Other ways to run: Mac mini · your own cloud VM · your own machine · all guides