FAQ

The questions people actually ask, answered without hedging. Where the answer is "no", it says no.

Can I put this on the internet?

No. Argus is remote shell access wearing a browser: anyone holding the token can run anything you can. Put it on a LAN, or behind a VPN, or reach it through an SSH tunnel. If you want it from outside, read this first.

Nothing about the design changes that. The token is compared in constant time, the file jail refuses .., absolute paths outside the roots and symlinks pointing out of them — but a shell is a shell.

Does it change anything about how I use tmux?

No. It attaches as an ordinary client, the way a second terminal window would. Kill Argus and every session carries on; it keeps no state your work depends on.

What it changes in tmux it changes because you asked: the size of a window (two clients on one session cannot both pick it — resize_policy, and the lock button on each terminal), a session's look or the tmux config when you apply one, and the sessions you start or end.

Is there a Docker image?

Yes: a Dockerfile and a docker-compose.yml in the repository, and an image at ghcr.io/andreaderuvo/argus with every release. See Getting started.

It is a way to get the runtime, not a sandbox. The whole point is that Argus reaches your tmux socket and your filesystem, so the container is handed both — pid: host, your uid, your home at the same path, the tmux socket — and the isolation you might expect is given away on purpose.

Does it phone home?

It asks github.com once a day for the latest release, and says so once if there is. It sends nothing doing it: no identifier, no configuration, not even which version is running. It never updates itself.

check_releases: false      # and it never asks

Nothing else leaves the machine on its own. What you can turn on, each of which you set up or press: ntfy notifications (ntfy), reporting to a board (report_to), what is my public address on the System screen (ask_outside), and fetching a link into a folder. There is no analytics, no error reporting, no account.

Something is running and I want to know when it finishes. Can it tell me?

Yes, per session, and it can tell finished apart from asking you something. The setup is one button for Claude Code, Codex and Gemini (Settings → Let your agents ring), or the Argus plugin for Claude Code and Codex (Gemini CLI gets its tools as an extension). See Notifications.

Browser notifications normally need HTTPS. Over plain HTTP on a LAN there is a way round it, and that page has it.

Can two agents work on the same thing without me in the middle?

Yes: a team, from Team in the desk's toolbar. A team is a graph of steps — seven templates (Optimise, Tournament, Split the work, Fix a bug, Feature with tests, Build and review, Write) that you change with a click, with your own roles, saved as your own models. Two agents can split the work (a planner gives each one its files, both work at once in the same folder), or one builds and the other reviews, or two try different ideas in their own worktrees and a reviewer keeps the better one. Argus prompts each in turn, runs your tests or benchmark between turns, and stops where you told it to: at every round, at the first trouble, or at the goal, with a limit on rounds either way. It works with any agent; with the Argus plugin installed, each agent reports its turn through a tool and is sent back if it stops without doing so. A team can also be written as a Mermaid flowchart — or you can ask an agent to design it: it writes it, checks it and proposes it, and you start it. See Teams. (The older Two agents button is gone; its page remains for pairs started with it.)

Can a prompt press Enter for me?

Yes — every prompt in the list says sends (it presses Enter) or types (you do), and the ones that hand work over deliberately do not: what to do with a handover is the point of handing it over.

The return goes as a separate write half a second after the text, which sounds like a detail and is the whole thing. An input box does not read lines, it reads writes: a box that assembles a paste treats everything arriving in one read as part of the paste, so a return sent along with the text lands in the box and the prompt sits there unsent. Claude Code submits it anyway, Codex does not, and that difference was the bug. The gap is in Settings if one of your agents wants longer.

Why does typing in the terminal duplicate letters on my phone?

That is xterm.js #3600 and it is not something an app can fix from outside: Chrome on Android wraps Enter and Backspace in composition events of its own, and interrupting one makes the word arrive twice.

So there is a way in that never meets it — the compose box, an ordinary text field where predictive typing behaves as it does everywhere else. The finished line goes to the session in one go.

It was working, then I logged out of SSH and it went away

systemd --user stops your services when your last session ends, and argus.service is one of them. One command, once:

sudo loginctl enable-linger $USER

After that it starts with the machine and stays whether or not you are logged in.

I lost my phone. Do I have to change the token everywhere?

Not if that phone had its own. Settings → Devices → Revoke, and it is out on its next request; every other device carries on untouched.

If it was using the token from the config, then yes — rotating that one signs out everything, which is exactly the reason per-device tokens exist. Worth setting up before you need it: Security.

How would I know if somebody had been in?

Journal, in the sidebar. It keeps everything that changed something and everything that was refused, with the address each came from — and refusals are the signal. A handful from your own machines is ordinary; a run of them from an address you do not recognise is not.

Successful reads are not kept, on purpose: a log full of folder listings is a log nobody opens, and it would push the interesting lines out of the file.

It is not tamper-proof. Anything holding the main token can delete it. See Security.

Who can read my files?

Whatever is under roots, and nothing else. Everything is resolved and checked against that list, symlinks included — a link inside the jail pointing at /etc is refused, which is the escape that catches most path checks.

Writing is off unless you ask for it with --allow-write.

Can two people use it?

Not really. One token, one machine, one person's work. Two browsers can attach to the same session — tmux allows that, and they will fight over the window size unless one of them locks — but there are no accounts and no per-user anything.

Does it draw mermaid diagrams in a markdown file?

Yes. A fenced block whose language is mermaid is drawn — in mermaid's own themes by default, or the app's palette (Settings → Documents → Diagram colours) — and it redraws when you switch theme. The library is vendored like everything else and loaded only when a document actually has a diagram in it.

If one does not appear: reload the page — the app's code (app.js and its modules) is fetched when the page loads, so an old tab keeps running yesterday's copy however many times the server is restarted. If after a reload you see neither the diagram nor a line saying the diagram library did not load, the copy you are looking at is older than this feature.

My phone will not offer to install it. Can I have two Argus apps installed at once?

Two, or ten. A browser identifies an installed app by its origin — scheme, host and port — so each machine is its own app and installing one has nothing to do with the others. Since each manifest now carries the address it was asked for, they are told apart on the home screen instead of being three icons called Argus.

Being offered is a different matter: a browser decides on its own, decides once, and Safari never offers at all. So the offer is a button — Settings → Go to → Install it on this device — which also reports the three things it can check (a secure origin, a running service worker, a manifest that arrives) and, if all three are fine, says that the browser has simply made up its mind and where its own install command lives. See On a phone.

Can I start an agent from Argus, or only watch one?

Start one. New session — on a desk, or the first row of the Sessions screen — asks what to run — a shell, or an agent from a list in your config — in which folder, and what to say to it first; then it waits for the thing to finish starting and types the prompt in. It does not press Enter unless you say so, and never into something still drawing its banner.

If the folder is a git repository it will also make a worktree on a new branch and start the agent in there, which is how you get a second agent on the same code without the two of them editing one checkout.

Two consequences worth knowing: what it may start is a list — Claude Code, Codex, Gemini and a shell until you write your own launchers, which then replaces it (so this endpoint is not "run anything", unlike the terminal beside it), and each entry is a shell line run through your login shell, so conda activate x && claude is a valid launcher. See Starting an agent.

Can my agent ask me something, or start another agent?

Yes, if you give it the way to. The Argus plugin (Claude Code, Codex) or argus-mcp gives it tools: ask you a question and wait for the tap on your phone, ring you, see who else is working, relay a sentence to another session, start_agent (in its own worktree), open_desk and rename_desk ("open a desk called pippo with a Codex and a Claude in it"), work your to-do list (todos, todo_set, todo_add), read the teams, take part in one and design one (team_check, team_propose), and read your prompts. What its key cannot do — start or stop a team, end a session, start an agent with no questions — it may request, and you tap Do it or No. It never answers its own questions, deletes files through Argus, or removes a desk. The whole table: What an agent can do.

Which browsers?

Anything current. Chrome, Firefox and Safari are all used; the terminal is xterm.js and the PDF viewer is pdf.js, both of which Argus ships rather than relying on the browser's.

The PDF viewer is drawn by Argus precisely so the answer does not depend on which browser you have — unless you choose the browser's own (Settings → Documents → PDF viewer).

It is not in my language. How much work is adding one?

One file. A catalogue is a flat JSON object whose keys are the English strings — no gettext, no .po, no extraction step, no build, and nothing to register:

{
  "code": "de",
  "name": "Deutsch",
  "strings": {
    "Sessions": "Sitzungen",
    "up {age}": "läuft seit {age}"
  }
}

Two ways to install it, either is enough:

• Drop it at ~/.config/argus/lang/de.json. It is picked up on its own.
• Settings → Language → Import a language file…, which puts it in the same place. That is the one that works from a phone, where you have no shell.

A missing entry falls back to English, so a translation is useful the day it is started — there is no broken half. Copy static/lang/en.json to see every key. The only rule is that {age}, {n}, {path} and friends have to survive into the translation: they are filled in at the point of use, and one that is dropped leaves a hole in the sentence.

A file you drop in overrides one that ships, so a wording you disagree with can be fixed without a fork.

To send it back, open a pull request with the file in static/lang/. A test checks that every catalogue covers every string and keeps its placeholders, so a stale one cannot slip through. Panoptes works the same way, file for file.

Can a board start and stop things on this machine?

Only if you write down what it may touch, and it can never do more than that. A board sends a name, never a command:

runnable:
  - name: nightly
    run: python3 nightly.py
    cwd: /srv/work

watchers:
  - name: panoptes
    token: …
    may_run: true

There is no field in any request where a shell line could go. A name that is not on that list is refused, and stop can only kill a session that is on it — so a board cannot touch the work you did not list. See Security.

Can I turn Argus off from the board?

Yes, with may_stop_argus: true on that watcher — and it is the one action on a board that cannot be undone from there.

Your tmux sessions carry on: Argus attaches as an ordinary client and is not their parent. What you lose is the way in. Bringing it back takes a shell on that machine (systemctl --user restart argus, if that is how it runs), so it is worth having a service that supervises it before you turn this on for a machine you cannot easily reach.

The board asks twice, and says that in the confirmation.

may_stop_argus does not need may_run: a machine with nothing worth publishing as runnable can still be one you want to be able to switch off.

I have several machines

Then you want Panoptes: one page showing every machine, which sessions are on each, and which one is waiting for you. Clicking a session sends you straight to that terminal, on that machine.

It holds one watcher token per machine, in a file on its own server, and it never sends one to a browser — the page is told where a machine is, never how to get into it. By default each of those keys opens exactly one read-only door, so losing the board loses a list of session names rather than every box on it. You can widen that deliberately, per machine, to let the board start and stop things you have named or switch that Argus off; what you cannot do is give it a shell, because there is no request that carries a command.

A machine the board cannot reach can announce itself instead, which covers the ordinary case of two boxes where only one direction through the firewall is open.

Argus never depends on it. Turn the board off and every machine carries on alone.

See Security for what each permission actually opens.

Something is wrong and I want to work out what

Troubleshooting first. If it is not there, open an issue with what you did, what happened, and what you expected — and say which browser, because more than one bug in here has turned out to be a browser doing something reasonable that nobody expected.