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.

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.

3-2. Set the subscription transport and destination

This is the connection method (transport) and destination GalleonQL uses when you subscribe. Choose WebSocket or SSE with the radio buttons; the default is WebSocket. The URL field is optional, so you can usually leave it empty. You can change the transport even on the Free plan (subscribing itself requires the Pro plan — see Sending queries).

• When the URL is empty, the request URL is reused with only its scheme replaced according to the selected transport.

  • With WebSocket selected: https://api.example.com/graphql becomes wss://api.example.com/graphql (http:// becomes ws://).
  • With SSE selected: the scheme is not replaced (it stays https:// / http://, since SSE connects over plain HTTP).

  The preview below the field shows "Resolved: … (derived from the request URL)".

• Fill it in only when the HTTP and subscription paths differ (for example /graphql and, depending on the transport, /graphql/ws for WebSocket or /graphql/stream for SSE). The value you enter is used as-is; its scheme is not replaced.

• You can enter a direct URL or an environment variable reference (e.g. {{wsUrl}} / {{sseUrl}}).

• If the destination cannot be determined, or the scheme you entered does not match the selected transport (for example writing ws:// while SSE is selected), the preview shows a warning explaining why. In that case, review this field or change the selected transport.

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).
• Besides manual edits, request hooks (post-send extract and assert; only extract overwrites variables) may overwrite variables without confirmation. If a value changes unexpectedly, check the Hooks tab results (Request hooks (extract and assert)).

Variable suggestions ({{ autocomplete)

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

Badge at the start of each candidate:

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.

• 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).

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. Setting HTTP timeouts

In the "HTTP timeouts" section (source badge E), set the connection timeout and total timeout for this environment. The project editor drawer has the same section, which sets the project-wide default.

• There are two fields: Connect timeout (default 10s, can be set from 1 to 60 seconds) and Total timeout (default 60s, can be set from 1 to 600 seconds).
• Leaving a field empty inherits the project's setting (or the app default if the project has none set either). While empty, the field shows the currently effective value, its source, and the allowed range, such as "Inherited 60 sec (project) / 1–600 sec".
• Full-width digits are normalized to half-width and saved (typing １０ saves as 10 — this is not an error). Any non-digit character (decimal points, symbols, letters, etc.) is stripped out on the spot, with a "Digits only" notice — and whatever digits remain are saved as the number of seconds. For example, typing 1.5 strips the . and saves 15 seconds; 10.5 becomes 105 seconds. Entering what looks like a decimal does not get rejected or truncated — it is saved as a different whole number, so check the value that ends up in the field. The only error you can actually trigger from the UI is an out-of-range whole number (e.g. entering 100 for the connect timeout, which exceeds the 60s maximum); it is not clamped automatically and the previous valid value is kept.
• Zero and "unlimited" cannot be set (this prevents the app from waiting indefinitely for a response that never arrives).
• The values set here apply to every query send and schema import that uses this environment (unless overridden per request on the Headers tab).

8. 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.

9. 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

HTTP timeout configuration example (extending only the total timeout for a slow staging environment):

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.

1. App built-in (source A. e.g. User-Agent)
2. Project-wide headers (P)
3. Environment request headers (E)
4. Authentication (the Authorization built from method + secrets. Au)
5. 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).

HTTP timeout cascade (App default → Project → Environment → Query)

HTTP timeouts (connection / total) are resolved by the same rule as headers: "layer them from the top, and the lowest layer with a value wins."

1. App default (10s connect / 60s total)
2. Project (the "HTTP timeouts" section in the project editor drawer)
3. Environment (the "Setting HTTP timeouts" section on this page)
4. Query (the "HTTP timeouts (this query)" section on the Headers tab of the request pane. See Sending queries and responses)

The difference from the header cascade is that timeouts have no auth stage, and the connection timeout and the total timeout cascade completely independently. For example, extending only the total timeout in an environment leaves the connection timeout unchanged (it stays at the project's setting, or the 10s default).

When a field is empty, the effective value, source, and allowed range up to the next layer above are shown as "Inherited N seconds (source) / min–max sec", so you can see what value is actually in effect without entering anything.

Schema import (introspection) has no query layer, so it is resolved through only three layers: app default → project → environment (see Importing a schema).

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 / OAuth2 Client Credentials (all complete with the Authorization header). API Key, OAuth2 Authorization Code, 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

Related documents

• Use in schema import: Importing a schema
• The request's Auth tab and Authorization on send: Sending queries and responses
• Post-send extract and assert (request hooks): Request hooks (extract and assert)
• Assembling queries: Query Builder
• Reordering environments: Reordering and moving
• Terminology: Key terms
• Back to the index: User manual contents