API Endpoints for Omarchy: External Service Integration Guide

Omarchy does not expose its own public API, but as a desktop environment it integrates with six external HTTPS endpoints for AI agents, weather data, network speed testing, and VPN capabilities, all hard-coded in shell scripts and QML plugins.

Omarchy is Basecamp’s open-source desktop environment built for Linux. While the system itself operates as a local graphical shell rather than a web service, it relies on several third-party REST APIs to power features like AI assistance, weather forecasting, and network diagnostics. These integrations are implemented directly in the source code via executable scripts and Qt/QML plugins that construct HTTP requests and parse JSON responses.

AI Service Endpoints

Omarchy includes built-in agents for Fireworks AI and Anthropic Claude, each communicating with their respective cloud APIs to fetch model information and usage statistics.

Fireworks AI Agent

The Fireworks integration uses https://api.fireworks.ai as its base URL for all API operations. According to the source code in bin/omarchy-agent-usage-fireworks, the script authenticates requests using a bearer token stored in the FIREWORKS_API_KEY environment variable.

curl -s -H "Authorization: Bearer $FIREWORKS_API_KEY" \
     "https://api.fireworks.ai/v1/models"

Anthropic Claude Usage Endpoint

For Claude usage tracking, Omarchy queries https://api.anthropic.com/api/oauth/usage. The implementation in bin/omarchy-agent-usage-claude sends authenticated GET requests to retrieve OAuth-scoped consumption data.

curl -s -H "Authorization: Bearer $CLAUDE_API_KEY" \
     "https://api.anthropic.com/api/oauth/usage"

Weather and Geocoding Endpoints

The Weather panel plugin, located at shell/plugins/panels/weather/Panel.qml, communicates with Open-Meteo’s free weather API to resolve location names and fetch forecast data.

Open-Meteo Forecast

The panel retrieves hourly weather data from https://api.open-meteo.com/v1/forecast, passing latitude and longitude coordinates as query parameters.

curl -s "https://api.open-meteo.com/v1/forecast?latitude=37.7749&longitude=-122.4194&hourly=temperature_2m"

Open-Meteo Geocoding

To convert user-input location names into coordinates, the plugin calls the geocoding endpoint at https://geocoding-api.open-meteo.com/v1/search.

curl -s "https://geocoding-api.open-meteo.com/v1/search?name=San+Francisco&count=5&language=en&format=json"

Network and VPN Endpoints

Omarchy also integrates with Fast.com for speed testing and Tailscale for VPN capability detection.

Fast.com Speed Test

The bin/omarchy-network-speedtest script retrieves test URLs from https://api.fast.com/netflix/speedtest/v2 to measure download throughput.

fast_api_url="https://api.fast.com/netflix/speedtest/v2?https=true&token=$FAST_TOKEN&urlCount=5"
fast_urls=$(curl -fsS "$fast_api_url" | jq -r '.targets[]?.url // empty')

# Then each URL in $fast_urls is fetched to measure download speed.

Tailscale Capability Check

In shell/plugins/panels/tailscale/Model.js, the system references https://tailscale.com/cap/file-sharing to verify file-sharing permissions within the Tailscale network.

Authentication and Request Handling

All external API calls in Omarchy follow a consistent pattern: the source files construct HTTPS requests, inject authentication headers (typically Authorization: Bearer <token>), and process JSON responses using tools like curl and jq. These endpoints are not configurable through user settings; they are hard-coded in the respective scripts and plugins at build time.

Key Source Files

• bin/omarchy-agent-usage-fireworks: Implements the Fireworks AI client for model and usage queries.
• bin/omarchy-agent-usage-claude: Handles Claude OAuth usage statistics retrieval.
• shell/plugins/panels/weather/Panel.qml: Contains the QML logic for Open-Meteo weather and geocoding requests.
• bin/omarchy-network-speedtest: Executes network diagnostics against Fast.com’s API.
• shell/plugins/panels/tailscale/Model.js: References Tailscale capability URLs for VPN feature detection.

Summary

• Omarchy is a desktop environment that consumes external APIs rather than exposing its own REST interface.
• The system integrates with Fireworks AI (api.fireworks.ai) and Anthropic Claude (api.anthropic.com) for AI features.
• Weather data comes from Open-Meteo’s forecast and geocoding endpoints.
• Network speed tests use Fast.com’s Netflix-powered speedtest API.
• Tailscale integration checks capabilities via tailscale.com/cap/file-sharing.
• All endpoints are hard-coded in shell scripts and QML plugins, requiring environment variables for authentication.

Frequently Asked Questions

Does Omarchy expose a public REST API?

No. Omarchy functions as a local desktop shell and does not run an HTTP server or expose webhooks. It operates purely as a client to external services.

How does Omarchy authenticate with external AI services?

Authentication uses bearer tokens passed via the Authorization header. The Fireworks script expects a FIREWORKS_API_KEY environment variable, while the Claude script requires CLAUDE_API_KEY.

Can I configure custom API endpoints in Omarchy?

No. The endpoint URLs are hard-coded in the source files (e.g., bin/omarchy-agent-usage-fireworks, shell/plugins/panels/weather/Panel.qml). To use different endpoints, you must modify the source code and rebuild the environment.

Where is the weather data source configured?

The weather panel logic resides in shell/plugins/panels/weather/Panel.qml, which directly calls the Open-Meteo API at api.open-meteo.com. There is no external configuration file; the latitude and longitude are resolved at runtime through the geocoding endpoint or passed as parameters.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}