# 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.

Source: https://zeptap.com/docs/cli/setup



## Install [#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](https://zeptap.com/docs/get-started/install#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 [#check-it]

```sh
zeptap doctor
```

[`doctor`](https://zeptap.com/docs/cli/commands/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 [#teach-your-agents]

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

| Agent        | Skill                                                          | Also allows `zeptap` to run                                                                                                             |
| ------------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code  | `~/.claude/skills/zeptap/SKILL.md`                             | `Bash(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`](https://zeptap.com/docs/cli/commands/skill) 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 [#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 [#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`.
