FORMESTRY

Cli.nt

User Guide

Code from anywhere.

Cli.nt connects your iPhone or iPad to Claude Code running on your desktop. Send prompts from your phone, review and approve every action before it runs, manage multiple coding sessions, and stay in control — whether you’re on the sofa or across the world.

Quick Start

Work through this checklist on your desktop first, then your phone.

  1. 1.Set the AI CLI — choose Claude Code in the desktop server’s Settings > AI Provider and confirm it shows as authenticated. If not, run “claude login” in a terminal.
  2. 2.Set network settings — pick Tailscale (recommended, works anywhere) or LAN (same Wi-Fi only). For Tailscale, click Detect in Settings > Security & Server to auto-fill your Magic DNS hostname.
  3. 3.Set a password — Settings > Security & Server > Password. Minimum 4 characters. Must be set before any device can connect.
  4. 4.Add settings to the mobile app and connect — open Cli.nt on iOS, go to Settings, enter the IP/hostname, port (default 3001), and password, then tap Connect.
  5. 5.Approve the device in the server — the desktop shows the new device as Pending under Settings > Devices. Click Approve to let it through. The mobile app will sit at “Awaiting Approval” until you do. See Step 5 below for the full flow.

Once approved, you’re connected — start chatting.

How It Works

Cli.nt has two parts:

  • A server application that runs on your Mac or PC
  • An iOS app on your iPhone or iPad

The server launches Claude Code and keeps it running. The iOS app connects to the server over your local network or, with Tailscale, from anywhere with an internet connection. When Claude Code wants to run a command, edit a file, or use a tool, it pauses and sends an approval request to your phone.

Part 1

Getting Started

Step 1: Server Setup

Download and install the Cli.nt server application.

Claude Configuration

  • Set the Claude Code executable path. On Windows the default is “claude”. On Mac it is “/Users/(user name)/.local/bin/claude”.
  • Set your projects folder. This is a sandboxed root folder that Claude Code can work within. You can narrow this further per session in the iOS app — for example, set a broad projects folder on the server, then point each iOS session at a specific subfolder.
  • You can adjust the max token size for the context file. This file is created on the server and sent with each prompt, giving every session its own persistent context.

Network & Security

  • Go to Settings > Security & Server and set a password (minimum 4 characters). This protects your server from unauthorised connections.
  • The server runs on port 3001 by default. You can change this in Settings > Security & Server — just remember to match it in the iOS app.
  • Enter your Tailscale Magic DNS hostname to allow remote connections. You can find this in the Tailscale app on your desktop. Direct Tailscale IP addresses (100.x.x.x) are disabled for security reasons — accepting raw IPs would allow any device on your Tailscale network to connect. Magic DNS hostnames are required instead.
  • If you prefer to stay on your local network only, enable the “Allow HTTP on LAN” option.

Security note: Tailscale is the recommended way to connect because all traffic between your devices is encrypted (it runs over a private WireGuard tunnel). LAN mode, however, sends traffic unencrypted (cleartext) over your Wi-Fi. That means anyone else connected to the same network could, in principle, read what passes between your phone and desktop, including the commands Claude runs and the contents of any files it returns. This is why enabling LAN mode asks you to confirm a security warning first. Use LAN mode only on a network you trust (such as your own home Wi-Fi), and prefer Tailscale whenever you can.

Sandbox Mode

Sandbox Mode is enabled by default and recommended. When on, Claude Code’s file actions are restricted to the project paths set in the server and iOS settings.

This is an important protection with one limitation worth understanding — it does not contain Bash commands. See Sandbox Mode in Part 2 — Understanding Security for the full picture, including what to watch for.

Note: Claude Code is an AI agent and could potentially find ways around sandboxing. Sandboxing is a safety measure but not foolproof.

Logging

  • Console Log: The debugging log shown on the server’s main page. An option in settings enables more detailed output.
  • Execution Log: A record of events saved on your device for debugging. You can adjust the retention period (7 days, 30 days, or disabled) or turn logging off entirely. Logs are stored locally at ~/.satellite/execution_log.json and are never uploaded.

Step 2: Connect Your Devices

You have two options for how the iOS app reaches your desktop.

Option A — Local Network (simpler)

Use this if your iPhone/iPad and desktop are on the same Wi-Fi network.

  1. 1.Find your desktop’s local IP address.
  2. 2.In the iOS app, go to Settings and enter the IP, port 3001, and your password.
  3. 3.Tap Test Connection. A green tick means you’re ready.

Option B — Tailscale (recommended)

Tailscale creates a private encrypted network between your devices. Use this to connect from anywhere — a coffee shop, another city, or just a different Wi-Fi network at home.

  1. 1.Download Tailscale on your desktop from tailscale.com and sign in.
  2. 2.Download Tailscale on your iPhone/iPad from the App Store. Sign in with the same account.
  3. 3.On your desktop, open the Tailscale app and copy the machine’s Magic DNS hostname.
  4. 4.In the iOS app Settings, enable “Use Tailscale”, paste the Magic DNS hostname, set port 3001, and enter your password.
  5. 5.Tap Test Connection to confirm.

Your Tailscale hostname is stable and never changes, so you only need to set this up once.

Step 3: iOS App — First Launch

When you open the app for the first time and connect, a welcome screen explains how the approval system works. Tap Continue when you’re ready.

You’ll be prompted to enable Face ID or Touch ID if you want biometric lock. This protects access to your server connection and chat history — recommended if others use your device.

Step 4: Review Security Settings (Recommended)

Before your first session, review these settings in the desktop server under Settings > Security & Server. The most important one, Sandbox Mode, has its own full explanation in Part 2 — Understanding Security.

Approval Timeout

When Claude sends an approval request, it waits for your response before continuing. If you don’t respond within the timeout period, the request expires and Claude will let you know.

Options: 5 minutes, 10 minutes, 20 minutes (default), or 2 hours. You can change this in both the desktop server and the iOS app — both update the same setting.

Execution Logging

The server can log every tool call Claude makes — the tool name, command or file path, timestamp, and whether it was approved. File contents and secrets are never logged.

Choose a retention period (7 days, 30 days, or disabled) in Settings > Security & Server. Logs are stored locally at ~/.satellite/execution_log.json and never uploaded.

Step 5: Approve Your Device

This is the step most often missed. A correctly configured phone with the right IP, port, and password will still appear stuck on “Connecting” or “Awaiting Approval” until you approve it on the desktop. The connection is not broken — the server is waiting for you to say yes.

Cli.nt is designed so that no device can talk to your computer until you have explicitly approved it on the desktop, in person. Even a device with the correct password is held in a pending state until you click Approve. This is what stops a stolen password from giving anyone instant access to your machine.

The first-connection flow

  1. 1.On the phone: enter the server’s IP/hostname, port, and password, and tap Connect.
  2. 2.On the phone: the app shows “Awaiting Approval” — this is normal. Leave it open.
  3. 3.On the desktop: a notification appears, and a new entry shows up under Settings > Devices marked Pending.
  4. 4.On the desktop: click Approve next to the pending device. You can also rename it here — for example “Andy’s iPhone” — so future approvals are easier to identify.
  5. 5.On the phone: the connection completes automatically within a second or two. You’re in.

Revoking a Device

If you lose your phone, sell it, or just want to disconnect a device, open Settings > Devices on the desktop, find the device in the list, and click Revoke. The device is disconnected immediately and cannot reconnect — even with the correct password — until you re-approve it.

Why Approvals Don’t Transfer

Approvals are per-device. If you reinstall the app, restore from backup to a new phone, or change the iOS device’s installation ID, the new install appears as a new pending device. This is intentional: a fresh install on a different device can’t silently inherit trust from the old one.

Troubleshooting Approvals

  • Phone says “Awaiting Approval” but nothing shows on the desktop: the phone probably can’t reach the server at all. Check the IP/port and that Tailscale is connected on both ends. The approval flow only triggers once the network handshake succeeds.
  • Phone says “Approval denied”: you clicked Revoke, or never clicked Approve and the request expired. Re-tap Connect on the phone, then approve on the desktop.
  • You don’t see Settings > Devices: make sure the desktop server is on the current build.

Part 2

Understanding Security

Cli.nt is built around one idea: you stay in control of everything Claude Code does on your machine. Part 1 covered the first layer — no device can connect until you approve it in person. This part covers the protections that apply once you’re in a session: where Claude is allowed to act, how “Always Allow” really works, and the one risk — prompt injection — worth understanding before you start. The day-to-day mechanics of approving actions live in Part 3 — Daily Use; this part explains the why behind them.

Sandbox Mode

When on (the default), Claude Code’s file actions — reading, writing, and editing files — are confined to the project folder you set for a session. It cannot read or change files outside that folder.

Important: Bash (shell) commands are not path-checked the same way. A shell command can still reach the wider system, so Sandbox Mode does not contain it. For Bash, the real protection is the approval card — read the literal command before tapping Yes. See Always Allow and Prompt Injection below.

Recommendation: Keep Sandbox Mode on unless you have a specific reason to need cross-project access.

Understanding “Always Allow”

When you tap “Always Allow” on a card, that choice is remembered only for your current session, and only in the app’s temporary memory — nothing is written to a file on your desktop. As soon as the session ends — you start a new chat, disconnect, or close the app — the choice is forgotten, and that tool type will prompt for approval again the next time.

  • This makes “Always Allow” safe: a choice can never quietly follow you from one session into the next.
  • The simplest way to reset everything you’ve approved during a long session is just to start a fresh session. There’s no file to find or clean up.

Note: If you also use Claude Code in a desktop terminal

Cli.nt drives Claude Code — the same engine you can also run directly in a terminal on your desktop. If you do, it’s worth knowing that the terminal version handles “Always Allow” differently from the app: it saves the rule to a file inside your project (.claude/settings.local.json), and that rule stays there permanently — across restarts and across every future session — until the file is edited. Because both share the same project, this can affect what you see in the app:

  • If a command is already approved in that file, Claude Code approves it silently and no approval card is ever sent to your phone.
  • So if you ever expected an approval card and didn’t get one — for example, for a git command — it usually means a rule for it is already saved in that file from earlier terminal use, not that the app skipped it.

To clear those saved rules, just ask Claude during a session — for example, “remove the saved permission rules in .claude/settings.local.json” — and it will edit the file for you. This applies only to rules written by terminal use; the app’s own “Always Allow” never needs clearing, because it disappears on its own when the session ends.

“Always Allow” and Prompt Injection

Claude Code reads a lot of untrusted content as it works — files in your repo, code from dependencies, web pages, command output. It’s possible for malicious instructions to be hidden inside any of that content and attempt to steer Claude into running something you didn’t intend. This is called prompt injection, and it’s an inherent risk of any AI agent, not specific to Cli.nt.

Your approval cards are the defence: nothing runs until you say yes. Keep that in mind when using “Always Allow,” which approves a whole tool type for the rest of the session rather than the single command in front of you:

  • Never use “Always Allow” for Bash. Approving one harmless command like “Bash: ls” pre-approves every Bash command for the rest of the session — including destructive ones like deleting files — and you won’t be shown them. The same caution applies to Write and Edit.
  • Reserve “Always Allow” for read-only tools like file reads and searches, where the worst case is Claude seeing something, not changing or deleting it.
  • Bash commands are not contained by Sandbox Mode the way file edits are. Sandbox Mode restricts file reads and writes to your project folder, but a shell command can reach more of your system. Approve them deliberately.
  • Read the literal command, not just the plain-English description. Injection works by making the description sound benign while the actual command does something else. The raw command on each card is the source of truth.

If anything on an approval card looks unrelated to what you asked for — an unexpected network call, a file path outside your project, a command you didn’t prompt — Deny it. That instinct is exactly what the approval system is for.

Part 3

Daily Use

Starting a Session

A session is a conversation with Claude Code that has its own context, history, and project folder. You can have many sessions — one per project, feature branch, or task.

  1. 1.Tap the hamburger menu (top-left) and select New Session.
  2. 2.Give the session a name — something like “Auth refactor” or “Fix login bug” makes it easy to find later.
  3. 3.Set a working folder. This is the root directory Claude Code will work in for this session, and the sandbox boundary if Sandbox Mode is on.
  4. 4.Tap Connect (the green dot, top-right) if you’re not already connected.

Sending Messages

  • Type in the input field at the bottom and tap the send button. Responses stream in as Claude works.
  • To attach images, tap the photo icon. You can attach up to 4 images per message.
  • To stop a response mid-stream, tap the Stop button that appears during generation.
  • To switch models (Haiku, Sonnet, Opus), tap the model selector above the input field.

Approving Actions

When Claude Code wants to do something — run a command, edit a file, create a file, or use a tool — it pauses and sends you an approval card. The session waits until you respond.

Each approval card shows

  • A plain-English description of what Claude intends to do
  • The raw command or file path it will act on
  • The tool type (Bash, Edit, Write, etc.)

Your three options

Approve

Allow the action to proceed

Deny

Reject the action

Always Allow

Approve this tool type for the session

Switched apps mid-task? Approvals don’t disappear when you leave the app. When you return, an “Approval Pending” alert appears and the card is re-displayed.

If the server doesn’t receive a response within the approval timeout, the request expires. You can continue chatting and Claude will usually explain that it needed approval and ask again.

Stuck on a pending approval? Long-press the connection button to restart the approval and agent servers.

For more on what “Always Allow” actually does, and how to use it safely, see Part 2 — Understanding Security.

Autonomous Mode

You can turn off approval prompts entirely in Settings > Advanced by toggling off “Require Approval for Changes”. When active:

  • The input bar turns orange as a visual warning.
  • All tool calls are auto-approved without prompting.
  • A confirmation dialog warns you before enabling.

Only use Autonomous Mode with Sandbox Mode enabled. Without both sandboxing and approval, Claude Code has unrestricted access to your entire system.

Managing Sessions

Your sessions are listed in the hamburger menu under Previous Sessions. Tap any session to resume it — the full conversation context and project folder are restored.

  • The session header shows the exchange count, context token count, and total tokens used.
  • Very long sessions accumulate context and use more tokens. Start a new session when switching topics or projects.
  • A “Loading context...” indicator appears briefly when restoring a session with a lot of history — this is normal.

Keeping the Connection Alive

For long-running tasks, enable “Prevent Sleep” in Settings > Connection. The screen dims to 10% brightness after a minute of inactivity to save battery, but the app stays in the foreground and the connection stays active. Tapping the screen or picking up the device restores brightness automatically.

If you close the app, it can send an approval notification within 30 seconds. After that the approval can fail. When you return to the app the agent generally tells you it didn’t have approval it needed and you can continue.

Part 4

Troubleshooting

Can’t Connect

  • Check the server is running on your desktop — look for the green indicator.
  • Re-enter your password in iOS Settings to rule out a typo.
  • For local network: confirm both devices are on the same Wi-Fi.
  • For Tailscale: confirm both devices are signed in and Tailscale shows as connected.
  • Check the port in the iOS app matches the server port (default 3001).
  • Check your firewall isn’t blocking port 3001.

Connection Drops Frequently

  • Tailscale: check the VPN is still connected on both devices.
  • Local network: try moving closer to the router.
  • Check the Cli.nt server app is still running on your desktop.

Slow Responses

  • Long sessions accumulate large context. Start a new session to speed things up.
  • Try a faster model — Haiku responds much quicker than Opus for simpler tasks.
  • Tailscale adds a small amount of latency versus a pure local connection; this is normal.

Approval Not Appearing

  • Confirm you’re connected to the server (green indicator).
  • Check “Require Approval” is toggled on in Settings > Advanced.
  • Check the server is running — approvals won’t arrive on a dropped connection.

Session Stuck / Agent Not Responding

Long-press the connection button to restart both the approval and agent servers. This recovers most stuck states without losing your session context.

Always Allow Not Working

The “Always Allow” cache resets when you disconnect — this is intentional. Reconnect and re-approve the tool type. If it’s still not working, check the server logs for approval flow errors.

Tips for the Best Experience

  • Use Tailscale so you can connect from anywhere, not just home Wi-Fi.
  • Name your sessions descriptively — “Homepage redesign” is easier to find than “Session 4”.
  • Start a fresh session when switching projects. Context from an unrelated task just adds noise.
  • Use “Always Allow” for low-risk tools like file reads and searches to reduce approval fatigue — it resets on disconnect anyway.
  • Keep Sandbox Mode on whenever possible, especially with Autonomous Mode.
  • Enable “Prevent Sleep” for long tasks so your phone doesn’t disconnect mid-job.
  • Review the literal bash command in each approval, not just the description — Claude’s intent and the actual command can occasionally diverge.
← Back to Cli.ntSupport →