FAQ

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.

The one thing it can change is the size of a window, because two clients on one session cannot both pick it. That is a choice you make: resize_policy, and the lock button on each terminal.

Why is there no Docker image?

Because the whole point is that it reaches your tmux socket and your filesystem. In a container you end up bind-mounting both, and the isolation you paid for is the isolation you gave away.

If you want one anyway, it is a short Dockerfile and a --pid=host --network=host you should think hard about.

Does it phone home?

It asks github.com once a day whether a newer tag exists, 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. 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 and Codex: 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?

Two patterns, one button — Two agents, in the desk's toolbar. Either they work towards one goal with a plan file saying who owns which file, or one builds and the other reviews and never edits. Argus writes the plan and sends each of them the prompt that points at it; nothing is installed inside the agent, so it works with whatever you run.

The reviewing one ends on VERDICT: OK or VERDICT: REDO, and Argus can read that line and hand a REDO straight back — off unless you switch it on, per desk, and counting down, because two agents bouncing a change between them for six hours unattended is a novel way to spend money rather than a feature. Two agents on one job has the lot, including what it deliberately will not do.

Can a prompt press Enter for me?

Yes — a prompt carries a ↵ mark if it should send itself, 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 this app's palette rather than mermaid's own themes, 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 — app.js 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 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 you write (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.

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.

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 → Add a language, 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.