Skip to content

Security

mocante can type into every terminal it manages, on every host it reaches. Anyone who can talk to it has that power too. This page explains what is exposed by default, how to open it up with care, and what the agents in your sessions can and cannot do.

Everything listens on localhost only. Nothing is reachable from the network until you opt in.

What Address Notes
Backend 127.0.0.1:4124 Serves the app’s control channel and terminal streams. The desktop app starts it for you, on a port the system picks.
Web UI dev server localhost:4123 Only when you run mocante from a source checkout with pnpm dev.
IDE server, one per session 127.0.0.1, on the host where the session runs Lets Claude Code in that session connect to the code view. It needs a token that only your user can read.

On a remote host, mocante runs a small agent over ssh. That agent opens no network port of its own apart from the IDE server above.

The agent hooks, the MCP bridge and the link shim on this machine reach the backend through a socket file that only your user can open (server.sock in the config directory points at it), so they need no token there. When that socket cannot open, the backend writes the port it listens on to server-port in the config directory, and they reach it over TCP with the token from auth-token.

The desktop app talks to the backend with a token it creates at each launch. It makes two kinds of outbound request of its own, both over HTTPS: the update check, and crash reports to Sentry, which are on by default. It installs a downloaded update only when its size and checksum match, and on macOS only when its signature matches the running app.

In the desktop app, nobody: every connection to its backend’s port needs a token, from a program on the same machine too. Other users of a shared machine reach the same localhost, so being local proves nothing there. The hooks and tools above use the socket file instead, which only your user can open.

With a source checkout (pnpm dev), a program on the same machine that connects to the backend is trusted without a token. A web page in your browser is not, even though it runs on the same machine. mocante reads the page’s origin, which a page cannot fake, and the host name the page was loaded from:

  • mocante’s own page on localhost, 127.0.0.1 or ::1 counts as local.
  • A page on any other localhost port does not, such as a dev server you open in the built-in browser. It still loads and works as usual; it just cannot control mocante without the token.
  • A page from a hostname you named in MOCANTE_ALLOWED_HOSTS or MOCANTE_ALLOWED_ORIGINS counts as local.
  • Any other page, including one in a sandboxed frame or one served from a bare IP address, must present the machine token.
  • A page whose host name only points at your machine, which is how a DNS rebinding attack works, must present the machine token too.

So a site you happen to visit cannot open a connection to mocante and drive your sessions.

Any client that is not local must present the machine token. Where the token comes from depends on how you run mocante:

  • The desktop app makes a new random token each time it starts its backend, and hands it to its own window. Nothing is written to disk, and a leaked token stops working when the backend stops or you quit the app. Set MOCANTE_TOKEN in the environment to use a fixed token instead.
  • A source checkout (pnpm dev) keeps its token in auth-token in the config directory (~/.config/mocante by default), readable only by you. mocante creates the file the first time the backend starts, and MOCANTE_TOKEN overrides it. The backend prints the path of the file when it starts, never the token.

A browser passes the token once in the address, as ?token=<token>. The web UI then keeps it for the tab and removes it from the address bar, so a screenshot of the address bar does not show it.

The token goes only into the web UI’s own connection. A link that leaves the app carries a short-lived permission for one thing instead: a download link names one file and stops working after five minutes, a shared file’s address opens that share alone, and a pop-out window’s address can be used once. So a file you drag from the code view onto a web page gives that page the file and nothing more.

Treat the token like a password. Anyone who has it and can reach the port has full control of your sessions. If the token from auth-token leaks, delete the file and restart pnpm dev to get a new one.

Only a source checkout serves the web UI to other machines. The desktop app does not. There are two ways to open it from another machine.

With the token (recommended). Make the web UI listen on the network, then open it with the token:

Terminal window
MOCANTE_HOST=1 pnpm dev

Then open http://<machine>:4123/?token=<token from auth-token>. The backend stays on localhost, and the web UI reaches it for you. A browser on another machine is not trusted by its address, so without the token it gets nothing.

Through a hostname you trust, with no token. Name the host in MOCANTE_ALLOWED_HOSTS, for example a tailnet name:

Terminal window
MOCANTE_ALLOWED_HOSTS="myvm.example.ts.net" pnpm dev

A page opened from a hostname you name here, on the web UI’s port, is trusted like a local page, so it needs no token. A leading dot allows a whole domain, for example .example.ts.net. For a reverse proxy that passes the browser’s origin through, such as tailscale serve, you can instead list exact origins in MOCANTE_ALLOWED_ORIGINS.

Prefer HTTPS for a remote browser, for example with tailscale serve --bg 4123. Browsers give clipboard access only to a secure page, so over plain HTTP, copying from the terminal can fail and Paste in the terminal menu is greyed out.

See settings for every environment variable.

What an agent in a session can do through mocante

Section titled “What an agent in a session can do through mocante”

An agent runs as your user in a normal shell, so it can already do whatever your user can do on that host. mocante adds a few things on top, each with a limit.

Session tools. mocante gives an agent tools about its own session, and tools that reach further: message the agent in another session, start a session with an agent in it, clone a repository as a workspace, and add a project. A call that renames or closes the session, restarts a dev server, runs JavaScript in a page, or starts a session waits for you to approve it in mocante. So do browser calls and messages to other sessions on the same host, when Ask before an agent drives the browser or Ask before an agent messages another session is on; both are off by default. A message to, or a stop of, an agent on another host always asks. The request shows every value the call passes, in full, and the call runs on exactly those values; a call too long to show is refused. You allow each kind once, or for the rest of the session, and you can revoke an approval for the session at any time. A clone or a new project asks on every call, since it names a URL or a folder you should see. A clone accepts only https, ssh and git URLs, never a URL that makes git run a program. A call nobody answers fails after 100 seconds. An approval for the session lasts until you revoke it, the session is removed, or the backend restarts. A session that an agent started cannot start sessions itself, and one session can run at most eight of them. Reading the session’s details, listing sessions, workspaces and dev servers, reading their logs and sharing a file need no approval.

Touch ID. On a Mac, Touch ID for risky approvals makes allowing a 1Password read, or a call that acts on another host, also need your fingerprint. It is off by default.

The built-in browser. An agent that drives the browser cannot use it to reach mocante’s own ports.

Links. A program can open a link in your browser through Open links from sessions. mocante accepts only http and https links up to 8 KB, and at most 5 links in 10 seconds for each host. It refuses file: links and app URL schemes. Turn the setting off to stop this. See links.

Clipboard. A program can copy text to your clipboard. It cannot read your clipboard: mocante ignores requests to read it, so a process on a remote host cannot see what you copied.

Shared files. An agent can share a file from its host with you, up to 100 MB. mocante counts the bytes as they arrive, so a host that sends more than that is stopped at 100 MB and nothing is kept. mocante stores it in its cache folder under a name it makes itself, so a share cannot write anywhere else. A shared file opens as data in the app, not as a web page.

Dropped files. A file you drop onto a session lands in ~/.cache/mocante/drops/ on the session’s host, up to 1 GB. It streams to the host over ssh and is private to your user while it arrives. Its name is cleaned so it cannot leave that folder.

Uploads and downloads. The code view’s file tree reaches only the session’s worktree. A path cannot leave it with .., a leading / or a link that points out of the worktree, and nothing can be uploaded into or downloaded from .git, in any spelling or through a link, where git would run a file as a hook. An upload never replaces a file unless you select Replace.

Git. Git actions run only in the workspace folder or in the worktree of one of its sessions.

Claude Code IDE connection. A Claude Code that connects to the code view can open files of its session, save them, and show a proposed edit. The edit is written only when you accept it.

The desktop app opens mocante:// links. Any web page can open one, so a link only takes you somewhere: it cannot type into a session, run anything, approve anything or change anything. See mocante links.

mocante uses your system ssh and your ~/.ssh/config. It opens two kinds of connections to a remote host:

  • Background connections for health checks, tmux queries and commands never forward your ssh agent, ports or X11, whatever your ssh config says. So they do not leave an agent socket on the host.
  • Terminals, commit and push follow your ssh config unchanged. If you forward an agent, for example a 1Password agent that signs your commits, it is available in your tmux panes and to commit and push, as in a normal ssh session.

When you reconnect, mocante points every pane of the host at the newest forwarded agent. With two devices attached to one host, the panes use the agent of the device that attached last.

Log in over ssh… on the Hosts page opens a plain ssh login so you can answer a host key question or a password. It forwards nothing.

The first time mocante connects to a host, it records the identity the host reports. If a later connection reports a different identity, or a new address claims the identity of a host you already have, mocante refuses to run commands there, opens no terminal, push or port forward to it, closes the ones that are open, and shows the mismatch on the Hosts page. Your forwarded ssh agent never reaches that address until you accept the new identity. If you know why it changed, for example you reinstalled the machine, use Trust new identity… to accept it. See remote hosts.

The desktop app sends its errors and crashes to the mocante team through Sentry. It also sends performance traces for one run in ten. The web UI sends nothing.

A report does not include your terminal output, and it does not include your machine’s hostname. A report can still hold a file path or a line of command output, because some errors quote the command that failed. Sentry can also estimate a coarse location from your connection.

Remote hosts report crashes of the mocante helper program too, but only while crash reports are on.

To stop the reports, turn off Send crash reports in Settings › Updates. The change takes effect the next time you start the app.

If sync.automerge or settings.json in the config directory is damaged, mocante keeps it beside the original as <name>.corrupt-<time>, reports it, and starts with an empty one. Your projects, hosts and workspaces come back from another device’s copy if you sync; without sync, the .corrupt- file is what is left of them.

Remove with files on a workspace deletes its folder only when the host is connected, and refuses your home folder, a folder that holds it, a folder right under the root, and a folder that holds another workspace. It checks the path as you typed it and the folder that path reaches through links, and deletes only that folder.

  • The auth-token file and any MOCANTE_TOKEN you set. Do not paste a ?token= address into chats or tickets.
  • The config directory, ~/.config/mocante. It holds the token, your projects, hosts and workspaces, and the host identities mocante trusts.
  • Your sync folder, if you sync between devices. It holds your projects, hosts and workspaces. It does not hold the token.
  • The cache directory, ~/.cache/mocante. It holds files that agents shared with you.
  • The web UI port when you expose it with MOCANTE_HOST or MOCANTE_ALLOWED_HOSTS. Anyone who can reach it controls your sessions.