Registering and switching environments

This page explains how to register and switch between "environments (connection profiles)" that bundle the settings for each destination, and how to configure environment variables, authentication, and headers.

What an environment is (a connection profile) (overview)

An environment is a switchable connection profile, equivalent to Postman's "Environment". It is not a parent (intermediate node) of collections or queries; it exists independently of queries (an orthogonal model). Queries are held under collections without depending on the environment, and sending and schema import are always assembled as "the target operation × the currently selected environment". For terminology, see Key terms.

Prerequisites

The app is running (Getting started (install and launch)).
You understand the difference between an "environment variable" and a "GraphQL variable" (see the table below and Key terms). Confusing them leads to mistakes when setting headers and URLs.

The difference between environment variables and GraphQL variables (do not confuse them)

GalleonQL distinguishes two kinds of "variable". This page deals with environment variables.

	Environment variable (covered on this page)	GraphQL variable
Notation	Double braces, like `{{baseUrl}}` `{{token}}`	Declared inside the query, like `$id` `$input`
Owner	The environment holds them as key-value pairs	The query holds their default values
Purpose	Connection settings that change per environment, such as the destination URL	Arguments of the query
Insertion target	Endpoint URL and header values	Arguments in the query body

Named GraphQL variables (such as $id) become available when you switch the query builder's input mode to "Variables" (see Query Builder).

Put authentication secrets (Bearer tokens, Basic passwords) in the "Auth" section described below, not in environment variables.

Steps

1. Open the environment editor

The top bar has the environment selector (dropdown), the resolved URL of the selected environment, and an "Edit" button. Clicking "Edit" opens the environment editor (a modal), and the environment that was selected at that moment becomes the edit target.

2. Add an environment

Enter a name in the "New environment name" field of the "Environments" section, and click "Add environment".

If the name is empty (empty after trimming surrounding whitespace), nothing is added.
The added environment is created with the URL, environment variables, and environment headers all empty, and authentication set to "None (none)".
The added environment is automatically selected so you can edit it right away.

3. Set the request URL

In the "Request URL" section, enter either a direct URL (e.g. https://api.example.com/graphql) or an environment variable reference (e.g. {{baseUrl}}).

A "Resolved: …" preview is shown below the input field. If any unresolved {{...}} remain, a warning is shown.
The endpoint for sending and schema import uses the value of this request URL resolved with environment variables.

4. Add, edit, and delete environment variables

In the "Environment variables" section, enter a "Variable name" and a "Value", and click "Add environment variable".

Editing the value field of an already-added variable directly in the list updates it immediately. Delete each row with "Delete".
You can reference them as {{key}} inside request URL and header values. They are resolved even when there is whitespace between the braces and the variable name, like {{ token }}.
Indirect references are resolved only one level deep (see "Limitations" below).
Do not put authentication Bearer tokens or Basic passwords here (use the next "Auth" section).

Variable suggestions (`{{` autocomplete)

In the value fields for URL, headers, and variables, typing one or more characters after {{ opens a list of candidates.

Action	Result
Enter / Tab / click	Insert `{{variableName}}`
↑ / ↓	Move the highlight through candidates
Escape	Close the suggestions

Badge at the start of each candidate:

Badge	Meaning
P	Project-wide variable
E	Environment variable
A	App built-in (e.g. `AppUserAgent`)

A P and an E with the same name appear on separate rows. On resolution, the environment side overrides the project. Suggestions do not appear in authentication secret fields (because auth values are not template-expanded).

5. Set authentication (default method and secrets)

In the "Auth" section (with the source badge Au to the left of the heading), set this environment's default authentication method and secrets.

Default auth method	Meaning	Secret fields shown
None (none)	Do not add an auth header	None
Bearer	Build `Authorization: Bearer <token>`	Bearer token
Basic	Build `Authorization: Basic base64(username:password)`	Basic username / Basic password

When the request's Auth tab is "Inherit environment default", Authorization is auto-injected from the method and secrets set here (source Au). Secrets are not exported/imported.
Auth values do not expand {{...}} (by design, so secrets do not go through templates). Even if you write {{token}} in the token field, the literal string is used as is.
Bearer with an empty token does not send the Authorization header at all. Basic with an empty password does send the header (encoded as an empty password; warning only).

Situation	Warning text
Bearer with an empty token	`Bearer token is empty. Enter a token in Auth or the environment auth settings.`
Basic with an empty password	`Basic password is empty. Confirm this is intentional.`

For how to override just the method on the request side, see the "Auth tab" in Sending queries and responses.

6. Add, edit, and delete environment request headers

In the "Environment request headers" section (source badge E), set the HTTP headers specific to this environment.

Enter "Header" and "Value", and click "Add header".
You can insert environment variables into the value, like {{envVar}} (with {{ suggestions).
Editing each field of an already-added row directly updates it immediately. Delete with "Delete".
Hand-writing Authorization is discouraged (use the "Auth" section). Input itself is allowed for compatibility, but an Authorization written in an environment header is overridden by the later auth stage (Au) or request-specific headers (R) (see "Header cascade" below).

7. Rename an environment / delete an environment

Editing the "Environment name" field immediately changes that environment's name.
Delete an environment with "Delete" on each row of the environment list. You can delete them all down to 0 (though in that case schema import cannot be run).
If you delete the currently selected environment, the first of the remaining environments is automatically selected.

8. Switch environments

When you choose an environment to switch to in the top bar's environment selector, the resolved URL, the final-header preview on the left pane's Headers tab, and the auth Authorization switch immediately. When there are 0 environments, the selector is disabled and shows "(No environments)".

Configuration examples

Purpose	Environment name	Request URL	Environment variables	Authentication	Environment request headers
Local development (initial sample)	`Default`	`{{baseUrl}}`	`baseUrl` = `http://localhost:4000/graphql`	Default method Bearer, token `dev-local`	`Content-Type` = `application/json`
Staging	`Staging`	`https://staging.example.com/graphql`	Optional	Default method Bearer, issued token	Optional
Basic auth API	`BasicApi`	`https://api.example.com/graphql`	Optional	Default method Basic, username / password	Optional
Public API with no auth	`Public`	`https://countries.trevorblades.com/`	Optional	None (none)	Optional

Header cascade (Project → Environment → Auth → Request)

The headers that get sent are merged in the following order, and for the same header name lower overrides upper.

App built-in (source A. e.g. User-Agent)
Project-wide headers (P)
Environment request headers (E)
Authentication (the Authorization built from method + secrets. Au)
Request-specific headers (R)

Priority: Request > Auth > Environment > Project > App.
Header name matching is case-insensitive (content-type and Content-Type are folded into one as the same header, and the final display name is that of the winning side).
The left pane's Headers tab shows a "Final headers to send" preview, displaying the key, the resolved value, and the source badge. This preview is the same resolution result as the actual send (Sending queries and responses).

Source badge	Meaning
A	App settings
P	Project settings
E	Environment settings
Au	Authentication
R	Request settings

Persistence and restore

Environments (name, environment variables, environment headers, auth method and secrets) and the last selected environment are auto-saved to the device on every add / edit / delete / switch. No "Save" action is needed. When you restart the app, the registered environment list and the last selected environment are restored as they were. This restore issues no HTTP at all.

On the first launch (when no environment is saved at all), one sample environment "Default" (the first row of the configuration examples above, including the Bearer token dev-local) is created automatically.
When you switch environments and the resolved URL changes, that URL's schema cache is loaded automatically, and the displayed schema and Query Builder switch to that URL's (no HTTP is issued). If it is a URL you have not imported yet, it changes to a "Not loaded yet" notice. To fetch the schema of a new endpoint, run "Load schema" (or "⟳ Reload") again after switching (Importing a schema).

🚨 Auth tokens and the like are stored unencrypted

Authentication secrets (Bearer tokens, Basic passwords) and the values of environment variables and environment headers are stored in plaintext on the device, unencrypted. The app data lives in the OS's user area and cannot be read by other OS users, but the fact that plaintext remains on disk does not change. This is an intentional decision; similar local tools such as Postman and Insomnia also store in plaintext. Keep this in mind when entering tokens and passwords.

Current limitations

The auth methods are None (none) / Bearer / Basic only (all complete with the Authorization header). API Key, OAuth2, and custom-header authentication are not supported.
Auth values are not resolved with environment variables ({{...}}).
Indirect references of environment variables are resolved only one level deep. For example, even if the value of apiHost is another variable reference {{host}}, it does not automatically chase down to host (an intentional constraint to prevent infinite loops). In this case {{host}} remains after substitution and is warned about as unresolved. If you need multiple levels, expand the referenced value directly and register it.
Hand-writing Authorization is discouraged (use the "Auth" section).

When things go wrong

Symptom	Likely cause	What to do
The selector is disabled / "(No environments)"	There are 0 environments	Add one with "Add environment"
`{{baseUrl}}` appears literally in the URL with "Unresolved variables: baseUrl"	The referenced environment variable is undefined	Add the variable, or rewrite it as a direct URL
The final header shows "Unresolved variables: ()"	The header value's variable is undefined, or a two-or-more-level indirect reference	Add the variable, or keep it to one level
"Bearer token is empty. …" appears	The method is Bearer but no token is entered	Enter a token in the "Auth" section
`Authorization` does not appear in the final headers	The method is "None", or Bearer with an empty token	Check the "Auth" section and the request's Auth tab
The schema does not change even after switching environments	The resolved URL is the same before and after the switch	By design. Switch to an environment that resolves to a different URL
After switching, the schema disappeared and shows "Not loaded yet"	The switched-to URL has not been imported yet	By design (it does not auto-fetch). Run "Load schema"
After restart only the sample "Default" remains	Corrupted saved data, or a fallback due to a DB error	Check the warning shown just below the top bar. Recreate the environments if needed