Get started

What you need

• A computer running macOS or Linux, with curl and openssl (most have both). Windows isn't supported yet.
• A server (optional) running Linux, x64 or arm64 — a cloud VM works.
• A phone with a current browser. No app to install.
• Claude Code or Codex, installed and signed in with your own account, on each machine that runs agents. Ponte drives them with your subscription; it doesn't come with one.

Install on your computer

In a terminal:

• It downloads the ponte executable to ~/.ponte/bin and installs it only if the publisher's signature verifies.
• It asks for a device name and your address, https://<name>.ponte.sh — where you open the dashboard from anywhere. It suggests a name from your user name; names are public, so change it, or clear it to skip and pick one in the dashboard later.
• It starts Ponte as a background service (launchd or systemd), so it comes back after a reboot, and opens the dashboard at http://localhost:23513 with your browser already signed in. There's no account to create.
• Open a new terminal to use ponte. ponte open signs this computer's browser in again.

First-run setup

The dashboard opens with a short setup. Skip any step; everything is in Settings later.

• Language and Device name.
• Agents — checks Claude Code and Codex on this computer (installed, recent enough, signed in) and says what's missing.
• Permissions — how new sessions handle tool calls. The default is Run tools without asking: agents edit files and run commands on their own. Pick Ask first to approve each tool call. Each session can change it.
• Notifications — a notification when an agent finishes or needs you.
• Address — your <name>.ponte.sh, if you skipped it during install.
• Connect — add your server and your phone (the next two steps). Home keeps a Get started checklist of what's left.

Add your server

Add a server or another computer in the setup (later: Pair device, the QR icon in the sidebar, or ponte pair) shows a join command like this:

• SSH into the server and run it in that session — not as ssh host '…', which can't answer its questions. It installs the same way and asks for the server's name.
• On a server with a public IP address — most cloud VMs — it also asks whether your other devices may connect to it directly over the internet (still end-to-end encrypted). If yes, allow inbound TCP port 23512 in its firewall or the cloud's security group; until then your devices reach it through the relay.
• The server prints a confirmation code, and your computer shows the join request with its code. Approve only if the two match.
• Paired devices get full control of each other: agents, terminals and files. Pair only machines you own. Settings → Device access can make a device Receive only: the others control it, it can't reach them.
• On Linux with systemd, the installer enables lingering to keep Ponte running after you log out. Only if the installer says so, run sudo loginctl enable-linger $USER on the server; ponte doctor can check it later.
• Or, from your computer: ponte peer add --ssh user@host does all of this over SSH, lingering included. It shows its plan and asks first.

Add your phone

Add your phone in the setup (later: Settings → Account → Sign in a phone, or ponte setup phone in a terminal) shows a QR code.

• Scan it with your phone's camera and open the link. The phone signs in through the relay, end-to-end encrypted.
• Add the page to your Home Screen (iPhone: Share → Add to Home Screen), open it from there and allow notifications — you'll hear about approvals and finished work.
• Later, open https://<name>.ponte.sh in any browser. It signs in with a passkey (add one under Settings → Account) or a new QR code.

Daily use

• Start a Claude Code or Codex session from any device and choose where it runs — your server, say. It keeps working when you close the page or lock your phone.
• Sessions you start in a terminal show up too; continue them from the dashboard or your phone. Start Codex with ponte codex so other devices can prompt and stop it.
• Every device's terminals and files are a click away from the others.
• Projects: give a coordinator a goal; it delegates work to sessions across your machines and keeps a board of what waits on you.
• ponte status shows your devices; ponte sessions list lists sessions on all of them.

Updates

• Devices follow the stable channel and check for a release every hour: within an hour of one, the dashboard offers it and your devices notify you.
• Install it with one click — Update now, or Settings → Updates for any device — or run ponte update.
• Every update's publisher signature is verified before it's installed.
• If the new version doesn't start, the device rolls back to the version it ran before.
• Updates don't install by themselves unless you turn that on: ponte update auto on installs them at 05:00, once no session is working.
• What's new in the dashboard, and the changelog on this site, list what each release changes.

Good to know

• Agents run tools without asking by default. Switch to Ask first in the setup or in Settings if you'd rather approve each call.
• Sessions Ponte runs compact their context on their own: past 256k tokens after 55 idle minutes (before the prompt cache expires), and whenever the agent asks. Each compaction is a model turn on your account; Settings → Compaction turns them off.
• While an agent works, its device doesn't fall asleep when idle; Settings → General → Keep host awake changes that.
• Setup adds its hooks to ~/.claude/settings.json and, unless you set it yourself, cleanupPeriodDays: 90 — Claude Code keeps transcripts 90 days. ponte uninstall removes the hooks and leaves that setting.

What Ponte's services see

Your conversations, code and files stay on your devices, and Ponte sends no analytics or crash reports. A few services see metadata:

• The relay. When two devices can't connect directly, they go through Ponte's relay — a single one today, hk.relay.ponte.sh. What you send is end-to-end encrypted; the relay sees IP addresses, sizes and timing.
• It also serves the phone sign-in page and <name>.ponte.sh: you trust it to serve that page as published. ponte setup can point your devices at a relay of your own.
• The names service. Every 6 hours each device asks names.ponte.sh which addresses it holds; the service sees the device's public key and IP address.
• Updates. Every hour each device asks dl.ponte.sh for the newest release (npm when that fails), which sees its IP address.
• Only if you turn them on: trusted HTTPS names (ponte setup) give dns.ponte.sh your devices' IP addresses, LAN ones included, and get certificates from Let's Encrypt; the model gateway downloads Magpie from usemagpie.ai.

Uninstall

On each device:

$ ponte uninstall

$ ponte uninstall --purge  # also delete ~/.ponte

• It waits for sessions that are still working (--force doesn't), then stops the daemon, removes its launchd or systemd service, its terminals, the Claude Code hooks, the PATH line in your shell profile and the executable.
• It keeps ~/.ponte — config, device identity, database, logs — so a reinstall comes back as the same device. --purge deletes it.

When something's wrong

• ponte doctor checks the install, the daemon and its service, terminals and every agent, and says how to fix each problem.
• ponte open signs this computer's browser in to the dashboard again.
• ponte setup changes the device name, direct connections and relay, and connects a phone or another device.
• ponte status shows whether it runs and which devices are connected; ponte restart restarts it.
• Logs: ~/.ponte/ponte.log, and the service's output in ~/.ponte/daemon.log and ~/.ponte/daemon.err.