VivaDictaVivaDicta

VivAgents Server

Share CLI agents (Claude, Codex, Gemini) from your Mac with your iPhone or iPad.

VivAgents Server lets your iPhone or iPad use CLI agents (Claude, Codex, Gemini) running on your Mac, Linux server, or VPS — using your existing subscriptions with no API keys needed.

How it works: A server running CLI agents exposes them over the network. Your iOS device connects and routes AI requests through those agents. The server runs on macOS and Linux.

Two Ways to Run VivAgents

Option A: Built into VivaDicta for Mac (easiest)

The VivAgents Server is built into the VivaDicta macOS app. If you have a Mac, this is the easiest way to get started — just install VivaDicta for Mac, enable sharing, and your iOS devices can connect instantly. No command-line setup required.

Option B: Standalone server (Mac or Linux)

For headless servers, VPS, or Linux machines, you can run VivAgents as a standalone Node.js server. It supports macOS and Linux. Install with npm install -g vivagents, then run vivagents to start the server. See the GitHub repo for full documentation.

Requirements

  • A Mac running VivaDicta for Mac — or a standalone VivAgents server on Mac/Linux.
  • At least one CLI agent installed on the server: Claude Code, Codex CLI, or Gemini CLI.
  • Both devices on the same network (WiFi or Tailscale).

Step 1: Set Up the Server (Mac)

  1. Install one or more CLI agents on your Mac:
  2. Open VivaDicta on your Mac.
  3. Go to Settings → Share with iOS and enable the server.
  4. Note the server URL (e.g. http://192.168.1.5:3456) and auth token shown on the Mac.

Step 2: Connect from iOS

  1. Open VivaDicta on your iPhone or iPad.
  2. Go to Settings → AI Providers → VivAgents Server.
  3. Enable VivAgents Server.
  4. Enter the server URL and auth token from your Mac.
  5. Tap Test & Save — VivaDicta will verify the connection and show which CLI agents are available.

Available Agents

After connecting, VivaDicta auto-detects which CLI agents are installed on the server. Each agent maps to a provider:

AgentProviderSubscription
Claude CodeAnthropicClaude Pro, Max, or Team
Codex CLIOpenAIChatGPT Plus, Pro, or Team
Gemini CLIGoogleAny Google account (free tier available)

You can enable or disable individual agents from each provider's settings screen (Anthropic, OpenAI, Gemini).

Per-Provider Toggles

Once connected, each provider's settings screen shows a toggle to enable or disable that specific CLI agent. For example, you might want Claude CLI for Anthropic but prefer OAuth for OpenAI.

Fallback Chain

VivAgents integrates with VivaDicta's fallback system. When multiple methods are configured for a provider, they're tried in priority order:

  • Anthropic: VivAgents (Claude CLI) → API Key (Anthropic has no OAuth yet)
  • OpenAI: ChatGPT OAuth → VivAgents (Codex CLI) → API Key
  • Gemini: Google OAuth → VivAgents (Gemini CLI) → API Key

If the VivAgents server is unreachable (Mac asleep, different network), VivaDicta automatically falls back to the next available method.

Run on a VPS (Mac / Linux)

You don't need a Mac — VivAgents runs as a standalone Node.js server on macOS and Linux. This is ideal for always-on access from anywhere, without keeping your Mac awake.

1. Set up the server

  1. SSH into your VPS (Ubuntu, Debian, etc.) and install Node.js 18+:
    curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs
  2. Install VivAgents globally:
    npm install -g vivagents
  3. Install CLI agents you want to use:
    • Claude Code: npm install -g @anthropic-ai/claude-code, then claude to authenticate
    • Codex CLI: npm install -g @openai/codex, then codex login
    • Gemini CLI: npm install -g @anthropic-ai/gemini-cli, then gemini to authenticate
  4. Start the server:
    vivagents
    By default it listens on port 3456. The server prints the auth token on first run — save it for the iOS connection step.

2. Keep it running

Use a process manager to keep VivAgents running after you disconnect:

# With pm2
npm install -g pm2
pm2 start vivagents --name vivagents
pm2 save
pm2 startup

# Or with systemd (create a service file)
# See VivAgents docs for the full systemd template

3. Connect securely

Your VPS needs to be reachable from your iPhone. Two recommended approaches:

  • Tailscale (recommended) — install Tailscale on both your VPS and iPhone. Use the Tailscale IP as the server URL (e.g. http://100.x.x.x:3456). Zero firewall configuration, encrypted, works from any network including mobile data.
  • Reverse proxy + HTTPS — put VivAgents behind nginx or Caddy with a domain and TLS certificate. Use the public URL in VivaDicta.

4. Connect from iOS

  1. On your iPhone, go to Settings → AI Providers → VivAgents Server.
  2. Enter the server URL (Tailscale IP or public domain) and auth token.
  3. Tap Test & Save.

Remote Access via Tailscale (Mac)

If you're running VivAgents on your Mac (either built-in or standalone), you can access it from anywhere using Tailscale. Install Tailscale on your Mac and iPhone, then use the Mac's Tailscale IP as the server URL. Works from any network, including mobile data.

Note: CLI agents (Claude Code, Codex) are designed for software development use. Using them for general text processing may fall outside the intended use and could lead to account restrictions. By enabling this feature you proceed at your own risk.

Troubleshooting

  • Test & Save fails: Verify both devices are on the same network. Check that the URL includes the port (e.g. :3456). Ensure the auth token matches.
  • Agent shows “Not found”: The CLI tool isn't installed on the server, or the Mac app has sharing disabled for that CLI.
  • Requests fail intermittently: Over Tailscale or slower networks, large requests may time out. Try again or switch to a local network.
← Use Your SubscriptionsViva Modes →