# API Endpoints for Omarchy: External Service Integration Guide

> Explore Omarchy's API endpoints for integrating external services like AI agents, weather, and VPN. Learn how this desktop environment connects via shell scripts and QML plugins.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: api-reference
- Published: 2026-08-19

---

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

```bash
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.

```bash
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.

```bash
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`.

```bash
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.

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.