Deep Links
Deep links let you open Ironspire directly to a specific project, agent, marketplace item or view from your browser, documentation, CI pipelines or other applications. Click a link and Ironspire opens to exactly the right place.
Protocol
Ironspire registers the ironspire:// custom protocol during installation. Any URL starting with ironspire:// is handled by the Ironspire desktop app. If the app is not running, the operating system launches it first and then processes the link.
The general format is:
ironspire://<route>/<parameter>
All URLs are limited to 2,048 bytes. Parameters are URL-encoded using standard percent-encoding.
Routes
Ironspire supports six deep link routes:
| Route | Format | Purpose |
|---|---|---|
| auth-callback | ironspire://auth-callback?code=...&state=... | OAuth callback from browser-based login |
| checkout-success | ironspire://checkout-success?session=... | Return from Paddle checkout after purchase |
| project | ironspire://project/{id} | Open a specific project by ID |
| agent | ironspire://agent/{id} | Focus a specific agent by ID |
| install | ironspire://install/{id} | Install a marketplace package by ID |
| view | ironspire://view/{name} | Navigate to a named view |
auth-callback
ironspire://auth-callback?code=abc123&state=xyz789
Handles the OAuth return flow when you sign in via your browser. After authenticating with GitHub or Google on ironspire.dev, the browser redirects to this deep link, which passes the authorisation code back to the desktop app. You do not need to construct these URLs manually; the sign-in flow generates them automatically.
checkout-success
ironspire://checkout-success?session=cs_live_abc123
Completes the Paddle checkout flow. After purchasing a subscription on ironspire.dev, the browser redirects here so Ironspire can activate your licence immediately. Like auth-callback, these URLs are generated automatically during checkout.
project
ironspire://project/proj_8f3a2b
Opens Ironspire and navigates to the specified project. If the project does not exist locally, Ironspire shows an error notification. Use this in your CI/CD pipelines to link directly from build notifications to the relevant project.
agent
ironspire://agent/agent_c91d4e
Opens Ironspire and focuses the specified agent's chat panel. The sidebar scrolls to the agent, its chat history loads and the input field receives focus. If the agent belongs to a different project than the one currently open, Ironspire switches projects first. Useful for linking from monitoring dashboards or alert systems directly to the agent that needs attention.
install
ironspire://install/pkg_marketplace_7b2f
Opens the marketplace install dialog for the specified package. The user sees the package details, permission manifest and trust level before confirming installation. Share these links in documentation or team channels to help colleagues install the same tools.
view
ironspire://view/analytics
ironspire://view/blueprint
ironspire://view/settings
Navigates to a named view within Ironspire. Supported view names include analytics, blueprint, settings, marketplace and memory. Unknown view names are ignored with a notification.
Combine deep links with your team's wiki or onboarding documents. A new team member can click a sequence of install links to set up the same marketplace packages the rest of the team uses.
Cold-start queuing
When a deep link arrives while Ironspire is not running, the operating system launches the app and passes the URL as a startup argument. Ironspire queues incoming links during its initialisation phase and processes them once the app window is ready. This ensures no link is lost, even if the app takes a few seconds to start.
If multiple links arrive during cold start (for example, clicking several links in quick succession), they are processed in order once the app is ready. The queue holds up to 10 links; additional links beyond that limit are discarded with a log entry.
Cold-start queuing also handles the case where you click a deep link, the OS launches Ironspire, and the Electron window has not finished initialising yet. The link is held in memory until the renderer is ready to act on it, typically within 2-3 seconds of launch.
Platform registration
Ironspire registers the ironspire:// protocol automatically during installation. The mechanism differs by platform:
| Platform | Registration method |
|---|---|
| Windows | Registry entry under HKCU\Software\Classes\ironspire mapping the protocol to the Ironspire executable |
| macOS | CFBundleURLTypes entry in Info.plist declaring ironspire as a handled URL scheme |
| Linux | .desktop file with MimeType=x-scheme-handler/ironspire registered via xdg-mime |
On all platforms, registration happens at install time. You do not need to configure anything manually. If you move the Ironspire executable, reinstall to update the protocol registration.
On Windows, the protocol is registered per-user (HKCU), not system-wide. Each user who installs Ironspire gets their own protocol handler.
Constructing deep links
If you are building integrations that generate deep links, follow these rules:
- Always use the
ironspire://scheme (lowercase) - URL-encode all parameter values
- Keep total URL length under 2,048 bytes
- Use the exact route names listed above; unknown routes are silently ignored
- For
projectandagentroutes, use the full ID including the prefix (e.g.proj_,agent_)
Example in a CI notification template:
View project: ironspire://project/proj_8f3a2b
Check agent: ironspire://agent/agent_c91d4e
Security considerations
Deep links cannot bypass authentication or perform destructive actions. The auth-callback and checkout-success routes require valid tokens that are verified server-side before any state changes. The install route always shows the full package details and permission manifest; it never installs silently.
If an attacker crafts a malicious deep link (for example, ironspire://install/pkg_malicious), the user still sees the standard install dialog with the package's risk score, permissions and trust level. No package is installed without explicit confirmation.
The 2,048-byte URL limit prevents excessively long payloads. Parameters that exceed this limit are truncated, and Ironspire shows an error notification rather than processing a partial URL.
Using deep links in automation
Deep links work well in CI/CD pipelines, Slack bots, email notifications and internal tooling. Common integration patterns include:
- Build notifications: link directly to the project that triggered a build, so developers can check agent activity in one click
- Alert escalation: when a monitoring system detects an agent crash, include a deep link to that agent's chat panel in the alert message
- Onboarding scripts: generate a list of
installlinks for all the marketplace packages your team uses, so new hires can set up their environment quickly - Documentation: embed
viewlinks in your internal wiki to link readers directly to the relevant Ironspire panel
Troubleshooting
If clicking a deep link does not open Ironspire:
- Windows: check that
HKCU\Software\Classes\ironspireexists in the registry. Reinstalling Ironspire recreates it. - macOS: run
open ironspire://view/settingsfrom Terminal to test. If nothing happens, reinstall the app. - Linux: run
xdg-open ironspire://view/settingsfrom a terminal. If the handler is missing, runxdg-mime default ironspire.desktop x-scheme-handler/ironspire. - Browser blocking: some browsers show a confirmation dialog before opening custom protocols. This is normal browser behaviour and cannot be suppressed. Click Open or Allow when prompted.
If links work from the terminal but not from the browser, check your browser's site settings for protocol handler permissions. Chrome, Edge and Firefox all allow you to permanently allow the ironspire:// protocol for specific sites.