Reference · for the agent running here

How your Dejima island works

You are an AI agent running inside a Dejima island. This page is written for you: what the island is, where your files live, what your token lets you do, and where the walls are. If your environment gave you a short primer, this is the long version of it.

Where you are

You are running in a contained Docker island on the operator's own hardware. An island holds one repository and is dedicated to it. You may be the only agent here, or one of several, each working the same repo from its own copy.

The island is the unit of isolation. Everything you do happens inside it. You do not see the host machine, the operator's other islands, or anything outside this container. That is the point: the operator can hand you real work without handing you the whole machine.

Your filesystem

Your filesystem is container-isolated. Two paths matter:

• /workspace is your worktree, the checkout of the repo you work in.
• /home/dejima is your home directory, where your config and tooling live.

There is no shared host filesystem mounted into the island. You cannot read the operator's files by walking up the tree, and nothing you write escapes the container on its own. When a file genuinely needs to cross the boundary, it goes through a governed path, not a raw mount:

• dejima cp moves a file in or out through the daemon.
• The intake drop is where the operator places files for you to pick up.
• The attach action brings a specific file into the session when the operator allows it.

Do not try to bridge the boundary yourself. Changing permissions, symlinking, or otherwise reaching for the host filesystem will not work and is not the intended path. If you need something from outside, ask for it through one of the routes above.

The daemon and your token

You talk to Dejima through a daemon, reached at the address in DEJIMA_HOST. Your access is scoped by a token. The token is what makes the island safe to give you: it grants exactly this island and nothing more.

Concretely, the boundaries your token enforces:

• You cannot create new islands. Only a Home Island may do that.
• You cannot reach into other islands or read their work.
• You cannot touch the control plane or change the operator's configuration.

If a command fails with a message about your token or a missing permission, that is usually the boundary working as intended, not a bug to route around.

What you can do

Inside those walls you have real capabilities. The ones worth knowing:

• Mailbox. dejima msg lets you send and poll messages with other agents on this island. It is how you coordinate handoffs and ask another agent for help.
• Sub-agents. You can spawn governed sub-agents, but only within a grant the operator has given. Spawning is bounded by that grant, not unlimited.
• Port. Port is brokered, audited access to specific host files. It exists only when the operator grants a path, and every crossing is logged. It is never a raw filesystem mount, and there is no Port access unless the operator set it up.
• Egress. Network access out of the island is observed and policy-gated. What you can reach depends on the operator's policy, and it is not open by default.

Your CLI and API

The dejima CLI is your entry point from inside the island. Start with:

dejima --help

The commands you will use most:

• dejima msg — send and poll mailbox messages with other agents here.
• dejima cp — move a file in or out through the daemon.
• dejima audit — read the ledger of what has happened in the island.
• dejima status — check the island's current state.

Everything the CLI does, it does over Dejima's HTTP API. If you are writing code rather than running commands, the same surface is described by the OpenAPI spec and wrapped by the Python and TypeScript SDKs. See the API reference and building on Dejima.

Lifecycle

Your session persists. If the operator disconnects and reconnects, even from a different device, you pick up where you left off; the session does not reset because someone dropped off.

An idle island may hibernate to free resources, and it wakes again when there is work, on a message or a scheduled wake. Across all of that, your git history is intact: you can commit as you go and push when your work is ready. Commit early and often rather than holding a large uncommitted diff, so nothing is lost across a hibernate or restart.

Working alongside other agents

Several agents can share one island. Each gets its own worktree, so you are not editing the same files out from under each other, but you share the underlying repository and the credentials the operator configured.

Because you share the repo, coordinate. Use the mailbox to hand off work, announce what you are touching, and avoid colliding on the same branch or files. Treat the other agents here as teammates on the same checkout, not as strangers.