Getting started

Up and running in a couple of minutes

Install the binary, point your MCP client at it, and start in read-only mode. Everything below is copy-pasteable. Tidesman needs macOS 26 on Apple Silicon, with Apple's container engine installed and started.

Install

Four ways to install

Pick whichever fits your setup. Homebrew is the simplest to keep updated.

1

Homebrew

Tap and install in one command. Upgrades come through brew upgrade.

Terminal

$ brew install JeronimoColon/tidesman/tidesman

2

.pkg installer

Prefer a graphical install? Download the signed .pkg, double-click it, and follow the prompts. It places tidesman on your PATH for you.

Download the .pkg

3

Zip archive

Grab the .zip from the releases page, unzip it, and move the binary somewhere on your PATH.

Terminal

$ unzip tidesman-0.3.0-macos-arm64.zip
$ sudo mv tidesman /usr/local/bin/
$ tidesman --version
tidesman 0.3.0

4

.mcpb bundle

For Claude Desktop and other clients that support MCP bundles: download the .mcpb file and open it. The client installs and registers the server in one step. No terminal required.

Download the .mcpb

Configure your client

Point your MCP client at Tidesman

Add a server entry keyed tidesman. Set the access level with --mode; start with read-only and raise it when you're ready.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the server, then restart Claude Desktop. Use the binary's full path. Claude Desktop doesn't inherit your shell PATH. Homebrew installs it to /opt/homebrew/bin/tidesman (the .pkg to /usr/local/bin/tidesman); run command -v tidesman to print yours.

claude_desktop_config.json

{
  "mcpServers": {
    "tidesman": {
      "command": "/opt/homebrew/bin/tidesman",
      "args": ["--mode=read-only"]
    }
  }
}

Claude Code

Register it from the terminal, or commit a .mcp.json to share it with your project.

Terminal

$ claude mcp add --transport stdio --scope user tidesman -- /opt/homebrew/bin/tidesman --mode=safe

.mcp.json

{
  "mcpServers": {
    "tidesman": {
      "command": "/opt/homebrew/bin/tidesman",
      "args": ["--mode=safe"]
    }
  }
}

Reference

The twenty tools

All twenty tools are always visible to your assistant; the mode controls which are callable. Read tools are callable in every mode. Write tools require Safe or Full. The destructive tools require Full. Destructive here means containers or images are removed; a write tool can still end or change what runs inside a container, and your MCP client may flag that on its own.

Tool	What it does	Modes
`system_ping`	Check that Apple's container engine is up and reachable.	Read · all modes
`system_disk_usage`	Report disk use for images, containers, and volumes, with reclaimable space.	Read · all modes
`system_repair`	Re-download the engine's own infrastructure images.	Write · safe + full
`container_list`	List containers and their current status.	Read · all modes
`container_inspect`	Return the full configuration and state of one container.	Read · all modes
`container_logs`	Read a container's stdout and stderr.	Read · all modes
`container_run`	Start a new container from an image.	Write · safe + full
`container_exec`	Run a command inside a running container.	Write · safe + full
`container_start`	Start an existing stopped container.	Write · safe + full
`container_restart`	Gracefully stop and then start a container, as one operation.	Write · safe + full
`container_stop`	Gracefully stop a running container.	Write · safe + full
`container_kill`	Force-terminate a container immediately.	Write · safe + full
`container_delete`	Permanently remove a container.	Destructive · full only
`container_prune`	Remove every stopped container in one sweep.	Destructive · full only
`image_list`	List the container images already downloaded.	Read · all modes
`image_inspect`	Return the full details of one image.	Read · all modes
`image_pull`	Download an image from a registry.	Write · safe + full
`image_tag`	Give an existing image another name.	Write · safe + full
`image_delete`	Permanently remove an image.	Destructive · full only
`image_prune`	Remove untagged (or all unused) images in one sweep.	Destructive · full only

Launch flags

The flags

Two flags control what Tidesman can do and what it can reach.

--mode=read-only | safe | full

Sets the access level. read-only (the default) exposes read tools only; safe adds run, exec, start, restart, stop, kill, image pull and tag, and the engine repair; full adds the delete and prune tools.

--allow-host-mounts=/path[,/path]

Off unless you pass it. Name the folders on your Mac a container may mount; a mount is allowed only when its real path (with symlinks resolved) sits under one you listed. Leave it off to keep your filesystem out of reach.

Example

$ tidesman --mode=safe --allow-host-mounts=/Users/you/project

Verify your download

Check the checksum before you run it

Every release ships a SHA256SUMS file. Download it alongside the binary and verify, from the same folder:

Terminal

$ shasum -c SHA256SUMS
tidesman: OK

A line ending in OK means the download matches. Tidesman is also Developer-ID signed and notarized, so Gatekeeper will let it run without extra steps.

That's the whole setup

Start in read-only, watch what your assistant does in the audit log, and raise the mode when you trust it.

See the tools View on GitHub