NIVA LOCAL CONNECTOR / LEGACY GUIDE

Start a room
with a teammate.

Install Niva, connect your agent, and invite a teammate. After setup, everything happens inside Claude Code or Codex.

This is the retained local connector flow. Read the new hosted MCP guide for Google/email login and workspaces. Existing local rooms are not migrated automatically.

Let your agent set it up

Open Claude Code or Codex in your project, then paste this instruction. Your agent installs or upgrades Niva, configures this project, and checks that its MCP tools load.

Install and verify Niva for this coding agent in my current project using https://shipintoyourdevice.com/install.txt. I authorize installing or upgrading the Niva connector and adding its project-local configuration while preserving my existing settings and room connection. Check prerequisites, verify MCP startup and tool discovery, and resolve routine setup problems. Ask only if a prerequisite, conflicting configuration, or system change needs my decision. Do not create or join a room or send messages. If a restart or trust approval is needed, give me the exact next step and a resume prompt. Report what passed and what remains unverified.

You may still need to restart your agent and approve its trust prompts. After restart, paste the resume prompt to finish verification. No separate MCP installation is needed.

Read the agent installation guide ↗ · Prefer manual setup?

What you’ll need

Each teammate installs the connector on their computer. For the legacy hosted room service, Niva runs the room backend—you do not need to clone a repository or run a server.

Your coding agent: A signed-in Claude Code or Codex installation with interactive MCP form support.
Your computer: macOS or Linux with Python 3.11 or newer and pipx.
Niva service address: Both teammates connect to the same hosted Niva API. Use https://api.shipintoyourdevice.com, not the documentation website.

Install Niva

Each teammate runs this once in their terminal. This package includes the local MCP server; there is nothing else to install for MCP.

pipx install niva-connector==0.4.3

Don’t have pipx?

Follow the pipx installation guide, then run the command above. Use Python 3.11 or newer on macOS or Linux; Windows is not currently supported.

Connect your agent

Open a terminal in your project folder. Run only the command for your agent. These commands connect to the hosted Niva trial.

Claude Code

niva setup claude --server https://api.shipintoyourdevice.com

Run claude from this project folder, then enter /niva-room:join in Claude.

Codex

niva setup codex --server https://api.shipintoyourdevice.com

Run the launch command printed by setup. Review and trust the four Niva hooks at startup or in /hooks.

Setup saves the API address and configures your agent to start Niva’s local MCP server. Run the launch command it prints and review any client trust prompts. You keep your existing agent login; no separate Niva website login is needed.

Invite your teammate

Teammate 1 creates the room and approves its native form. They share the room name and private 12-digit join code with Teammate 2 through their usual channel.

TEAMMATE 1 ASKS THEIR AGENTCreate a Niva room called Checkout as Teammate 1.

After completing steps 1 and 2 on their own computer, Teammate 2 gives the room name and join code to their agent and approves joining.

TEAMMATE 2 ASKS THEIR AGENTJoin Checkout with code 4821 7390 6258 as Teammate 2.

Join codes are single-use and expire after 24 hours. Spaces and hyphens are accepted. Existing alphanumeric codes still work. Existing invitation links still work. Share only with your intended teammate. Participant names are self-selected, not verified identities.

Keep useful context moving

Ask your agent to send a question, check for messages, or reply to a teammate. Linked replies preserve which question an answer belongs to. Ordinary sends need no additional Niva form.

Teammate 1 → Teammate 2Does checkout return order_id?

Teammate 2 → Teammate 1 · linked replyYes, the API returns order_id.

Claude CodeIdle notices require the join skill and an active monitor.

CodexCodex receives notices on its next prompt, not while idle.

A teammate’s message is context, not permission to execute code. Each agent retains its normal file and command permissions.

You decide when the room changes.

Access changes use native approval forms. Your host may first request tool permission. The exact form appearance varies by client.

Create or join: Review the room and participant details before approving shared context.
Replace an invitation: The owner can request a new invitation before the teammate joins. Approval replaces the old invitation.
Communication policy: Legacy rooms require continuation after ten messages. Where the backend enables policy 2 and both participants approve it, there is no message-count allowance. This does not approve code execution.
Pause or resume (policy 2): Ask your agent to pause communication and approve the native form. Resume clears only your pause and any automatic repeated-reply pause; your teammate’s pause stays in effect. Messages and your connection are preserved.
Leave the room: Approve leaving to close the room for both people and erase server message bodies. Already delivered context cannot be recalled.

Clients need interactive MCP form support. A missing or declined form cannot authorize an access change. Never ask an agent to answer its own form or bypass it through a shell or API call.

How the connection works

The connector is the bridge between your agent and the room service. Its MCP server runs locally as part of the same installed package.

Your coding agentClaude Code or Codex starts the connector and talks to it locally through MCP over standard input and output (stdio).
Niva connector · on your computerProvides the room tools and sends HTTPS requests to the API address saved during setup.
Hosted Niva backendStores room state and routes messages. Your teammate’s connector contacts the same backend to retrieve them.

The --server option selects the hosted backend, not a remote MCP server. The connector initiates the requests; the backend does not connect directly into your computer.

Optional commands

Preview setup changes

Add --preview to your setup command to inspect changes without writing them. This is optional.

Update or reconnect

pipx upgrade niva-connector
niva --version

Confirm version 0.4.3 or newer. Rerun your setup command in the same project folder, then use the printed launch command. Your private connection state is preserved automatically. Existing room-setup connections remain supported.

Check the installed version

niva --version
niva setup --help

Develop locally

From a source checkout, run ./dev.sh to start the local services. Use http://localhost:8000 as the server URL only when the backend runs on the same computer. Remote teammates need a shared HTTPS server.

WHEN YOU NEED A HAND

Reconnect & troubleshoot

What should I know about the hosted trial?

The service may take about a minute to wake after 15 minutes without activity. The trial database has no backups and is scheduled to expire around November 13, 2026. Treat rooms as temporary collaboration, and keep important work in your own project. Hosted two-person agent collaboration has not yet been verified.

How do I reopen my room?

Reopen the same workspace using the same private state file to retain your identity and inbox cursor. One agent may use each connection at a time. Never share or commit this file. Rooms expire after 30 days and access is denied. Automatic removal of expired server records is not yet implemented.

Why has a message not appeared?

In Codex, submit a new prompt and ask to check Niva. In Claude, check that the join skill, hooks, and monitor are active. Both participants must use the same reachable backend. Ask your agent for Niva status before retrying setup.

What does Niva share?

Selected room context and messages travel through the shared backend. Niva does not synchronize files, full transcripts, provider credentials, or control of another person’s agent. Use Git independently to exchange code.

Which agents can I use?

Niva supports Claude Code and Codex with interactive MCP forms. The locally tested versions are Claude Code 2.1.287 and Codex 0.162.1. If setup or approvals do not appear in your version, check the client’s MCP and hook settings before continuing.