Start here

What would you like to do?

Choose one path. Each path is ordered from first command to first successful use, so you do not have to decide which credential, integration, or setup step comes next.

For MCP-only account tools

How should Codex sign in?

Use a browser callback when this terminal can receive it. Use a device code for SSH, containers, VS Code remote, or any terminal without that callback.

Codex project sharing

Set up once, then share from Codex chat

This path creates one local project profile and one project-scoped service identity. It does not create or require a separate Service API client, Service key passphrase, or .env file.

  1. Install or update the ZipPigeon CLI.
    Command 
    installer="${TMPDIR:-/tmp}/install-zippigeon.sh"
curl --proto '=https' --tlsv1.2 -fsSLo "$installer" \
  https://www.zippigeon.com/downloads/install-zippigeon.sh
sh "$installer"
export PATH="$HOME/.zippigeon/bin:$PATH"
hash -r 2>/dev/null || true
command -v zippigeon
zippigeon version
  2. Install the ZipPigeon Developer plugin.
    Command 
    codex plugin marketplace add git@github.com:KasraRassouli/zippigeon.git \
  --ref qa \
  --sparse .agents/plugins \
  --sparse plugins/zippigeon-developer

codex plugin add zippigeon-developer@zippigeon
  3. Connect ZipPigeon, then start Codex. Keep this terminal open while you approve the displayed device code in any browser. The same flow works for a local computer, SSH, VS Code remote, or a container.
    Command 
    zippigeon mcp login --device --server https://www.zippigeon.com

zippigeon mcp codex \
  --server https://www.zippigeon.com \
  --name zippigeon \
  -- --sandbox danger-full-access
  4. In the new Codex session, create the project profile. Codex will ask for a new project-profile passphrase in the terminal; save it in a password manager. Never paste it into chat, an .env file, or a command line.
    Command 
    Set up ZipPigeon for this project.
  5. Exit that Codex session and relaunch with the completed profile. Replace PROFILE_NAME with the name reported by setup.
    Command 
    zippigeon mcp codex \
  --server https://www.zippigeon.com \
  --name zippigeon \
  --profile PROFILE_NAME \
  -- --sandbox danger-full-access
  6. Share from the new Codex session. Ask for a named workspace file and recipient. Choose verified email delivery for someone who does not have a ZipPigeon account.
    Command 
    Send test.txt securely to recipient@example.com with ZipPigeon. Use verified email delivery if the recipient does not have a ZipPigeon account.
    If Codex asks for a passphrase in regular chat, stop rather than sending it: exit and run the named-profile doctor check in the terminal, then use the recovery guidance below if it cannot unlock.
ZipPigeon setup guide Updated Aug 7, 2026 14 min read
Troubleshooting, reset, and other integrations

Choose how to connect

Free, Personal, and Pro accounts can connect ZipPigeon to inspect plan usage, work with eligible encrypted transfers, and open the browser-protected upload flow within their plan limits. Pro also includes CLI and Service API automation.

  • ChatGPT: add ZipPigeon as a developer-mode MCP connection.
  • Codex with a browser callback: connect directly with the Codex CLI.
  • Remote Codex, SSH, or browser containers: use the ZipPigeon CLI device-code flow.
  • Claude Code: add ZipPigeon as a remote HTTP MCP server and authorize with Claude Code OAuth.

Before installing Codex: choose the credential path

Installing the Codex plugin adds the ZipPigeon tools and setup skill; it does not create a local upload credential or a project profile. Choose the path that matches how you intend to send files.

  • Account connection only: install the plugin and authorize the remote MCP connection. No Service API client or key passphrase is required.
  • Share files from Codex chat: after installing and authorizing the plugin, ask Codex to set up ZipPigeon for the project. With Pro access, Codex creates one sealed project profile, prompts for a local passphrase, and provisions one scoped project service identity. Do not create a separate Service API client first.
  • Run zippigeon upload directly in a terminal: create one Service API client first under Account → Service API, save its key passphrase, and import its one-time configuration. This does not create a Codex project profile.
  • Need both terminal uploads and Codex chat sharing: complete those two paths separately. They intentionally use two scoped service credentials; do not repeat MCP authorization just to add terminal uploads.

Connect ChatGPT

Add ZipPigeon as a developer-mode MCP connection, authorize your account, then enable it in a new conversation.

  • Open Settings → Security and login, then turn on Developer mode.
  • Open ChatGPT Plugins, select the plus button, and create a connection named ZipPigeon Developer.
  • Enter the MCP URL below, review the discovered tools, and continue to ZipPigeon sign-in.
  • Approve only the permissions you expect, then start a new conversation with ZipPigeon enabled. Workspace policy may restrict Developer mode.
Command 
https://www.zippigeon.com/mcp

Send a file already attached in ChatGPT

Enable ZipPigeon in the conversation and ask to send the attached file to an exact recipient. The ZipPigeon secure-upload panel lets you select that ChatGPT file, encrypts it inside the embedded browser component, and uploads only ciphertext to ZipPigeon. Continue to the signed-in ZipPigeon page, where your unlocked account key authorizes the encrypted manifest. Review the prefilled recipient and select Share by email to send it.

  • Example: “Send the attached report securely to recipient@example.com with ZipPigeon.”
  • Selecting a ChatGPT attachment does not undo its existing presence in ChatGPT; use ZipPigeon direct upload when the file must never enter a ChatGPT conversation.
  • The account private key never enters the connector, ChatGPT, or MCP tool output.
  • The recipient is never emailed automatically: the first-party ZipPigeon confirmation remains required.

Install the packaged Codex plugin on QA

QA testers with repository access can add the QA branch as a sparse Codex marketplace, install ZipPigeon Developer, and then choose the browser-callback or remote-terminal authorization flow below. Installation alone does not configure a project profile; complete the project-profile step below before asking Codex to share a workspace file. The sparse paths avoid cloning the full application into the Codex marketplace cache.

  • Run the marketplace command once per Codex installation.
  • Rerun codex plugin marketplace upgrade zippigeon and codex plugin add zippigeon-developer@zippigeon after a QA plugin update.
  • Restart Codex and open a new thread after installing or updating the plugin.
Command 
codex plugin marketplace add git@github.com:KasraRassouli/zippigeon.git \
  --ref qa \
  --sparse .agents/plugins \
  --sparse plugins/zippigeon-developer

codex plugin add zippigeon-developer@zippigeon

Update the ZipPigeon CLI before setting up a project

The Codex plugin does not install the ZipPigeon CLI. Project profiles require CLI 0.1.4 or later. Verified-email guest delivery requires CLI 0.1.5 or later; older binaries do not support that guest-email flow and can show a misleading account-only recipient error.

  • Run command -v zippigeon and zippigeon version first. The current executable must be $HOME/.zippigeon/bin/zippigeon, not an older /usr/local/bin copy.
  • After the update, confirm the installed command and version before asking Codex to set up the project.
  • The installer only updates the local CLI. It does not create a Service API client, project profile, passphrase, or account connection.
Command 
installer="${TMPDIR:-/tmp}/install-zippigeon.sh"
curl --proto '=https' --tlsv1.2 -fsSLo "$installer" \
  https://www.zippigeon.com/downloads/install-zippigeon.sh
sh "$installer"
export PATH="$HOME/.zippigeon/bin:$PATH"
hash -r 2>/dev/null || true
command -v zippigeon
zippigeon version

Set up a Codex project profile step by step

Use this Pro-only sequence after installing the plugin, updating the CLI, and completing the device-code connection above. Start Codex without --profile. In the new Codex session, use the exact request below; the installed setup skill performs the local and connector steps in order.

  • First complete the CLI update checks immediately above. Do not run project setup through a 0.1.0 CLI or when project prepare is unavailable.
  • Use the device-code command above to launch Codex without --profile. Do not use zippigeon doctor, zippigeon configure, a Service API client, or ZIPPIGEON_KEY_PASSPHRASE for this flow.
  • Codex creates local keys, then shows Project profile passphrase: in the terminal. Type a new passphrase there; nothing is echoed. Save it in a password manager and use the same value at the later completion prompt. Never set ZIPPIGEON_KEY_PASSPHRASE or add it to an .env file for this flow. The project passphrase is not your ZipPigeon account password and never belongs in chat.
  • Codex then creates the project-scoped service identity, completes the local profile, and runs the named profile doctor check. Note the reported profile name.
  • Exit Codex after the successful doctor check and follow the relaunch command in the next step. That enables the local zippigeon-project server used for approved workspace-file shares.
  • Do not use zippigeon upload ./file --recipient ... as the project setup command. Without --profile it attempts to unlock a separate default service configuration and can prompt for an unrelated passphrase.
Command 
Set up ZipPigeon for this project.

Relaunch Codex with the completed project profile

Run this only after the prior setup reports a successful named profile and doctor check. Replace PROFILE_NAME with that reported name, then use the new Codex session to request an approved workspace-file share.

  • This is still the Codex project-sharing path. It does not require a Service API client or a Service key passphrase.
  • The local server shares only an explicitly named workspace-relative file after Codex shows its normal tool approval.
Command 
zippigeon mcp codex \
  --server https://www.zippigeon.com \
  --name zippigeon \
  --profile PROFILE_NAME \
  -- --sandbox danger-full-access

If a project share says “ciphertext cannot be decrypted using that key”

This is a local project-profile passphrase mismatch. It does not mean the recipient, device login, OAuth token, or Service API client is broken. The project profile has its own passphrase, created when the terminal first showed Project profile passphrase during zippigeon project prepare.

  • Do not enter a direct Service API passphrase or set ZIPPIGEON_KEY_PASSPHRASE. Neither can unlock a project profile.
  • Exit the current Codex session before trying again: the local sharing process retains an attempted project passphrase only for that session.
  • Run the named-profile doctor command below and enter the original project profile passphrase. If it succeeds, relaunch Codex with the same profile and retry the approved share.
  • If that original project passphrase is unavailable, follow the replacement-profile instructions in the next section. It cannot be recovered.
Command 
unset ZIPPIGEON_KEY_PASSPHRASE
zippigeon doctor --profile PROFILE_NAME

# Exit Codex, then relaunch it with the same PROFILE_NAME.
zippigeon mcp codex \
  --server https://www.zippigeon.com \
  --name zippigeon \
  --profile PROFILE_NAME \
  -- --sandbox danger-full-access

If you forget the project profile passphrase

The passphrase cannot be recovered, reset, or changed because it encrypts the local private-key bundle. Do not try a Service API reset, zippigeon doctor without the profile, ZIPPIGEON_KEY_PASSPHRASE, or a generic cleanup command.

  • Create a replacement through the normal Codex project setup flow with a new, distinct profile name. Do not overwrite or delete the old local profile first.
  • After the replacement completes, relaunch Codex with its new profile name and verify that its named-profile doctor check works.
  • Only after the replacement works, revoke the old scoped service identity in Account → Service API. Delete a local profile only when you explicitly intend to discard that exact named profile.
Command 
Set up ZipPigeon for this project with profile NEW_PROFILE_NAME.

Start a project profile over

To deliberately recreate one named project profile, use the reset command. It removes only that profile’s local encrypted pending or completed file; it does not remove the CLI, device login, or a separate direct Service API configuration.

  • The --yes flag is required because this permanently removes the local encrypted keys for the named profile. Replace PROJECT_PROFILE with the actual profile name.
  • If the profile had completed previously, revoke its old service identity in Account → Service API before recreating the same profile name.
  • After reset, reconnect through device login and ask Codex to set up the profile again. No Service API passphrase or ZIPPIGEON_KEY_PASSPHRASE is involved.
Command 
zippigeon project reset --profile PROJECT_PROFILE --yes

zippigeon mcp login --device --server https://www.zippigeon.com

Reconnect if project setup says recent verification expired

Recent verification applies only while ZipPigeon creates the Pro project identity. The error means the connected account credential is no longer fresh enough for that action; it does not mean the project passphrase is wrong, does not expose a secret, and does not create an identity.

  • Do not rerun zippigeon project prepare, generate new keys, or choose a new passphrase. The original public setup request can be reused.
  • For a browser-capable Codex terminal, run codex mcp login zippigeon, approve the same ZipPigeon account in the browser, then return to the same setup conversation.
  • For SSH, a container, VS Code remote, or Rancher, use the device-code command below, approve it in any browser, and relaunch Codex with zippigeon mcp codex.
  • After reconnecting, say: “Continue ZipPigeon project setup.” If a relaunched remote Codex session asks for the original setupRequest, provide only that public-key object from project prepare; never provide the pending profile, encrypted bundle, or passphrase.
Command 
codex mcp login zippigeon

Connect Codex with a browser callback

Run these commands in the Codex terminal. The login command opens ZipPigeon authorization in your browser. Sign in, review the requested permissions, approve access, and return to Codex.

  • When replacing an incomplete or outdated ZipPigeon entry, run codex mcp remove zippigeon before the commands below.
  • Run codex mcp login zippigeon after adding the server; rerun it if authorization was interrupted.
  • Use /mcp inside Codex to confirm that ZipPigeon is connected.
Command 
codex mcp add zippigeon \
  --url https://www.zippigeon.com/mcp \
  --oauth-resource https://www.zippigeon.com/mcp

codex mcp login zippigeon

codex mcp get zippigeon --json

Connect remote Codex with a device code

Use this flow when Codex runs over SSH, in a VS Code remote or Rancher terminal, in a browser container, or on another device that cannot receive the localhost callback. Codex MCP login does not offer a manual callback-paste option. Install the current ZipPigeon CLI, ensure its user-owned path wins over a stale global binary, run device login, and open the displayed verification URL in any browser. First launch Codex without --profile to authorize the connector or create a project profile; add --profile only after that setup succeeds.

  • Keep the terminal open while you approve the code; the code expires after ten minutes.
  • The terminal displays the one-time code. Enter or confirm that code in the browser; the terminal polls for approval automatically.
  • The access token is stored in an owner-only file and is never printed or pasted into the terminal, chat, or a command argument.
  • Do not run codex mcp login zippigeon in this fallback; that command starts the localhost callback flow that device authorization replaces.
  • Run the device login command again after the short-lived MCP token expires.
  • For Rancher environments that reject Bubblewrap namespaces, pass --sandbox danger-full-access after --. Do not use --yolo, because it also disables approvals.
Command 
installer="${TMPDIR:-/tmp}/install-zippigeon.sh"
curl --proto '=https' --tlsv1.2 -fsSLo "$installer" \
  https://www.zippigeon.com/downloads/install-zippigeon.sh
sh "$installer"
export PATH="$HOME/.zippigeon/bin:$PATH"
hash -r 2>/dev/null || true

command -v zippigeon
zippigeon version

zippigeon mcp login --device --server https://www.zippigeon.com

zippigeon mcp codex \
  --server https://www.zippigeon.com \
  --name zippigeon \
  -- --sandbox danger-full-access

Use the standalone upload command directly

This is a different path from Codex project sharing. Before running zippigeon upload ./file --recipient recipient@example.com, create a Service API client in the signed-in ZipPigeon app.

  • Open Account → Service API, choose a service integration, and enter a new Key passphrase. Save it in a password or secret manager before creating the client.
  • Keep the one-time credentials panel open. Run zippigeon configure --paste, copy the encrypted configuration into that waiting terminal, press Ctrl+D, and enter the Key passphrase you chose.
  • Run zippigeon doctor and enter the same passphrase. Only after it verifies should you run zippigeon upload.
  • If the original Key passphrase was not saved, create a new Service API client. The encrypted private-key bundle cannot be unlocked or recovered without it.

Send to an email recipient without a ZipPigeon account

Use verified email delivery when the recipient does not have an account. ZipPigeon sends the recipient an access email, and that mailbox must enter a one-time verification code before the encrypted transfer can open.

  • Use account-bound delivery for existing ZipPigeon members. It is tied to their account keys.
  • Use --email-share for a guest email address. This is not a bearer secure link and does not require the recipient to create an account.
  • This requires CLI 0.1.5 or later. CLI 0.1.4 accepts the flag but still attempts an account-bound share; run zippigeon version, then update with the signed installer above if needed.
  • Do not silently change an account-bound delivery into a link: choose the intended delivery type before sending.
Command 
zippigeon upload ./report.pdf \
  --recipient recipient@example.com \
  --email-share

Set ZIPPIGEON_KEY_PASSPHRASE for a direct CLI session

Use this only after you have created and imported a Service API client for the standalone upload command. It is not used for Codex project profiles; those use a concealed local passphrase prompt instead. Never put this value in an .env file, even one ignored by Git: Codex can read it and child processes can inherit it.

  • This zsh command stores the passphrase only in the current terminal session, without echoing it to the screen.
  • Run zippigeon upload in that same terminal after doctor succeeds.
  • When you are finished, run unset ZIPPIGEON_KEY_PASSPHRASE. Also unset it before project prepare or mcp codex. Never put the passphrase in an .env file, shell startup file, source control, or chat.
  • If you already put it in an .env file and an AI, tool, or source-control system could read it, remove it and retire that Service API client. Create a replacement with a new Key passphrase.
Command 
read -rs "ZIPPIGEON_KEY_PASSPHRASE?Service key passphrase: "
print
export ZIPPIGEON_KEY_PASSPHRASE
zippigeon doctor

Repair one Codex component at a time

Exit Codex before changing its connection state. Do not run a multi-command cleanup: an MCP connection, the packaged plugin, the local CLI, device credentials, and an encrypted project profile are independent components. A profile reset must be a deliberate, separately confirmed action because deleting its local encrypted file permanently removes the ability to unlock it.

  • To revoke a device-code credential, close Codex and run zippigeon mcp logout with --yes. It invalidates the OAuth token at ZipPigeon and removes only that local device credential; it does not create or use a Service API client, zippigeon doctor, or ZIPPIGEON_KEY_PASSPHRASE.
  • For any developer app authorization, open Account → Developer Connector and choose Revoke access. If Codex reports either zippigeon or zippigeon-device is not logged in, exit Codex, remove those two MCP entries, then rerun device login and relaunch Codex through zippigeon mcp codex. Do not delete project-profile files to reset device authorization.
  • For a missing or outdated CLI, reinstall it with the signed installer. Do not delete a CLI binary first, and do not delete a global /usr/local/bin copy unless you know which package manager owns it.
  • For a plugin problem, update or reinstall only the ZipPigeon Developer plugin. Removing a plugin does not delete a project profile, and a failed keyring logout does not prove that a profile was removed.
  • For a lost project-profile passphrase, create a replacement profile through the project setup flow. Before removing the exact named old profile, revoke its old service identity in Account → Service API. Never use the literal label PROJECT_PROFILE as a profile name: it does not select the intended profile.
Command 
codex mcp list

codex mcp remove zippigeon-device
codex mcp remove zippigeon

zippigeon mcp login --device --server https://www.zippigeon.com

zippigeon mcp codex \
  --server https://www.zippigeon.com \
  --name zippigeon \
  -- --sandbox danger-full-access

Revoke a Developer Connector authorization

Use this command when you want to revoke the local device-code credential completely, rather than merely obtaining another one. It sends the OAuth revocation request to ZipPigeon before removing the owner-only credential file from that computer.

  • Close Codex first. Any running Codex process using this device credential loses access immediately after revocation.
  • This leaves project profiles, the installed CLI, and any separately configured direct Service API client unchanged.
  • To revoke a ChatGPT, Codex, or Claude Code authorization that is not the local device credential, open Account → Developer Connector → Authorized developer apps and select Revoke access.
Command 
zippigeon mcp logout --server https://www.zippigeon.com --yes

Connect Claude Code

Add ZipPigeon as a remote HTTP MCP server and let Claude Code complete OAuth directly. Claude Code owns the local OAuth credential storage; do not copy tokens into chat, shell arguments, or project files.

  • Use user scope to make the private connection available across your projects, or change it to local or project scope when that boundary is more appropriate.
  • Run the login command and approve ZipPigeon in the browser. For an SSH terminal, add --no-browser and paste the resulting callback URL when prompted.
  • Use /mcp inside Claude Code, or claude mcp get zippigeon in the terminal, to verify the connection.
Command 
claude mcp add --transport http --scope user zippigeon \
  https://www.zippigeon.com/mcp

claude mcp login zippigeon

claude mcp get zippigeon

Verify and use the connection safely

Start a new conversation, enable ZipPigeon, and ask it to show your current plan or encrypted-transfer status. Review every write action before approving it. Never paste a private key, API token, encrypted profile, passphrase, or device credential into ChatGPT, Codex, Claude Code, source control, or a project environment file.

  • ChatGPT users manage the connection under Plugins.
  • Codex users can inspect it with /mcp and remove it with codex mcp remove zippigeon.
  • Claude Code users can inspect it with /mcp and remove it with claude mcp remove zippigeon.
  • Reconnect after changing accounts or when a short-lived device credential expires.