How Island works.

Quick start

The quickest way in is a prerelease from the download page: a disk image for macOS, an installer for Windows, a Debian package for Linux, and portable archives for all six targets. They are unsigned, so the page also explains how to get past Gatekeeper or SmartScreen and how to check the checksum.

Build from source

From a clean checkout, vendor the pinned dependencies first. The CEF binary distribution and the Geist fonts are fetched by scripts/setup_deps.sh from the versions locked in deps/dependencies.lock.json; both land in gitignored directories and are never committed.

$ ./scripts/setup_deps.sh
$ python3 scripts/deps.py verify

The first configure needs network access: GoogleTest is fetched through CMake FetchContent. Then build, run the default test suite and open the app.

$ cmake -B build -S .
$ cmake --build build
$ ctest --test-dir build --output-on-failure
$ open build/src/main/island_browser.app

The ad and tracker blocker needs a stable Rust toolchain (cargo and rustc). CMake turns ISLAND_ENABLE_CONTENT_BLOCKER on when it finds cargo; without it you get a build whose blocker does nothing.

First run

The first launch shows one welcome card that offers, never blocks. It asks for a theme (System, Light or Dark) and lists the browsers found on your machine to import from (see Import).

Press EscEscape or choose “Just start browsing” to skip it. “Show Welcome…” in the browser menu reopens it, and Settings can import again at any time.

Looks

New in 0.7 Settings → Appearance starts with a Look preset:

• Native, the default for new profiles: a grey source-list sidebar, a segmented space switcher (initials only beyond four spaces), the New Tab row under the tabs, one full-width Agent button at the bottom, system-blue selected rows, and an address field that shows page state as indicators: a shield with the blocked-request count, Reader on pages that have a reader view, and an agent dot (blue while the agent works, orange while it waits for you). Native has no space colors.
• Arc, which existing profiles keep: the sidebar and window margin tinted in the space’s color, the page on an inset card with rounded corners and a soft shadow, and a frameless window on macOS.
• Graphite: neutral greys and hairlines, the sidebar Island 0.6 ships with.

Below the preset, Appearance groups the controls into Theme, Color, Layout and Text: per-space color (ten presets or a hex value), sidebar tint, sidebar on the left or right, page corner radius (0, 6, 10 or 14), density, interface font, the page card’s shadow and full bleed. Changing any of them labels the look Custom. Native hides the space color and tint controls.

Tabs and spaces

• Spaces are named groups of tabs. ⌘Command⌥OptionN makes one, F2 renames it, and ⌘Command⌥Option↓Down arrow / ⌘Command⌥Option↑Up arrow move between them.
• Pinned tabs (⌘CommandD) stay first in their space and never sleep.
• The icon rail: ⌘CommandB collapses the sidebar to a 52-point rail with one button per tab, a new-tab button and the spaces. The choice is kept across launches, and ⌘CommandL from the rail opens the sidebar while you type.
• Split view (⌘Command⇧ShiftS) pairs the tab with the next one; ⌘Command⌥Option[ and ⌘Command⌥Option] move the divider. Closing either half returns the other to full width.
• All tabs (⌘Command⇧ShiftA) shows every space’s tabs as searchable cards with their blocked-request counts. Arrows and Enter jump, Delete closes, P pins, and dragging a card onto another space moves it.
• Tab sleep: a tab you have not used for 15, 30 (the default) or 60 minutes releases its page to free memory (Settings → Tabs, or Never). It keeps its address, title, favicon and scroll position, shows dimmed, and reloads where you left off. Pinned tabs, the tab on screen, split-view partners, tabs playing audio and tabs with unsaved form input never sleep. The command palette has “Sleep inactive tabs now”.
• Peek: ⌘Command-click or middle-click a link, or choose “Open in peek”, and the page opens in a floating card over the current one, with “Open as tab” and “Close”. Links a page opens in a new tab peek too. EscEscape closes it.
• Session restore: after a clean quit Island rebuilds your spaces, tabs, pins, selections and split pairs. Restored addresses are checked like anything you type. ⌘Command⇧ShiftT reopens the last closed tab.

Start page and search

New tabs open on Island’s own start page, a local document that requests nothing until you submit. One field has three modes: Search opens the results in that tab, Ask agent sends the text to the agent panel, and Research starts a research turn. The last mode is remembered.

New in 0.7 The modes become a segmented control (Tab and Shift+Tab step through them while the field has focus), and six speed-dial tiles show your most visited sites, one per host, taken from history. Clearing history clears the tiles.

The address bar searches when the text is not an address: weather in oslo opens a results page. Bare hosts such as example.com open over https, localhost and IP addresses over http. Choose Google (the default), DuckDuckGo or Yandex in the Search section of Settings. ⌘Command⇧ShiftK opens the search palette.

Reader and find

Reader view

⌘Command⌥OptionR (or the Reader button in the address field) pulls the article out of the page and shows it in Island’s own reader document, with controls for text size, page width and Auto, Light, Sepia or Dark. Your choices are remembered, and Settings → Reader sets the defaults. Toggling again returns to the page. Reader fetches nothing extra.

Find in page

⌘CommandF opens a small bar at the top right of the page with an “n of m” count and a match-case toggle. Enter and Shift+Enter, or ⌘CommandG and ⌘Command⇧ShiftG, step through the matches; EscEscape closes the bar, and so does switching tabs.

Privacy and blocking

Island blocks ads and trackers natively: Brave’s adblock engine checks EasyList and EasyPrivacy before a page’s subresources load. Settings → Privacy turns ads and trackers on or off separately and keeps a per-site allowlist, and All tabs shows each tab’s blocked count. New in 0.7 In the Native look the count also sits in a shield at the left of the address field; clicking it opens Settings → Privacy.

The lists are downloaded at runtime, refreshed in the background at most every four days, and Island keeps working from its cached copy when an update fails. Site permission requests (camera, microphone, location, notifications) are declined, because Island does not show a permission prompt yet. The privacy page lists everything the browser sends and keeps.

History search

Island keeps your browsing history on this device: the address and title of http and https pages (never local, data or credentialed addresses), up to the newest 50,000 visits. ⌘CommandK searches it alongside open tabs, bookmarks and reports; the last word you type matches as a prefix, and results rank by text match, recency and how often you visit. Settings can stop recording new visits or clear the history.

Research and the Plan tab

Pick Research on the start page and press Enter. The question goes to your agent with a prompt to research it with Island’s browser tools: a new space named after the question, several sources in tabs, compared. The agent finishes with a Markdown report that cites every claim, and the report opens in a Report tab with Copy Markdown, Save as .md… and Continue in agent panel. Reports are kept in reports.json and listed in Settings → Reports and in ⌘CommandK.

The Plan tab New in 0.7

In 0.7 the agent first proposes a plan, and nothing runs until you approve it. The plan opens in a Plan tab, pinned first in the space, as a graph or a list of steps, branches, a join and a result, with at most three levels of branching. While it waits, the agent panel says “Waiting for approval”.

• Skip a step or restore it, and write an instruction for one step.
• Branch from a step, or ask the agent to expand it.
• Choose Run plan, Run one branch only, or Cancel.

Each research reuses its one Plan tab. Plans from other ACP agents open in List view.

AI agents

Island works with agents in two directions: an agent can run inside the browser, in the sidebar, and any agent you already use can drive the browser from outside through its tools.

The agent in the sidebar (ACP)

⌘CommandJ opens the agent panel. It runs an Agent Client Protocol agent as a local program and hands it Island’s browser tools. Pick the provider in the panel header or in Settings → Agent & tools; a custom command or ISLAND_AGENT_COMMAND runs any other ACP agent. Replies stream in as Markdown, tool calls that need approval ask first, EscEscape stops a turn, and the agent is told which tab you are looking at. New in 0.7 In the Native look the Agent button sits at the bottom of the sidebar.

Island’s tools for any agent (MCP)

While Island runs it serves MCP over Streamable HTTP on http://127.0.0.1:9223/mcp (a random free port if 9223 is taken), reachable from this computer only and protected by a bearer token that changes on every launch. Settings → Agent & tools shows the exact config with the current token; copy it into Claude Code, Claude Desktop, Cursor or any MCP client:

{
  "mcpServers": {
    "island": {
      "type": "http",
      "url": "http://127.0.0.1:9223/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

The stdio bridge

The port and token are also written to agent-endpoint.json in Island’s data directory, readable only by your user. Clients that only speak stdio can use the bundled bridge, which reads that file for them:

{
  "mcpServers": {
    "island": { "command": "/path/to/island_mcp_bridge" }
  }
}

The tools

Environment variables

Set these before launching Island (or the bridge).

Keyboard shortcuts

These are the default bindings (37 in Island 0.8.1), shown for macOS. On Windows and Linux use CtrlControl wherever the table shows ⌘Command and Alt for ⌥Option; ⌃Control is the Control key on every platform. On macOS, ⌘Command1 to ⌘Command8 select a tab and ⌘Command9 the last one; those are fixed menu items.

Make them yours

Open Settings (⌘Command,) → Shortcuts, click a shortcut and press the new keys; EscEscape cancels. Shortcuts need ⌘Command / CtrlControl, ⌃Control or Alt, except the function keys. Each row, or all of them, can be reset to the default. Changes are saved in prefs.json; on macOS the menu picks them up at the next launch.

New in 0.7 Keys you already use for another action are not taken silently: an amber banner names the other action and offers Replace or Cancel. Unbound actions offer “Add shortcut”, and ⌘Command/ (also Help → Keyboard Shortcuts) shows a cheatsheet of the ten most-used bindings with your current keys.

Import

Island reads other browsers’ files on your own computer, and nothing is uploaded. Import from the welcome card or from Settings at any time:

• Chrome, Edge, Brave and other Chromium-family browsers: bookmarks.
• Safari: bookmarks, where macOS lets Island read them.
• Firefox: bookmarks from the newest automatic bookmark backup of any profile.
• Arc: your spaces, with their names, colors and pinned tabs. Imported spaces are added next to yours and never replace them.

Downloads are saved straight into your Downloads folder under the suggested name; an existing file is never overwritten (name (1).ext).

Updates

Island checks its GitHub releases shortly after startup, at most once a day, or when you ask in Settings → Updates. It downloads the archive for your platform, verifies it against the release’s SHA256SUMS.txt, and swaps it in only when you choose Restart to update, keeping the previous version as a backup until the new one starts. Prereleases are opt-in. Builds run from a CMake build directory never update themselves.

Builds are unsigned prereleases for now, so macOS Gatekeeper and Windows SmartScreen warn before the first launch; the download page explains what to do. To turn the update checks off, set ISLAND_DISABLE_UPDATES=1 before launching.

$ ISLAND_DISABLE_UPDATES=1 open build/src/main/island_browser.app

Smoke test and test suites

A documented smoke run proves that startup stays local and shutdown stays clean. It opens a fixed local data: page with no external requests and exits through the normal CEF close lifecycle; afterwards no helper process should be left.

$ open build/src/main/island_browser.app --args --island-smoke-test
$ pgrep -fl island_browser || true

Four lanes run independently; ctest -N lists what a build directory contains.

Default suite

The browser build’s GoogleTest suite, which the quick start runs.

$ ctest --test-dir build --output-on-failure

Search kernel (opt-in)

The search kernel under src/search/ is guarded by ISLAND_ENABLE_SEARCH (OFF by default) and builds without CEF.

$ cmake -B build-search -S src/search -DISLAND_ENABLE_SEARCH=ON
$ cmake --build build-search
$ ctest --test-dir build-search --output-on-failure

Agent kernel

The MCP endpoint, the browser tools and the ACP client under src/agent/ are CEF-free and build on their own.

$ cmake -B build-agent -S src/agent
$ cmake --build build-agent
$ ctest --test-dir build-agent --output-on-failure

Python suites

The dependency lock model, packaging checks, the design-token contract and the version tooling run under pytest.

$ python3 -m pytest tests/deps tests/package tests/design tests/version

Versions and releases

Island uses Semantic Versioning. The version lives in one place, the VERSION file, and feeds the build, the About page, the agent protocols, the macOS bundle and this site. The changelog lists what changed in each release.

$ python3 scripts/version.py show
$ python3 scripts/version.py bump minor
$ python3 scripts/version.py check

bump moves the Unreleased notes in CHANGELOG.md under the new version; check fails if anything is out of step. When a version bump reaches main, the commit is tagged vX.Y.Z and this site rebuilds from the new changelog. Between versions, a moving nightly prerelease carries the packages of the latest packaging run.

How the code is organized

• src/main/: the browser: the native window, chrome views, the palettes, Settings, All tabs, the start page, Reader, Research and the stores behind them.
• src/agent/: the CEF-free agent kernel: the MCP endpoint and tools, the ACP client and the stdio bridge.
• src/content_blocker_ffi/: the Rust bridge to Brave’s adblock engine, pinned by its Cargo.lock.
• src/search/: the opt-in search kernel.
• tests/: the GoogleTest suites and the Python suites.
• docs/superpowers/: the accepted spec and plan for each phase.

Honest status

Island 0.8.1 is an unsigned prerelease. Every release is packaged for six targets, but only macOS on Apple silicon has been built and run on real hardware; the other five still need platform verification. There are no signed or notarized builds yet, so the operating system warns before the first launch.

Island does not support browser-store extensions, and it declines site permission requests for now. Nothing on this site is a promise about dates or platforms, only a description of the repository as it stands; Coming next is a direction, not a schedule.