Sign in to your organisation

Each Build app signs in to your organisation's Neural Inverse Govern deployment with your own account. Your organisation's policies apply to agents, models and tools after you sign in.

Which deployment the app uses

Your administrator decides which Govern deployment the apps sign in to.

Editor and Agents app, strongest first:

1. A build locked to one address by your organisation. Managed policy and settings are then ignored.
2. The managed policy NeuralInverseKeystoneBaseUrl, set through MDM, Group Policy or the policy file.
3. The user setting neuralInverse.keystone.baseUrl, for self-hosted deployments. A workspace (a cloned repository) cannot set it.
4. The address the build ships with.

An address that is set but not valid stops sign-in with a reason. The app never falls back to a weaker source.

CLI: the keystone.baseUrl setting in your user settings or in the organisation's managed settings. A project's settings cannot set it. neuralinverse login --base-url <url> uses another address for one sign-in, unless managed settings fix it.

How the app checks the deployment

Before you sign in, the app checks the address:

1. It reads /.well-known/keystone-region from the address. This names the region, the issuer and the API address.
2. It reads the issuer's OpenID configuration, which must name the same issuer. The issuer is then pinned.

The app refuses the deployment, with the reason, when an answer is not HTTPS, redirects, is not valid JSON of the expected shape, or names a host outside the address's own domain. Tokens are only ever sent to the deployment that issued them.

Sign in with the browser

This is the default in the Editor and the Agents app, and in the CLI on a machine with a browser.

1. Start sign-in. In the Editor and the Agents app, the sign-in screen shows Server: <host> - <region> before anything else happens, and warns you when the address came from your own user setting or could not be verified. Choose Sign In.
2. Your browser opens your organisation's sign-in page. Sign in with your organisation account.
3. The browser returns to the app on a loopback address (http://127.0.0.1:<random port>/callback). The app shows Signed In.

The app uses OAuth 2.0 authorization code with PKCE. Where the deployment advertises it, the authorization response must name the same issuer the app discovered (RFC 9207); otherwise the sign-in ends and the code is not used.

In the CLI:

neuralinverse login                  # opens your browser and prints the URL
neuralinverse login --no-browser     # only print the URL

Over SSH, open the printed URL in a browser on the machine that runs the CLI (or forward the port), because the browser returns to that machine's loopback address. The CLI gives up after 10 minutes.

Sign in with a device code

Use this on a machine with no browser, for example over SSH. It uses the device authorization grant (RFC 8628).

1. Start a device sign-in:
   • Editor or Agents app: on the sign-in screen choose No browser on this machine? Sign in with a device code, or run the command Sign In to Neural Inverse with a Device Code.
   • CLI: neuralinverse login --device. In an SSH session, and on Linux with no display server, neuralinverse login uses a device code by itself. --browser forces the browser flow.
2. The app shows a code and the address of your organisation's verification page (in the Editor and the Agents app, with Open the page and Copy the code). The address must be on the deployment's own domain; any other address is refused before a code is shown.
3. On any device with a browser, open the page and sign in. The page shows:
   • the name of the app asking to sign in, with a warning if it is not an app made by Neural Inverse;
   • who you are signed in as;
   • when the request was made, and the network address and software it came from;
   • the account the device signs in to. If you belong to several accounts, choose one; none is preselected.
4. Approve or deny. The app waits for your decision and then completes the sign-in.

Only enter a code you started yourself. Codes are 8 letters and stop working after 10 minutes. If your organisation enforces single sign-on for its domain, only a session signed in through that connection can approve.

After you sign in

• Where the session is kept. Each app has its own session in the operating system's credential store: Keychain on macOS, DPAPI on Windows, the Secret Service on Linux. When no credential store works, the session is kept in memory for that run only, and the app tells you.
• Your account. The account menu (Editor and Agents app) and neuralinverse account show (CLI) show your name, email, account, 12-digit Account ID, Account Region, the server and the app.
• The connection at a glance. The Editor's status bar and the Agents app's title bar show whether you are signed out, connecting, connected (Keystone: <region>), degraded with a reason code, or locked by your organisation's policy.
• Signing out. Use the account menu, or neuralinverse logout in the CLI, which revokes the session and deletes the local tokens. Signing out of the Editor or the Agents app also signs the CLI out at its next start.

In the CLI, neuralinverse whoami shows the account, device and policy state (--json for scripts).

When sign-in fails

Every failure shows a sentence that says what happened and what to do, ending with a reason code in parentheses. Give the code to your administrator.

A network failure names its cause where it can: DNS, TLS (often a corporate proxy or inspection certificate), connection refused, offline or proxy.

If the server does not recognise the app (invalid_client), your Govern deployment is probably older than the app. Your administrator can upgrade it, or set the client id described below.

For administrators

Each Build app signs in with its own public OAuth client, so sessions, the device list and audit records say which app they belong to:

Govern registers these clients itself. They have no secret, require PKCE (S256) for the authorization code grant, and accept loopback redirects on any port.

Set the deployment address for your organisation:

• Editor and Agents app: the managed policy NeuralInverseKeystoneBaseUrl.
• CLI: keystone.baseUrl in the managed settings file, for example:

// /etc/neuralinverse/managed-settings.json (Linux)
// /Library/Application Support/NeuralInverse/managed-settings.json (macOS)
// %ProgramData%\NeuralInverse\managed-settings.json (Windows)
{
  "keystone": {
    "baseUrl": "https://keystone.example.com",
    "requireSignIn": true
  }
}

With requireSignIn, the CLI refuses model calls and tools until the person signs in.

Only for a self-hosted Govern deployment older than the per-app clients, set the client id that server knows: the managed policy NeuralInverseKeystoneClientId for the Editor and the Agents app, or keystone.clientId in the CLI's managed settings. Neither can be set from a user setting, a project or an environment variable, and the apps never try another client id by themselves.