Guide · 4 min read

Give an AI agent scoped access to one folder

Q: Is the folder access read-only?

It can be. Grant with :ro for read-only or :rw for read-write. Read-only is the safe default for handing an agent a dataset or reference material, and every crossing through the broker is written to an audit log either way.

Sometimes an agent needs a file from your machine: a dataset to analyze, a notes vault to read, a config to reference. You don't want to hand it your whole disk to get that. With Dejima you grant exactly one folder, read-only, and nothing else.

The default is nothing

A Dejima island starts with zero access to your host files. It can't see your home directory, your other repos, or your keys. There's no mount to forget about and no path it can reach by guessing. Everything an island touches on your machine has to be granted, on purpose, one path at a time.

So "give the agent one folder" isn't you poking a hole in a wall. It's the only door there is, and you decide what's behind it.

Grant the folder

One command. Point an island at a single host path and mark it read-only with :ro.

dejima port grant myproject ~/datasets/customer-csvs:ro

That's it. The agent in myproject can now read the files under that one folder, and nothing outside it. Use :rw instead of :ro only if the agent genuinely needs to write back; for handing over a dataset or reference material, read-only is the right default.

Check what's granted

You never have to guess what an island can reach. List its grants.

dejima port list myproject

Each scope shows its path and whether it's read-only or read-write. If a folder isn't on that list, the island can't touch it.

How the agent reads it

Files cross through the Port broker, not a shared mount. An agent working inside the island pulls a file across on demand, and the broker authenticates it automatically from inside. You can also do it explicitly:

dejima port intake myproject customer-csvs:2026-q2.csv

Either way the file moves through one controlled crossing, and that crossing is recorded.

See and revoke

Every grant and every file that crosses is written to the audit ledger. Look at just the host-file crossings:

dejima audit --type port

When the agent is done with the folder, take the access away.

dejima port revoke myproject ~/datasets/customer-csvs

The island is back to seeing nothing of your machine, which is where it started.

Why this beats a bind mount. A mounted folder is open for as long as it's mounted, with no record of what was read. A Port grant is explicit, scoped to one path, read-only by default, revocable in one command, and logged on every crossing. The agent can't widen it from the inside.

Common questions

How do I give an AI agent access to just one folder?

Dejima islands are deny-all by default. Grant a single folder with dejima port grant <island> <path>:ro. The agent reaches only that folder, read-only, through a broker, and you revoke it with dejima port revoke when you're done.

Can the agent see the rest of my files?

No. Host-file access is deny-all until you grant a specific path. The agent sees only the folders you've granted; it can't widen its own access or reach anything else on your machine.

Is the folder access read-only?

It can be. Grant with :ro for read-only or :rw for read-write. Read-only is the safe default for handing an agent a dataset or reference material, and every crossing through the broker is written to an audit log either way.

Have an AI walk you through it

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

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

Install Dejima and run your first island →