API access and the access token

VirtuProbe’s API is what the app itself uses, what scripts reach, and what an agent drives. This page covers who can reach it and how that is controlled.

It listens on your machine only

By default the server binds the loopback interface, so it accepts connections from the machine it runs on and nowhere else. Another device on the same network cannot reach it, even on an open office or cafe network.

This is the setting that does most of the work. The API can read your workspace and run chains using your stored credentials, so where it listens matters more than anything layered on top.

To expose it deliberately, for instance when running the execution server in a container for a team, set:

SERVER_ADDRESS=0.0.0.0

The port the API is reachable on is shown in the app footer, next to the version (for example v2.0.0 · API :10101). Click it to copy the full address. That is the address an agent or MCP client connects to.

The access token

Every instance generates a bearer token on first start and keeps it alongside its data, readable only by your user account. You will find it in Settings, under API access token, where you can reveal it, copy it, or issue a new one.

When it is required

The token is enforced whenever the server is not bound to loopback.

That ties the requirement to the thing that changes the risk. On loopback, the only callers are programs already running on your machine as you. Once the server is reachable from elsewhere, the token is what stands between a stranger and your credentials. So exposing the server switches the token on by itself: there is no second setting to remember, and no way to end up exposed and unauthenticated by accident.

On a normal desktop install the Settings panel will therefore tell you the token is not currently required. That is honest rather than a defect. Nothing is checking it, because nothing off your machine can reach the server.

If you want it enforced regardless, set security.api-token.mode to always. Setting it to never disables enforcement entirely, including when exposed, which you should only do behind something else that authenticates.

Using it

Send it as a bearer token:

Authorization: Bearer <token>

The desktop application handles this for you. You need the token only for something you configure yourself: an agent, a script, or a CI job.

Static assets and the health check do not require it, so a container orchestrator can probe the server without credentials.

Issuing a new one

Regenerate in Settings immediately invalidates the previous token. The app itself keeps working, but anything you configured with the old value stops until you update it. Rotate deliberately rather than casually, and update your agent configuration at the same time.

API documentation

The interactive API browser is disabled in released builds. It publishes a complete map of every endpoint, which is not something a shipped application should hand out, and it is not needed to use the product.