1. What HalAxe Does

Most real APIs require authentication before they will return any data. Many tools and AI assistants have no built-in way to handle this. Without HalAxe, you would have to sign in separately, retrieve an access token, and pass it into your tool on every request, often by hand.

HalAxe sits between your tool and the API. You set up an Environment once, telling HalAxe which API to reach and how to log in. HalAxe then gives you a local Proxy URL that behaves like an open, unauthenticated address. Any tool or AI assistant that can make HTTP requests can point at that address, and HalAxe takes care of authentication behind the scenes.

HalAxe also includes a built-in MCP (Model Context Protocol) server. When connected, an AI assistant can call your APIs, explore their schemas, run saved queries, and send email through HalAxe, without ever seeing your credentials.

Important: HalAxe reads data from APIs. It supports GET and QUERY requests only. It cannot send data to an API using POST, PUT, PATCH, or DELETE.

1.1 Supported Authentication Methods

HalAxe supports two types of API authentication:

• OAuth 2.0: HalAxe handles the login flow and manages access tokens on your behalf. See the Flow Types section for the specific OAuth flows supported.
• HTTP Header pass-through: HalAxe adds a fixed set of HTTP headers (such as an API key or a bearer token) to every request. No login flow is needed.

1.2 Pricing

Free

The Free version includes everything you need for day-to-day use:

• Local proxies for as many environments as you like, with automatic token handling.
• All login methods: Authorization Code, PKCE, Client Credentials, ROPC, and HTTP Header.
• Placeholders and extra header/body fields for shaping requests.
• The environment token for locking down a proxy.
• Internal HTTPS for local connections.
• Email sending (SMTP) per environment.
• The AI assistant (MCP server) for querying your APIs from AI tools.
• Exporting your environments to an encrypted backup file.

The Free version is valid for one year. When it expires, reinstall HalAxe to continue using it free.

Premium

Premium unlocks the two features not included in Free:

• Import — restore environments from an encrypted backup file.
• Deployment Targets — ready-made connection profiles such as IFS ERP.

Start with Premium features free for one year, then keep them for life with a one-time purchase. No subscriptions.

2. System Requirements

HalAxe is a small program that runs quietly in the background on your computer. To use it, you need:

• A system tray (notification area). HalAxe lives there while it is running, usually near the clock. If your system hides this area, you may need to show it to find the HalAxe icon.
• A web browser. HalAxe's screen opens in your default browser. Any modern browser works.
• Network access to your APIs and login providers. HalAxe itself does not need an internet connection just to run. It does need to be able to reach whatever Base URL, Auth URL, and Token URL you set up for an environment, whether those addresses are on the internet or only on your local network.
• Free local ports. Each environment you set up uses its own local port number, between 1024 and 32767, on localhost. Make sure the ports you choose are not already used by something else on your computer.
• A folder HalAxe can write to. HalAxe stores its settings in one folder on your computer, choosing the first of the following that it can write to:
  1. Your app-configuration folder:
     %AppData%\halaxe - the internal folder HalAxe writes its data to
     ~/Library/Application Support/halaxe - open via Finder's "Go" > "Go to Folder..."
     ~/.config/halaxe - hidden by default, since folder names starting with a dot are hidden
  2. If that location is not available, a .halaxe folder directly in your "home folder" - the main folder set up for your user account (e.g. C:\Users\<YourName> on Windows/Users/<YourName> on macOS/home/<yourname> on Linux).
  3. If neither of the above is available, a halaxe folder next to the HalAxe program itself - i.e. wherever HalAxe is installed or unzipped.

  Inside this folder, HalAxe keeps:

  • an environment json file, containing your environment settings, stored encrypted
  • settings.json, app preferences such as which ports use HTTPS and whether to stop proxies when you close the tab, plus your HTTPS certificate (stored encrypted)
  • a cert folder, holding the certificate files used for HTTPS (see section 11, "Secure Connections (HTTPS)")

  Do not edit or rename any files in this folder. Tampering will break the application. The Export and Import buttons (section 12, "Backing Up and Restoring Environments") are the supported way to back up or move your environments.

On Windows, having the Microsoft Edge WebView2 Runtime installed lets HalAxe show its own sign-in window for Authorization Code and PKCE logins. Most Windows computers already have it. If it is missing, HalAxe still works fully, sign-in simply opens in your normal browser instead (see "Authorize using browser" in section 6, "Filling in the Login Details"). On Windows, this runtime also keeps a small <HalAxe>.exe.WebView2 folder next to the program. This is created and managed by Windows itself, is unrelated to HalAxe's own settings folder above, and can be safely ignored.

3. Starting HalAxe

A short splash screen may appear for a few seconds when HalAxe starts. This is normal and closes by itself.

Once it has started, HalAxe opens its screen in your default browser automatically, and also shows an icon in your system tray.

• Click Open to open the HalAxe screen in your browser again, for example if you closed the tab earlier.
• Click Exit to stop HalAxe completely. This stops every proxy that is currently running.
• Enable Internal HTTPS is a tick box in this menu. Turn it on if you need any of your proxies to use a secure (https) address instead of a plain (http) one. See section 11, "Secure Connections (HTTPS)", for more on this.

4. Quick Start

1. Open HalAxe from the tray icon.
2. Click + New in the Environments section.
3. Fill in a Name, the Base URL of the real API, and a local Port number for HalAxe to use.
4. Choose a Flow (this is the login method, explained below) and fill in the details it asks for.
5. Click Save. Your new environment appears in the list with its own Proxy URL.
6. In the table, click the proxy address shown next to your environment (it looks like http://localhost:8080/load?halaxe-env=MyEnv) to copy it to your clipboard.
7. In Postman, curl, or any other tool, send a GET request to that address. Add one extra header to the request called halaxe-get, and set its value to the full address of the real API endpoint you want to call. HalAxe will log in for you, fetch that address, and send back the response.

   You can click the halaxe-get tag near the top of the page to copy that header name, so you do not have to type it yourself.

5. Adding or Editing an Environment

Click + New in the Environments section to add one, or click an existing row in the table to edit it.

Flow Types (Login Methods)

• Authorization Code: The standard browser-based login. HalAxe opens a login page, you sign in, and HalAxe receives the result and exchanges it for an access token.
• PKCE: Works the same way as Authorization Code, but does not need a client secret. This is the recommended choice for most setups, especially if your provider does not give you a secret.
• Client Credentials: No human login at all. HalAxe sends a Client ID and Client Secret straight to the provider and gets back an access token. Good for service-to-service connections.
• Resource Owner Password (ROPC): HalAxe sends a username and password directly to the provider to get a token. Only use this with a system you trust completely, since the password is stored by HalAxe.
• HTTP Header: No login process at all. HalAxe simply adds one or more fixed headers (such as a static API key) to every request it forwards.

Email Configuration (Optional)

Each environment can optionally store an SMTP configuration. Once set, an AI assistant connected via HalAxe's MCP server can send emails through that environment's mail account (see section 16, "AI Assistant (MCP Server)", for details on the send_email tool).

Creating the config file

The email configuration is a plain JSON file you create yourself and keep in a safe place. HalAxe does not generate it. Create a file named anything you like (for example email-config.json) with the following content:

{
  "smtp_host": "smtp.example.com",
  "smtp_port": 587,
  "username": "you@example.com",
  "password": "your-smtp-password",
  "from": "you@example.com",
  "tls": "starttls"
}

All six fields are required. HalAxe will reject the file at import time if any field is missing or tls is not one of the three allowed values.

Security note: this file contains your SMTP password in plain text. Keep it on your own computer securely or delete it. Once imported, HalAxe stores the config encrypted inside the environment, so the original file is no longer needed.

Importing the config

1. Open or edit the environment in HalAxe.
2. Click Import Email near the bottom of the dialog.
3. Choose the JSON file you created. If valid, a success message appears and the button gains an asterisk (*) to show there is an unsaved change.
4. Click Save. The config is validated, encrypted, and stored with the environment.

Removing the config

Click Remove Email in the environment dialog, then click Save. The button gains an asterisk (*) while the removal is pending, and the config is deleted once you save.

6. Filling in the Login Details

The fields shown change depending on the Flow you picked.

Authorization Code, PKCE, Client Credentials, and ROPC

• Client ID and Client Secret: the credentials your login provider gave you for this application. If you leave Client Secret blank while editing an existing environment, the saved value is kept as is.
• Well-Known URL: many providers publish a single configuration address ending in .well-known/openid-configuration. Paste it here and click Fetch. HalAxe will read it and fill in the Auth URL and Token URL for you, so you do not have to look them up yourself.
• Auth URL and Token URL: the addresses your provider uses for login and for issuing tokens. You can type these in by hand if you do not have a Well-Known URL.

  Some providers require extra parameters that are not covered by the fields above. You can add any such parameters directly to the Auth URL or Token URL as a normal query string:

  https://myidp.example.com/oauth/token?audience=https://api.example.com
  https://myidp.example.com/authorize?prompt=select_account&login_hint=user@company.com

  HalAxe passes those parameters through to your provider alongside its own. If a parameter value contains a space, use + in its place, as is standard in web addresses:

  https://myidp.example.com/authorize?prompt=select+account

  Any parameter name that HalAxe already sets itself (such as client_id, state, scope, or code_challenge) is reserved. HalAxe will warn you at save time if you try to use one of those.

  If your provider requires a nonce parameter, add nonce=anything to the Auth URL. HalAxe will replace the value with a fresh random token on every login request, so you never have to manage it yourself.

  https://myidp.example.com/authorize?nonce=anything

  You can also add halaxe-header and halaxe-body parameters to the Token URL to inject extra headers or body fields into every token request HalAxe sends to your login provider. See section 8, "Using halaxe-header and halaxe-body", for details and format.

  If your provider requires Client Secret Basic Auth in the token request, see "Client Secret Basic Auth in the Token URL" in section 8.

• Scopes: the access permissions you are requesting, separated by spaces, for example openid profile.
• Redirect URI: the address the login page sends you back to once you have signed in. This must match what is registered with your provider.
• Authorize using browser: when ticked, the login page opens in your normal web browser instead of inside HalAxe. Turn this on if your provider refuses to show the login page inside an app, or if this computer does not have the component HalAxe needs to show its own login window. If that component is missing, this box is ticked automatically and cannot be unticked. The missing component is called "Microsoft Edge WebView2 Runtime". Most Windows computers already have it, but if needed you can download it for free from Microsoft's website by searching for "Microsoft Edge WebView2 Runtime download". Either way, ticking this box lets you keep using HalAxe without installing anything.

Resource Owner Password (ROPC) only

• Username and Password: the login details HalAxe will send to the provider on your behalf. As with Client Secret, leaving Password blank while editing keeps the value already saved.

HTTP Header only

• Headers: one or more Name: Value pairs, separated by semicolons, for example Authorization: Bearer mytoken; X-API-Key: secret. HalAxe adds these headers to every request it forwards, exactly as typed.

Extra Options (all flows)

• Require environment token on each /load request: when turned on, anyone calling your proxy must also include a HalAxe-issued token. This stops other programs on your computer from quietly using your proxy. See section 10, "The Environment Token", for details.
• Token lifetime hours: how long that HalAxe token stays valid. Leave it at 0 to keep it valid until you stop the proxy.
• Check URLs are reachable: when turned on, HalAxe tries to contact the Base URL, Auth URL, and Token URL before saving, and warns you if any of them cannot be reached.

7. Using Your Proxy

Once an environment is saved, it starts running and shows as Running in the table, with its proxy address shown next to it, for example:

http://localhost:<port>/load?halaxe-env=<name>

Send a GET request to that address, with an extra header called halaxe-get set to the full address of the real API endpoint you want to call. HalAxe fetches that address, adds the correct login details (an access token, custom headers, or whatever the Flow needs), and gives you back the response exactly as the real API sent it. Logging in again and refreshing tokens happens automatically, behind the scenes.

If your API supports the HTTP QUERY method (a newer protocol that works like GET but allows a request body, used by some OData and REST services), use halaxe-query in place of halaxe-get. HalAxe sends the request using the QUERY method exactly as the protocol defines. You can combine halaxe-query with halaxe-body to include a request body. You cannot include both halaxe-get and halaxe-query in the same request.

If your environment uses Authorization Code or PKCE, the very first request (and any later request after your login expires) will pause while HalAxe shows you a login window, either its own pop-up window or your normal web browser, depending on the Authorize using browser setting. Sign in there as you normally would. HalAxe then finishes the request and keeps the access token it received, securely encrypted, for a while, so most later requests will not need a new sign-in.

Most headers you include on your proxy request are forwarded to the upstream API unchanged. Connection-level headers such as Host, Connection, and Transfer-Encoding are stripped automatically, and any halaxe-* headers are consumed by HalAxe and not forwarded. Response headers from the upstream are forwarded back to your client in the same way. All non-connection-level headers (such as Content-Type, ETag, Cache-Control, and any custom X-* headers) pass through unchanged.

In OAuth2 flows (Authorization Code, PKCE, Client Credentials, and ROPC), HalAxe automatically adds an Authorization: Bearer <token> header to every upstream request. If your request already includes an Authorization header, HalAxe passes yours through and skips the automatic injection. For example, if one particular endpoint needs a service account token instead of the user token, send:

Authorization: Bearer <service-account-token>

and HalAxe will use that for this call only. Header values in halaxe-header also support {placeholder} substitution to pull values from the token response or your environment config. See section 9 for details.

In the HTTP Header flow there are no OAuth tokens. Instead, the headers you saved in the environment's Headers field are sent automatically with every upstream request. If you set the same header name directly on your request, yours takes priority. For example, if the environment has Authorization: Bearer api-key saved and you send a different Authorization header on a specific call, the upstream receives yours.

If your tool cannot set custom HTTP headers or include a request body, see section 8, "Using halaxe-header and halaxe-body", for how to pass that information through the URL instead.

8. Using halaxe-header and halaxe-body

Some tools have no way to set custom HTTP headers or include a request body. halaxe-header and halaxe-body are designed for exactly this situation. They let you pass headers and body content through the URL or an HTTP header instead.

If your tool already supports setting custom HTTP headers and request bodies natively, you do not need these parameters. Set them directly and HalAxe forwards them to the upstream API.

halaxe-header

Injects extra headers into the upstream request. Accepted as a URL query parameter or a request body field.

Format: Name: Value; Name2: Value2 (semicolon-separated)

If you send halaxe-header both ways, the request body field takes priority. If you also set the same header name directly on your request, the direct header always wins, regardless of what halaxe-header says for that name.

In the Token URL: Adding halaxe-header=Name: Value to the Token URL in your environment settings injects that header into every token request HalAxe sends to your login provider. Useful when your provider requires a custom header alongside the standard token exchange.

To inject extra headers only during token refresh, use halaxe-refresh-url-header=Name: Value in the Token URL instead. This works the same way as halaxe-header but applies only to refresh requests, not the initial token fetch.

Client Secret Basic Auth in the Token URL

Some providers require your Client ID and Client Secret to be sent as a Client Secret Basic Auth Authorization header in the token request, rather than in the request body. HalAxe provides two built-in placeholders for this.

{halaxe-client_secret_basic} expands to a Base64-encoded Basic value built from your Client ID and Client Secret. Use it with halaxe-header in the Token URL to add the Authorization header while still sending client_id and client_secret in the request body as usual:

https://myidp.example.com/token?halaxe-header=Authorization: {halaxe-client_secret_basic}

{halaxe-client_secret_basic_only} works the same way but also removes client_id and client_secret from the request body. Use this for providers that want credentials in the header only:

https://myidp.example.com/token?halaxe-header=Authorization: {halaxe-client_secret_basic_only}

halaxe-body

Adds key-value pairs to the upstream request body. Accepted as a URL query parameter or an HTTP header. The HTTP header option is useful for tools that can set headers but not a request body.

Format: Name: Value; Name2: Value2 (semicolon-separated)

If you use more than one of these, the direct request body takes priority, then the HTTP header, then the URL param. Any halaxe-* keys found directly in the request body are removed and not sent to the upstream API.

In the Token URL: Adding halaxe-body=Name: Value to the Token URL in your environment settings adds extra parameters to the token request body. Useful when your provider requires non-standard body fields during the token exchange.

To add extra body fields only during token refresh, use halaxe-refresh-url-body=Name: Value in the Token URL instead. This works the same way as halaxe-body but applies only to refresh requests, not the initial token fetch.

9. Using Placeholders in URLs and Parameters

You can embed {key} placeholders anywhere in a halaxe-header, halaxe-body, Token URL, or upstream API address value. HalAxe replaces each placeholder at request time with a matching value from one of the sources described below.

Where placeholders work

• Direct proxy request: in halaxe-header and halaxe-body values, and in the upstream API address sent via halaxe-get or halaxe-query. All four substitution sources are available here.
• Token URL: in halaxe-header and halaxe-body values added to the Token URL in your environment settings. Because the token response does not exist yet at this point, only sources 3 and 4 are available: callback parameters (Auth Code and PKCE flows only) and environment config.
• Refresh URL: in halaxe-refresh-url, halaxe-refresh-url-header, and halaxe-refresh-url-body values. The previous token response is available here, so all four sources apply.

Substitution sources

All applicable sources for the context are checked for each key at the same time:

1. Token response body: fields returned by your login provider in the token response body, for example {access_token} or {id_token}.
2. Token response headers: HTTP headers returned by the token endpoint, for example {X-Custom-Tenant}.
3. OAuth2 callback parameters: query parameters sent back in the login redirect URL, such as {session_state} or any custom parameter your provider includes alongside the authorization code.
4. Environment config: values derived from the settings you filled in for this environment. These keys are always available regardless of which flow you use, and they are prefixed with halaxe- so they never clash with real token response fields:

Rules

• Each key must appear in exactly one source. If a key is found in more than one source, HalAxe returns SUBST_PARAM_AMBIGUOUS. If it is not found in any source, HalAxe returns SUBST_PARAM_NOT_FOUND.
• To write a literal { or } in a value, double it: {{ produces {, and }} produces }.

Examples

Using a token response field in the upstream URL:

halaxe-get: https://api.example.com/data?tenant={tenant_id}

If your token response body includes a tenant_id field, HalAxe fills it in before calling the API.

Using the Client ID in a token request header:

https://myidp.example.com/token?halaxe-header=X-Client-Id: {halaxe-client_id}

10. The Environment Token

If you turned on Require environment token on each /load request, every call to /load must include an environment token that HalAxe itself generates (this is separate from, and in addition to, the login token used for the real API).

• Click the Token button next to an environment to open the Environment Token window.
• Click Copy to copy the environment token to your clipboard.
• Add it to the end of your proxy address as &halaxe-token=<environment-token>, for example:

  http://localhost:<port>/load?halaxe-env=<name>&halaxe-token=<environment-token>

• If the environment token has expired, opening this window again gives you a fresh one.
• The Token lifetime hours setting (section 6, "Filling in the Login Details") controls how long each environment token stays valid. A value of 0 means it stays valid until the proxy is stopped.

11. Secure Connections (HTTPS)

By default, HalAxe's proxies use plain http:// on your local computer. Some tools insist on a secure https:// address (for example, if they refuse to use an http:// redirect address).

To turn this on:

1. Open the tray icon menu and tick Enable Internal HTTPS. This creates a security certificate for your computer the first time it is needed.
2. On the HalAxe screen, find the HTTPS Ports section. Each port you are using appears here with its own switch. Turn the switch on for any port you want to serve over https://.
3. If your browser or tool warns you that the certificate is not trusted, use Open Cert Folder to find cert.pem and add it to your system's list of trusted certificates. The folder contains cert.pem (the certificate); it regenerates automatically if you delete or move it.

   Open Command Prompt, change to that folder, and run:

   certutil -user -addstore -f "ROOT" cert.pem

   This adds it to your own (current user) trusted certificates, so no administrator rights are needed.

   Open Terminal, change to that folder, and run:

   security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db cert.pem

   This adds it to your own login keychain, so no administrator password is needed.

   Trusting a certificate for one user only varies between distributions and tools. The simplest reliable option is usually a system-wide install, for example on Ubuntu/Debian (this does need admin access):

   sudo cp cert.pem /usr/local/share/ca-certificates/halaxe.crt
   sudo update-ca-certificates

   After this, restart your browser or tool so it picks up the change.

Switching a port between http and https restarts that proxy briefly. Any requests in progress may need to be sent again.

12. Backing Up and Restoring Environments (Export / Import)

You can save your environments to a file and load them again later, or move them to another computer.

Export

1. Click Export near the top of the environment list.
2. Tick the environments you want to include.
3. Enter a 6-digit PIN (and confirm it). This PIN locks the file so only someone who knows it can open it.
4. Click Export to download the file. It is named halaxe-export-<date>.json.

Keep the PIN safe. If you lose it, the file cannot be opened or recovered.

Import Premium

1. Click Import.
2. Choose the exported file and enter the PIN that was used to create it.
3. Click Import.

If an environment in the file has the same name as one you already have, HalAxe will ask whether to:

• Skip existing: keep your current environment and ignore the one from the file, or
• Overwrite: replace your current environment with the one from the file.

Either way, the environments you choose to bring in appear in the table straight away.

13. Other Settings

• Toggle theme (the icon at the top right of the screen): switches the screen between light and dark appearance. Your choice is remembered the next time you open HalAxe.
• Stop all servers when active tab is closed: when this is ticked, closing the HalAxe browser tab stops every running proxy after a short delay. If you reopen the tab quickly, the proxies keep running. When this is unticked, closing the tab does not stop anything, your proxies keep running in the background until you exit HalAxe from the tray.

14. Screens You Might See

These full-screen messages can appear in the browser tab from time to time. They are normal and tell you what HalAxe is doing.

• Reconnecting...: shown briefly while a proxy switches between http and https. The page reconnects on its own once it is ready.
• HalAxe is Shutting Down...: shown after you click Exit in the tray menu, while HalAxe closes everything down.
• HalAxe is offline: HalAxe has fully stopped. You can close this tab.
• This tab is no longer active: you opened HalAxe in a new tab, so this older tab has been retired. Switch to the newer tab and close this one.
• Access Restricted: this page was opened directly, without going through the tray icon. Note that refreshing (reloading) the HalAxe page itself also shows this screen, since each link from the tray can only be used once. If this happens, just click Open in the tray icon menu again to get back into HalAxe.

15. "localhost" and "127.0.0.1" Addresses

Every HalAxe proxy address uses your own computer's address, which can be written in two different ways: localhost or 127.0.0.1. These mean exactly the same thing to your computer, but most login providers treat them as two different addresses when checking a Redirect URI for Authorization Code or PKCE logins.

Each time HalAxe starts, it tries to use localhost first, and uses that for every proxy address. If localhost does not work on this computer, which is rare and usually points to a network setup issue, HalAxe falls back to using 127.0.0.1 instead for that run.

If one of your saved environments has a Redirect URI written with the address HalAxe is not using this time, sign-in for that environment will fail until it is corrected. HalAxe helps with this automatically:

• When HalAxe starts: if any saved environments are affected, a message appears at the top of the screen listing them, along with the address they currently use and the address HalAxe is using now. Click Fix All to update every listed environment's Redirect URI to the correct address in one go. This message stays on screen until you click Fix All.
• When importing environments: if a file you are importing contains environments with this same issue, HalAxe pauses the import and asks whether to:
  • Update addresses: change the affected environments' Redirect URIs to match the address this run of HalAxe is using, and continue importing them as normal, or
  • Skip these: leave those environments out of the import. Any other environments in the file are still imported normally.

After fixing the address either way, remember to also check that the Redirect URI registered with your login provider matches what HalAxe is now using, if your provider requires it to be registered in advance.

16. AI Assistant (MCP Server)

HalAxe includes a built-in MCP (Model Context Protocol) server that allows desktop AI tools to call your APIs directly through HalAxe's authenticated proxy. The AI can explore API schemas, make authenticated calls, save and rerun queries, and send email, all without ever seeing your credentials.

Starting the MCP server

1. Click the 🤖 button in the top-right area of the HalAxe screen.
2. Set a Port number (default 9877). This is the local port the MCP server listens on; it is separate from your environment proxy ports.
3. Optionally tick:
   • Auto-start when HalAxe opens: the MCP server starts automatically every time HalAxe launches.
   • Use HTTPS: serves the MCP server over https://. Requires HTTPS to be enabled first (see section 11, "Secure Connections (HTTPS)").
4. Click Start. The status changes to Running and a configuration snippet appears.

Connecting your AI tool

Once the server is running, a configuration snippet appears in the dialog:

"mcpServers": {
  "HalAxe": {
    "command": "halaxe.exe",
    "args": [
      "mcp-proxy",
      "9877"
    ]
  }
}

Click Copy to copy it to your clipboard, then paste it into your AI tool's MCP server configuration file. If necessary, restart your AI tool after adding the config so it picks up the new server.

The command is the short app name (halaxe.exe) rather than a full install path. Windows resolves this name to the current version of HalAxe through its app execution alias, so the configuration keeps working after HalAxe updates. If your AI tool reports that it cannot start HalAxe, the dialog shows a full fallback path you can paste as the command instead, and a warning if the alias has been turned off, in which case re-enable it under Settings > Apps > Advanced app settings > App execution aliases.

What the AI can do

Once connected, the AI assistant has access to the following tools:

Saved queries

Queries saved via save_query are stored on disk inside HalAxe's settings folder (see section 2, "System Requirements"). Environment tokens are never saved. If a query needs one, you must provide it at run time (see section 10, "The Environment Token"). Saved queries are shared across all AI tools connected to the same HalAxe instance.

17. Troubleshooting

Environment settings

Ports and HTTPS

Export and Import

Using your proxy

Proxy errors appear in two places: as a halaxe-error JSON response to the caller (see section 18 for the response format), and in the environment log panel inside HalAxe. API_BAD_RESPONSE is the exception: it appears only in the environment log, because HalAxe passes the real API error response through to you unchanged.

MCP server

Email configuration

These messages appear when your AI assistant calls the send_email tool (see "Email Configuration" in section 5 and section 16).

License

Browser

18. Errors From Your Proxy Requests

When something goes wrong with a request to your proxy address before HalAxe can reach the upstream API, HalAxe sends back a short JSON response instead of the data you asked for:

{ "halaxe-error": { "code": "...", "message": "..." } }

For what each code means and what to check, see section 17, "Troubleshooting", under "Using your proxy".

If the response does not look like {"halaxe-error":{...}} at all and instead looks like a normal error page or a different JSON shape, HalAxe successfully reached the upstream API and is passing its response back to you unchanged. The problem is with the request itself or with the upstream API, not with HalAxe. Check the environment log panel in HalAxe for the API_BAD_RESPONSE entry, which shows the status code and a snippet of the API's reply.

19. Internal Error Codes (For IT / Support)

The messages below are referenced from section 17, "Troubleshooting". Most appear as a small banner near the button you clicked, but a few show in different places depending on the situation. The notes in each row say where to look. None of them are caused by anything you typed into an environment's settings, and there is no setting on the HalAxe screen that fixes them. They point to a problem with HalAxe's own internal state, or with this computer's storage, permissions, or network setup. Restarting HalAxe is the first thing to try for all of them.

Setting that fails silently

Startup messages

These messages appear before or during HalAxe startup, before the main screen is ready. They are shown in a separate window as full messages, never as raw codes.

20. Application Logs

HalAxe writes a log entry every time an internal event occurs, such as a warning, an error, or a significant operation. These logs are intended for diagnosing issues and sharing with IT or support when something goes wrong.

Log location

Logs are stored in a logs folder inside HalAxe's storage folder (see section 2, "System Requirements", for the location of that folder). Each day, HalAxe creates a new log file named:

halaxe-YYYY-MM-DD.log

The logs folder and today's file are created the first time HalAxe writes a log entry that day. If nothing noteworthy has happened yet, the file will not exist.

Retention - no automatic cleanup

HalAxe never deletes log files automatically. There is no scheduled cleanup job and no maximum number of files. Log files accumulate indefinitely. If disk space becomes a concern, you can open the logs folder and remove old files manually.

Opening the logs folder

Click the 📋 button in the top-right area of the HalAxe screen (next to the ❔ help button) to open the logs folder in your file manager. If the folder does not yet exist, HalAxe creates it before opening it.

Log viewer errors