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.

What listens by default

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.
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 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.

Who counts as local

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:

• A page from localhost, 127.0.0.1 or ::1 counts as local.
• 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.

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

The machine token

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 and hands it to its own window. Nothing is written to disk, and a leaked token stops working when 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.

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.

Reach the web UI from another machine

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:

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:

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

A page opened from a hostname you name here 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.

Caution

MOCANTE_ALLOWED_HOSTS and MOCANTE_ALLOWED_ORIGINS give full control of your sessions, with no token, to anyone who can reach the web UI through a name or origin you list. List only names that resolve on a network you trust, such as a private tailnet.

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

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. They act only on the session the agent runs in. The first call in a session that renames or closes it, restarts a dev server, drives the built-in browser, or runs JavaScript in a page waits for you to approve it in mocante. You approve each of those three kinds once per session. A call nobody answers fails after 100 seconds. An approval lasts until the session is removed or the backend restarts. Reading the session’s details, listing dev servers, reading their logs and sharing a file need no approval.

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 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 10 MB. Its name is cleaned so it cannot leave that folder.

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.

SSH and agent forwarding

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.

Caution

A forwarded agent can sign with your keys for as long as you are attached. Any program on the remote host that runs as your user, an agent included, can use it. Forward an agent only to hosts you trust, and prefer an agent that asks you to approve each use.

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.

Host identity

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 and shows the mismatch on the Hosts page. If you know why it changed, for example you reinstalled the machine, use Trust new identity… to accept it. See remote hosts.

Crash reports

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.

What to keep private

• 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.