Connecting to ORE Studio

Click Add (or the "+" button) to open the New Connection form. Fill in the fields:

• Name — a free-text label you choose, used throughout the UI to identify this backend (e.g. "Local dev", "Team staging"). Must be unique among your saved connections.
• Host — the hostname or IP address of the machine running the ORE Studio backend (e.g. localhost, 192.168.1.10, ores-staging.example.com).
• Port — the TCP port the backend is listening on. The default is 35900; change it only if the backend was started on a different port.
• Environment — an optional grouping label (see Environments below). Helps you distinguish development, staging, and production backends at a glance.
• Tags — zero or more free-text labels (see Tags below). Useful for filtering and searching when you have many connections.

Click Save (or OK) to add the connection to the list. The new entry appears immediately in the Connection Browser list. No network contact is made at this point — ORE Studio simply stores the configuration.

Select an existing connection in the list and click Edit (or double-click the row) to open the same form pre-populated with the saved values. Change any field and click Save. The connection list updates immediately.

Select one or more connections in the list and click Delete (or press the Delete key). A confirmation dialog asks you to confirm the removal.

Deleting a connection removes only the saved configuration; it has no effect on the running backend or any data stored there.

When the list grows, folders keep it manageable. A folder is a named container you can nest, grouping related connections — by team, by client, or by environment tier. In the populated browser above, the connections sit under a Development → Dev → Local1…Local4 folder tree.

To create one, click Add and set Type to Folder. Give it a name and an optional description, and choose a parent folder (or No Folder to place it at the top level). Connections are then assigned to a folder through their Folder field, or by dragging them in the tree.

The passwords you save with a connection are encrypted at rest using a master password that you choose. The first time you save a credential, ORE Studio offers to create one.

Type the same value into New Password and Confirm Password; the fields turn green when they match. Show password reveals what you typed.

When you next launch ORE Studio and open the Connection Browser, it prompts you to unlock your saved connections by entering the master password. Until you do, the encrypted passwords stay sealed.

If you leave the master password blank, your connections still work but their passwords are stored unencrypted — acceptable on a personal machine, but not recommended on shared or portable systems.

An environment is a named grouping that you assign to a connection to indicate which tier of your infrastructure it belongs to. Typical values are Development, Staging, and Production, but the list is fully customisable — you can define any environment names that make sense for your setup.

Environments appear as a coloured badge or label next to the connection name in the list, making it immediately obvious which tier you are about to connect to. This is a safety feature: it is easy to accidentally connect to production when you meant staging; a clearly labelled environment badge prevents that.

See the populated Connection Browser figure under Organising connections into folders above — the same coloured chips shown there are the environment and tag labels described below.

To manage the available environment names, open the Environments section within the Connection Browser settings (or the dedicated menu item). From there you can:

• Add a new environment name and choose its display colour.
• Rename an existing environment (all connections using it update automatically).
• Delete an environment (connections that used it revert to Unassigned).

An environment is itself created from the Connection Browser: click Add and set Type to Environment. An environment carries its own host, port, HTTP port, namespace and tags — these become the connection details that any connection linked to it inherits.

Once an environment exists, a connection can link to it by selecting it in the connection's Environment field instead of manual entry. The connection then inherits the environment's host, port, and namespace, so you maintain those details in one place.

Tags are free-text labels you attach to a connection to enable flexible filtering and search. Unlike environments (which represent a single tier), a connection can carry any number of tags. Examples: personal, client-acme, read-only, high-memory.

Tags are displayed inline with the connection name in the list. The Connection Browser provides a tag filter bar at the top of the list: type or select a tag to show only the connections that carry it.

To add or remove tags, open the Edit form for the entry and use the Tags field. Type a new tag name and press Enter (or comma) to add it; click the × on an existing tag chip to remove it. Tags are created on first use — there is no separate tag management screen.

ORE Studio keeps your connections — together with their environments, folders, and tags — in a single local SQLite database file named connections.db. Your UI settings (preferences and window layout) are stored separately, in the operating system's standard settings store. Neither leaves your machine.

• Linux:
  • settings in ~/.config/OreStudio/;
  • database at ~/.local/share/ores.qt/connections.db.
• macOS:
  • settings in ~/Library/Preferences/;
  • database at ~/Library/Application Support/ores.qt/connections.db.
• Windows:
  • settings in registry: HKCU\Software\OreStudio\OreStudio;
  • database at %APPDATA%\ores.qt\connections.db.

If connections.db is missing when ORE Studio starts, it creates a new empty one — so the Connection Browser simply opens with no entries.

Because everything you configure here lives in that one connections.db file, backing it up is a file copy:

1. Quit ORE Studio, so the database is fully written and not locked.

2. Copy connections.db from the location above to a safe place — on Linux, for example:

   cp ~/.local/share/ores.qt/connections.db ~/connections-backup.db
   

To restore, quit ORE Studio and copy the backup back over connections.db. To move your connections to another machine, copy the file to the same location there. The file is self-contained, so a single copy preserves all your connections, environments, folders, and tags.

In the Connection Browser, select the connection you want to use and click Set as active (or double-click it). The selected connection becomes the target for the Connect button in the main toolbar. The status bar at the bottom of the main window shows the name of the active connection.

You do not have to choose in advance, though: clicking Connect opens the login dialog directly, and its Quick Connect selector lets you pick the connection there (see Filtering Quick Connect with labels below).

With an active connection selected, click Connect. ORE Studio attempts to reach the backend. If the backend is reachable, the Login dialog appears.

# Capture: open the login dialog for an account with more than one party, so

Enter your username and password and click Login. Tick Remember me to have ORE Studio recall the username next time. ORE Studio authenticates against the backend's user database. On success the dialog closes and the main window transitions to the connected state: the workspace panels become active, the menu bar is fully enabled, and the status bar shows your username and the connected backend name.

If your account spans more than one party, Log in to default party (ticked by default) skips the party-selection step and logs you straight in to the party configured as your account's default. Untick it if you want to choose the party explicitly on this login instead.

The fields below the credentials describe which backend you are logging in to:

• Label — the saved connection's name (e.g. local1).
• Quick Connect — pick a saved connection to fill Server, Port and Namespace in one step, or leave it on Enter details manually to type them yourself.
• Server, Port, Namespace — the backend address the login targets.

The Label and Quick Connect fields work together. The Label names the environment — it defaults from the connection (or from the --instance-name you launched with); Quick Connect then offers the connections for that label, and picking one fills in Server, Port and Namespace so you do not have to type them.

If you do not yet have an account, the Register link in the footer opens account registration. If authentication fails, an error message is shown below the password field. Check that you are using the correct credentials for this backend; each backend maintains its own user database independently.

With only a handful of connections, Quick Connect is easy to scan. But a real deployment soon accumulates many — several environments, each with its own system, tenant and per-party logins. Left unfiltered (the Label set to All), the selector lists every one:

Each connection carries a label — its environment tag, such as dev, local1 or local2. The Label selector lists those labels; choosing one filters Quick Connect to just the connections that carry it:

With local1 selected, Quick Connect shows only the local1 entries — the environment's own database, its system and tenant logins, and its per-party connections — so you reach the right backend without scrolling past unrelated ones:

You normally run one client per environment: a client built for local1 should connect to local1, not to staging or production. Rather than pick the label by hand each time, set it when you launch the client — the --instance-name command-line option (see Telling windows apart) opens the client with the Label already set, so Quick Connect is pre-filtered to that environment. The compass client start command does this for you, taking the label from ORES_CHECKOUT_LABEL in your .env.

Not every login failure is a wrong password. ORE Studio talks to the backend over a messaging server (NATS), and if it cannot reach that server — or the services behind it — it tells you which is wrong rather than just reporting "login failed".

If the messaging server itself is unreachable, ORE Studio reports that it cannot connect, along with the host and port it tried:

If the messaging server is running but the application services behind it have not started, ORE Studio says so explicitly — the fix is to start the backend services, not to change your connection:

In both cases your saved connection is fine; correct the backend (start the server or its services) and click Connect again.

On a freshly initialised backend the only account that exists is the default administrator account. Your system administrator will have provided the initial credentials. After first login it is strongly recommended to change the password immediately via Settings → Account.

Once a tenant has been provisioned (covered in the next chapter, Initial Setup), you log in with that tenant's administrator account — the username takes the form user@tenant_code. Picking the connection from Quick Connect fills in the server, port and namespace for you:

If your deployment allows it, the Register link in the login dialog footer opens the Create Account form. Fill in a username, email, and password (with confirmation), check the Server and Port point at your backend, and click Create Account. The Log in link returns to the login dialog.

Self-registration is not always available: the backend must be set up to permit new users to register themselves. Where it is disabled, accounts are created for you by an administrator instead (see First login and the default account).

When you run more than one ORE Studio window at once — for example against different backends, or from separate checkouts — you can give each window a distinct identity so you can tell them apart at a glance. This is not a light/dark theme; it is purely a per-window marker.

• --instance-color HEX draws a small coloured circle in the status bar in that colour (a 6-digit RGB hex, e.g. F44336 for red). Give each window a different colour.
• --instance-name NAME (short form -n) labels the window with a name, also shown in the status bar, so you can see which window is which.

ores --instance-name "Local dev" --instance-color 2196F3

--instance-name does more than label the window: it also sets the login dialog's Label field on start-up, pre-filtering Quick Connect down to just that label's connections instead of showing every saved connection across every environment — see Filtering Quick Connect with labels above.

The colour and the name are independent: the colour is only a visual marker, and the name is what identifies the instance. If you launch via compass client start, its --colour red|green|blue|<hex> sets the marker colour and --name sets the instance name; when you omit --name, the name comes from ORES_CHECKOUT_LABEL in your .env — never from the colour.

By default ORE Studio stores its UI settings — preferences and window layout — in the operating system's standard settings store. The exact per-OS locations are listed under Where your connections are stored; your saved connections live separately in connections.db. To use a different directory:

ores --config-dir /path/to/config

This is useful when running multiple isolated instances, or when keeping configuration under version control for team-shared settings.

To bypass the Connection Browser and connect immediately to a named connection:

ores --connection "Local dev"

ORE Studio will start, set the named connection as active, and open the login dialog automatically. The connection name must match exactly (case-sensitive) a saved entry in the Connection Browser.

For troubleshooting, verbosity can be increased:

ores --log-level debug    # verbose output to stdout
ores --log-file /tmp/ores.log  # write log to a file instead

Log output includes connection lifecycle events, authentication attempts, and backend protocol messages. The debug level is intended for issue reporting and development; it produces high-volume output and should not be left enabled during normal use.