Install Ocean

Ocean syncs coding-agent sessions to a shared read-only team drive at ~/.ocean. This page is the complete public setup and recovery guide — you do not need the GitHub repository.

Requirements

  • macOS 14 or newer on Apple Silicon or Intel
  • A sign-in method: GitHub, Google, work email, or a team invitation link
  • Internet access during setup and sync

Homebrew is optional when you use the shell installer. Ocean does not require Node.js, npm, rclone, FUSE, an MCP server, or a preinstalled agent skill — those are bundled or installed automatically.

Install

Pick one path. Both end in ocean install, which authorizes this Mac, connects the drive, and installs agent guidance.

Homebrew

Installs the CLI from the Emergent tap, then chains ocean install. Homebrew cannot finish setup by itself.

Homebrew$ brew install emergent-inc/tap/ocean && ocean install

Shell installer

No Homebrew needed. The bootstrap script downloads the CLI and ends by running ocean install itself.

Shell installer$ curl -fsSL https://raw.githubusercontent.com/emergent-inc/homebrew-tap/main/install.sh | sh

What ocean install does

  1. Opens browser authorization (GitHub, Google, or email). A separate ocean login is only needed later to reauthenticate.
  2. Lets you create, join, or select the active Ocean team.
  3. Reviews detected coding-agent session sources. Detected sources are enabled by default.
  4. Registers the background LaunchAgent (com.ocean.daemon) and starts syncing.
  5. Exposes the read-only team drive at ~/.ocean.
  6. Installs the Ocean skill into supported coding agents' personal skill directories.

If macOS blocks background activity, Ocean opens System Settings → General → Login Items & Extensions so you can allow it. You do not manually add a Login Item.

Setup does not print success while the mount is still stabilizing. Wait for the final health check before treating install as done.

Coding agents

Give an agent this page (/install) as the only entry point. Preferred command:

brew install emergent-inc/tap/ocean && ocean install

For mostly non-interactive setup after the binary is present, use ocean install --yes. Browser authorization and any required macOS background-activity approval still cannot be bypassed.

Skills install automatically during ocean install. To repair or reinstall guidance later:

ocean skills install

Optional agent ids narrow the install, for example ocean skills install cursor claude-code. Ocean never overwrites a conflicting user-owned skill.

Ocean does not install or modify coding agents, hooks, MCP servers, or editor extensions. It only adds instruction-only skill files.

Verify the setup

ocean doctor --json
ocean status --json
open ~/.ocean

Healthy means:

  • doctor reports ok: true and mounted: true
  • ~/.ocean opens and shows the active team's People tree
  • status shows the expected team and enabled agents

Recovery

If setup becomes unhealthy, start with diagnosis, then repair:

ocean doctor --json
ocean refresh

ocean refresh reconciles authentication, the background service, and the mount without deleting native agent sessions. ocean repair is an alias for the same command.

Common trip-ups:

  • Homebrew installed the binary but setup never ran — run ocean install
  • Browser authorization was skipped or expired — run ocean login or ocean refresh
  • macOS blocked background activity — allow Ocean in Login Items & Extensions, then ocean refresh
  • Drive not ready yet — wait a short time after install, then re-check ocean doctor --json
  • Agent guidance missing — run ocean skills install

For a clean reinstall on the same Mac, stop sync and remove managed services first:

ocean uninstall
brew reinstall emergent-inc/tap/ocean   # if you use Homebrew
ocean install

Uninstall removes the LaunchAgent, mount, and Keychain refresh credential. It preserves durable local session state and already uploaded team data so a reinstall can recover.

Useful commands

oceanOpen the installer / management TUI
ocean install [--yes]Authorize, connect, install agent guidance
ocean loginReauthorize this Mac
ocean status [--json]Concise health overview
ocean doctor [--json]Diagnose setup and suggest fixes
ocean refreshRepair auth, service, and mount
ocean skills installRepair Ocean guidance for agents
ocean pause / ocean resumeStop or resume session syncing
ocean uninstallRemove services; keep local session state

What Ocean places on the Mac

  • CLI — Homebrew prefix, or ~/.local/bin/ocean for the shell installer
  • Background service — ~/Library/LaunchAgents/com.ocean.daemon.plist
  • App state — ~/Library/Application Support/Ocean
  • Team drive — ~/.ocean (read-only)
  • Agent skills— each supported agent's personal skills directory

Ocean runs while that user is logged in. It does not run before login, and it does not collect product telemetry.