ZeptapDocs

Install and connect agents

How the zeptap command gets on your PATH, how to teach Claude Code, Codex and Cursor to use it, and how it gets through agent sandboxes.

Install

There's nothing to install separately. When Zeptap runs from your Applications folder, it links ~/.local/bin/zeptap to the tool inside the app and keeps the link current across updates. If ~/.local/bin isn't on your shell's PATH, it adds one guarded line to ~/.zshenv (or ~/.bash_profile for bash), once.

Settings › Connectors › Command line shows the status, and has an Install button if the link is missing.

With Homebrew, brew install --cask zeptap/tap/zeptap links the same tool.

The Beta build installs zeptap-beta, which talks only to Zeptap Beta. It also takes zeptap while no other copy of Zeptap has it.

Check it

zeptap doctor

doctor checks the command, PATH, the app, the connection, the license, the phones and the agent skills, and says how to fix whatever is wrong.

Teach your agents

Settings › Connectors › Command line lists the agents found on this Mac. Add does two things for each one:

AgentSkillAlso allows zeptap to run
Claude Code~/.claude/skills/zeptap/SKILL.mdBash(zeptap:*) in permissions.allow, and Zeptap's socket folder in sandbox.network.allowUnixSockets, in ~/.claude/settings.json
Codex~/.agents/skills/zeptap/SKILL.md~/.codex/rules/zeptap.rules: prefix_rule(pattern = ["zeptap"], decision = "allow")
Cursor~/.cursor/skills/zeptap/SKILL.md
Other agents~/.agents/skills/zeptap/SKILL.md (Gemini CLI, OpenCode, ...)

The skill is short. It tells the agent to run zeptap --help first, so the manual always matches the installed version. zeptap skill install writes the same skill files from a terminal, without the permission rules.

Use either the CLI or MCP for an agent, not both: two sets of instructions for one phone tend to confuse it.

Agent sandboxes

Codex's sandbox, and Claude Code's when it's turned on, block every way a shell command could reach a local app: TCP, Unix sockets and launching apps. zeptap talks to Zeptap over a Unix socket in ~/Library/Application Support/Zeptap/run/, so one exception covers it:

  • Claude Code: the socket folder in sandbox.network.allowUnixSockets. Add in Settings writes it.
  • Codex: the allow rule above. Codex then runs zeptap without asking, outside its sandbox.

When a sandbox blocks it, zeptap exits with code 8 and prints the setting for the agent it's running in. Agents should call it by its bare name, zeptap, not a full path: permission and sandbox rules match the command as typed.

How it connects

If Zeptap isn't running, zeptap opens it in the background and waits for it (up to 20 s). Inside a sandbox it can't, so the user has to open Zeptap first.

The command finds the running app through ~/Library/Application Support/Zeptap/run/server.json. The app rewrites that file on every launch with its process id, TCP port, socket path and version. The command then sends MCP requests over the Unix socket zeptap.sock in the same folder. That folder is readable only by your user (mode 0700), so only your own processes can connect. If the app is too old to have the socket, the command falls back to http://127.0.0.1:47801/mcp.

On this page