Dock your own island

You can host an island on your own domain and have Harbor show it on the chart and the sea. Your domain publishes a small signed file, /.well-known/acre-island.json, and Harbor checks the signature before listing it.

Note

Docking is only available where the ACRE server has it switched on. If you don’t see Dock your island on the chart, it isn’t available there yet.

1. Make a key and a signed manifest

Get the acre CLI (a single file that needs Node.js):

mkdir -p ~/.acre
curl -fsSL https://useacre.dev/api/client/acre.mjs -o ~/.acre/acre.mjs
alias acre="node ~/.acre/acre.mjs"

Then create the island:

acre island init kestrel.example --name "Kestrel" \
  --kind startup --template autumn --visit harbor \
  --one-liner "Contract tools for small funds" \
  --contact mailto:hosts@kestrel.example

This writes a folder, ./acre-island/ (or --dir <folder>), containing:

File	What it is
acre-island.key	Your island’s private signing key. Readable only by you. Keep it secret and keep a copy offline.
acre-island.config.json	What the island says about itself. Edit it, then re-sign.
.well-known/acre-island.json	The signed manifest to publish

2. Publish it

Serve .well-known/acre-island.json from your domain over HTTPS, so it loads at:

https://kestrel.example/.well-known/acre-island.json

Harbor fetches it over HTTPS only, from public addresses, following at most 2 redirects, within 5 seconds, and reads at most 64 KB.

3. Check it

acre island verify kestrel.example

This runs the same seven checks Harbor runs, in Harbor’s order, and marks the first failure with NO.

4. Dock it

In ACRE, open the chart (M) and choose Dock your island. Enter your domain. You can dock up to 3 islands, and undock your own at any time.

Keeping it current

• A manifest is good for at most 90 days. Re-sign before it expires with acre island sign. An expired manifest drops off the chart.
• Harbor re-reads every docked island every 6 hours.
• Rotate keys with acre island rotate. It makes a new active key and keeps the old ones listed as retired, so Harbor can follow the rotation. Keys last at most 730 days.
• Harbor pins your key the first time it lists your island. If the manifest is later signed by a key that isn’t the pinned one, or a retired successor of it, the island comes off the chart until an operator re-pins it. Don’t delete your key. Rotate it.

State	What it means
Listed	The manifest passed every check
Offline	Your domain didn’t answer. The island stays listed until its manifest expires.
Invalid	The file is missing or fails a check. Off the chart.
Lapsed	The manifest expired. Off the chart.
Key changed	Signed by an unpinned key. Off the chart until re-pinned.

Letting people come ashore

Listing only needs the signed file. For people to land, your island has to run the ACRE server itself, which provides the visitor door and the live connection:

• Set realtime.url to a wss:// address on your own domain (--realtime on acre island sign).
• Set visit to harbor. Visitors at invite and island levels aren’t admitted from Harbor yet.
• Your island has to trust the visitor’s home world (see Peers).

The first time someone sails to a self-hosted island, ACRE asks their consent once, and again if the island’s key changes. Their home world then gives them a single-use, 15-minute pass carrying only a per-island visitor id, the name they chose, and their look. Nothing else about them crosses over.

If you run the ACRE server yourself, point it at your island folder and it serves the manifest and re-signs it for you.

See the manifest reference for every field.