Run ARMANOS without a screen

Server mode runs ARMANOS where nobody looks at the window: on a server, in a virtual machine, next to a script that does all the work. The window stays hidden, the local API starts on a fixed port with a key from the environment, and the program signs in without a form.

Start in server mode

Start the program with --server, or set ARMANOS_SERVER=1. It then needs the key of the local API in ARMANOS_API_TOKEN, 24 characters or more, or in a file named by ARMANOS_API_TOKEN_FILE.

The key is never taken from the command line, since other users of the machine see it in the process list. The key and the sign-in code leave the environment at start, so no browser process inherits them.

ARMANOS_API_TOKEN: Key of the local API, 24 characters or more
ARMANOS_API_TOKEN_FILE: A file that holds this key, for Docker secrets
ARMANOS_API_PORT: Port on 127.0.0.1, 50325 by default
ARMANOS_OUT_DIR: Absolute folder for exports and flow data files, out in the data folder by default
ARMANOS_LOGIN_CODE: One-time sign-in code from the Dashboard
ARMANOS_API_KEY: Account API key with the right to sign the program in

Exit code 2 means the key or a setting is wrong, and the message says which. Exit code 3 means the port is taken: the program does not move to another port, because your script calls this one.

What changes in server mode

The window never shows
It exists hidden, so everything it does in the background keeps working.
The local API is always on
On 127.0.0.1 only, as on a desktop; the switch on the For developers screen is not used.
Notices go to the log
A line that starts with ARMANOS notice, in the standard output, instead of a system notification.
Sites get no permission prompt
Every profile refuses permission requests without a window, the way a flow run does, so a page does not wait for an answer nobody gives. The location of a profile set to "Share without asking" still goes to the site, the same as with a window.
No update checks
To update, install the new version.
One status line at start
It names the API address, the account, the engine with its version and the video card. The key is not in it.

Sign in without a form

POST /api/v1/app/login takes one of three bodies. A program already signed in with the same account answers alreadySignedIn and spends nothing, so a script can call it at every start.

Without the second-step number the answer is two_factor_required. The password goes in the body only; in the address it is refused.

The code from the Dashboard lives two minutes and works once. The right to sign the program in with a key is off by default; revoking the key ends the program's sign-in at the next token refresh.

{"code": "…"}: Code from the Dashboard: Devices, then Sign in on a server
{"email", "accountPassword", "twoFactorCode"}: The same sign-in as in the window, with the second step
{"apiKey": "ak_…"}: An account key from API keys in the Dashboard, with the right to sign the program in

State for a script

GET /api/v1/app/state answers whether the program is signed in and as whom, the plan and its profile limit, the engine and its version, how many profiles are open, the video card, the port and whether server mode is on.

The open /status call stays as it was, without the key. It names no email, because anyone on the machine can call it.

Without a video card

A server usually has no video card. ARMANOS Browser then opens profiles without WebGL and WebGPU, and a site can tell such a machine from the one in the profile template.

ARMANOS says so openly: gpu none in the status line and in app/state, and note no_gpu_webgl in the answer of browser/start and profile/quick.

Software rendering stays off

The program does not switch on software graphics by itself: under a real video card name it would report the limits of a software renderer. A profile that must look like a desktop needs a machine with a video card.

Stopping the program

SIGTERM, Ctrl+C and Quit ARMANOS in the menu close the open profiles and wait up to 8 seconds for our server to release their locks, so a teammate does not see a profile busy after you stopped. A server that does not answer does not hold the exit longer.

With the window, quitting waits for the locks the same way. But if the ARMANOS window is visible and profiles are open, the program first asks whether to close them, and the exit waits for the answer; without a visible window there is no question.

What this does not do

It does not open the local API to other computers. Calls come from this machine alone.
It does not take the key from the command line. Use the environment or a file.
It does not update itself. A new version is installed on top.
It does not show the window. Everything goes through the API and the log.

Where this is decided

Each line below names the stand that checks it.

Exit codes 2 and 3, the hidden window, the key kept out of the environment and the output, sign-in by code, by email and by key, the refused permission prompt: apps/desktop/test/режим-сервера.js, apps/desktop/test/режим-сервера-живьём.js
The exit waits for the server to release profile locks, with a limit: apps/desktop/test/выход-ждёт-замков-живьём.js
Sign in on a server in the Dashboard shows the code and commands without a key: apps/web/test/вход-на-сервере-кабинет.js
The right to sign in with a key is separate, and revoking the key ends the sign-in: apps/server/test/вход-ключом-устройства.js

Questions

The program exited right away with code 2.: The key is missing, shorter than 24 characters or given on the command line. The line in the error output names the reason.
The program exited with code 3.: Another program holds the port. Stop it or set ARMANOS_API_PORT to a free one.
How does my script know the program is ready?: Call /status until it answers, then GET /api/v1/app/state to see whether the program is signed in.

Next to this

Try it on one machine

The free plan gives two profiles, with no time limit and no card.

Download opens at launch Knowledge base