# What is Apache Sedona? Source: https://docs.wherobots.com/apache-sedona [Apache Sedona](https://sedona.apache.org/) is a cluster computing system for processing large-scale spatial data. Sedona extends existing cluster computing systems, such as Apache Spark and Apache Flink, with a set of out-of-the-box distributed Spatial Datasets and Spatial SQL that efficiently load, process, and analyze large-scale spatial data across machines. ## Relationship between Apache Sedona and Wherobots Wherobots uses Apache Sedona as an open core to build a cloud data platform optimized for geospatial analytics and AI workloads. Wherobots offers a streamlined experience for executing geospatial workloads, powered by Apache Sedona. Wherobots Inc. was founded by the original creators of Apache Sedona. As an open-source project, Apache Sedona attracts contributions from various leading companies, including Wherobots. Wherobots actively contributes to the development and improvement of Apache Sedona and also develops additional optimizations and proprietary features that enhance and extend the capabilities of Apache Sedona, such as `WherobotsDB`, a full-fledged spatial analytics database system. ## Differences between Apache Sedona and Wherobots | Feature | Apache Sedona | Wherobots | | ----------------------------------------- | ------------------------------------------ | ------------------------------------------------- | | Spatial Functions | 200+ | 300+ | | Data Model | Geometry, In-DB raster | Geometry, In-DB raster, Out-DB raster | | Distributed ETL and Analytics Performance | The fastest open-source engine1 | 20X faster than Apache Sedona (formerly GeoSpark) | | Spatial Data Lake Storage | No | Yes | | Distributed Vector Tiles | No | Yes | | Spatial AI | No | Yes | | Distributed Raster Inference | No | Yes | | Distributed Map Matching | No | Yes | | Deployment Mode | Unmanaged | Fully managed and highly optimized | | Supported Languages | SQL, Scala, Java, Python | SQL, Scala, Java, Python | 1. From [Third-party evaluation](https://sedona.apache.org/latest/community/publication/) in the Apache Sedona documentation: * **SIGMOD 2020:** Tahboub, R. Y., & Rompf, T. (2020). Architecting a query compiler for spatial workloads. *Proceedings of the 2020 ACM SIGMOD International Conference on Management of Data*, 2481–2496. > In Figure 16a, GeoSpark distance join query runs around 7x - 9x faster than Simba, a spatial extension on Spark, on 1 - 24 core machines. * **PVLDB 2018:** Pandey, V., Kipf, A., Neumann, T., & Kemper, A. (2018). How good are modern spatial analytics systems?. *Proceedings of the VLDB Endowment*, *11*(11), 1632-1645. > GeoSpark comes close to a complete spatial analytics system. It also exhibits the best performance in most cases. # API Playground Source: https://docs.wherobots.com/api-playground/index Explore and test the Wherobots Cloud API interactively Interact with the Wherobots Cloud REST API directly from the browser. Select an endpoint below to view request parameters, response schemas, and test the API with live requests using your credentials. All API requests require authentication via a **Bearer token** or [**Wherobots API key**](/get-started/wherobots-cloud/api-keys). ## Try the API The following is a non-exhaustive list of API endpoints you can test in the playground. For a complete list of available endpoints, refer to the [API Reference](/reference/runs). Submit and execute a compute job run Export organization audit log events Generate a pre-signed URL for file uploads # Export audit log as CSV Source: https://docs.wherobots.com/api-reference/audit-log/export-audit-log-as-csv https://api.cloud.wherobots.com/openapi.json get /audit-log/export # Create a job run Source: https://docs.wherobots.com/api-reference/runs/create-a-job-run https://api.cloud.wherobots.com/openapi.json post /runs # Create a presigned file upload URL Source: https://docs.wherobots.com/api-reference/storage/create-a-presigned-file-upload-url https://api.cloud.wherobots.com/openapi.json post /storage/{storage_id}/file-upload-url/{path} # Availability Source: https://docs.wherobots.com/availability This page details Wherobots' current availability commitments. ## Service level agreement A Service level agreement (SLA) guarantee is only available for the Wherobots Enterprise Edition. [Contact us](https://wherobots.com/contact/) for more information about Wherobots Enterprise Edition. | Organization | Service Level Agreement Guarantee | | :------------------- | :-------------------------------- | | Professional Edition | Not available ❌ | | Enterprise Edition | Available ✅ | ## Cloud and Cloud Region Availability If a specific cloud provider or region you need is not listed here, it means Wherobots does not currently support that region and/or provider. Please signal your interest in additional cloud providers and regions by filling out this form: [Cloud Provider Regions](https://resources.wherobots.com/wherobots-regions-cloud-providers). ### Amazon Web Services (AWS) * The Wherobots Cloud service is currently provisioned in the following regions: | AWS Region Name | AWS Region Code | Access | | ----------------- | --------------- | ------------------------- | | Oregon | `us-west-2` | All Organization Editions | | Ireland | `eu-west-1` | Paid Organizations Only | | Northern Virginia | `us-east-1` | Paid Organizations Only | | Mumbai | `ap-south-1` | Paid Organizations Only | * AWS US-West-2 (Oregon) is Wherobots' default region. * Wherobots can access (read and write) data in any private S3 storage bucket located in a public AWS region that you've connected to your Wherobots Organization through an [S3 Storage integration](/develop/storage-management/s3-storage-integration). * Wherobots can access read data in any public S3 storage bucket located in a public AWS region that you've connected to your Wherobots Organization through an [S3 Storage integration](/develop/storage-management/s3-storage-integration). * Wherobots does not currently charge its customers for cross-region data transfer between its cloud service and S3 storage in another region. ### Additional cloud provider regions At Wherobots, we're always working to better serve our customers. Fill out this form to tell us which additional cloud provider regions you need Wherobots to support: [Cloud Provider Regions](https://resources.wherobots.com/wherobots-regions-cloud-providers). # Changelog Source: https://docs.wherobots.com/changelog Product updates and announcements from Wherobots ### OAuth sign-in for Wherobots CLI and VS Code Extension Documentation Documentation detailing how to sign in to Wherobots Cloud from the **Wherobots CLI and VS Code Extension** with OAuth is now available. #### Wherobots CLI * Run `wherobots auth login` to sign in from your browser. Over SSH or on a headless machine, add `--no-browser` to complete the flow on any other device. * Check the active credential with `wherobots auth status`, and sign out with `wherobots auth logout`. #### Wherobots VS Code Extension * Run `Wherobots: Sign In` from the Command Palette to sign in from your browser, and `Wherobots: Sign Out` to sign out. API keys continue to be supported for those who prefer or require them. `Wherobots: Set API Key` also remains in the Command Palette. ### Wherobots is now in the Claude Connector Directory The **Wherobots Spatial AI Assistant** is now published in Anthropic's connector [Directory](https://claude.ai/directory), so you can add Wherobots to Claude in just a few clicks. Creating a Custom Connector is **no longer required**. Wherobots in Claude Directory #### What's new * **Add **Wherobots Spatial AI Assistant** from the Directory:** In Claude on the web or Claude Desktop, browse the [**Directory**](https://claude.ai/directory), search for `Wherobots`, and select **Wherobots Spatial AI Assistant**. * **OAuth sign-in:** Connect with your existing Wherobots Account and select which Organization Claude can access. No API keys or manual MCP configuration. * **Query data in the conversation:** Ask questions in plain language and get spatial SQL results back in Claude, across the open datasets in the Wherobots Global Hub and any of your own [storage integrations and catalogs](/develop/storage-management/wherobots-cloud-storage-overview). Connectors require a paid Claude subscription. On Team and Enterprise plans, a Claude administrator controls which Directory connectors are available to your Organization. #### Learn more * [Install Wherobots CLI](/develop/cli) * [Install the Wherobots VS Code Extension](/develop/vscode-extension/setup) * [Set Up Wherobots in Claude Desktop and Web](/develop/agentic-tools/claude-desktop-and-web) * [MCP Server Best Practices](/develop/mcp/mcp-server-usage) * [The Wherobots Spatial AI Assistant is now in the Anthropic Connectors Directory](https://wherobots.com/blog/spatial-ai-assistant-anthropic-connectors/) ### Connect an Amazon S3 Tables catalog Wherobots now supports connecting an **Amazon S3 table bucket** as an Iceberg catalog directly from the [**Data Hub**](https://cloud.wherobots.com/data-hub). Data Hub Extension with Amazon S3 Tables now included #### What is new * **Amazon S3 Tables integration available:** Add an S3 table bucket from the [**Data Hub**](https://cloud.wherobots.com/data-hub) with a guided CloudFormation deployment without having to write IAM policies or Spark configuration by hand. * **Read-only or read-write access:** Choose whether Wherobots can only read your Iceberg tables, or also create and modify them. * **Reusable Cloud Connections:** S3 Tables catalogs can use the same [Cloud Connection](/get-started/initial-storage/aws/connect-to-s3-tables-catalog#cloud-connections) model as Glue catalogs and S3 storage integrations. #### Learn more * [Connect to Amazon S3 Tables Catalog](/get-started/initial-storage/aws/connect-to-s3-tables-catalog) * [Query Amazon S3 Tables Catalog in a Notebook](/get-started/initial-storage/aws/query-s3-tables-catalog-in-a-notebook) ### Community Edition has been retired Wherobots has retired the **Community Edition**. New customers now start on the **Professional Edition**, beginning with a free Professional Edition trial. #### What is changing * **New sign-ups start on Professional:** Registering for Wherobots Cloud now starts a free [Professional Edition trial](/get-started/wherobots-cloud/create-account). * Add [a payment method](/get-started/add-payment-method) — Direct Billing or an AWS Marketplace subscription — to continue on the Professional Edition after your trial. * **Professional is the new minimum Organization tier:** All new Organizations start on the Professional Edition. * You can also contact sales to upgrade to the **Innovation** or **Enterprise Edition**. For more information, see [Wherobots Pricing](https://wherobots.com/pricing) or [Organization Editions](/get-started/organization-management/organization-editions). ### New Glue Catalog Connection and easier S3 setup with Cloud Connections Wherobots now supports connecting your **AWS Glue Catalog** directly from the [**Data Hub**](https://cloud.wherobots.com/data-hub) with a guided setup flow. #### What is new * **Glue Catalog Connection wizard:** Add an AWS Glue Catalog from the [**Data Hub**](https://cloud.wherobots.com/data-hub) and validate access with guided CloudFormation deployment. * **Simplified S3 integration setup:** Create or select an existing Cloud Connection inside the S3 integration flow and reuse it across integrations. * **Reusable Cloud Connection model:** Manage one Cloud Connection per AWS account and bind it to multiple storage integrations and Glue catalogs. * **BYOC compatible:** The Cloud Connection model works with [Bring Your Own Cloud (BYOC)](/develop/storage-management/byoc) by scoping access with an **Allowed compute** option. #### Learn more * [Connect to AWS Glue Catalog](/get-started/initial-storage/aws/connect-to-glue-catalog) * [Query AWS Glue Catalog in a Notebook](/get-started/initial-storage/aws/query-glue-catalog-in-a-notebook) * [Set up S3 Storage Integration](/develop/storage-management/s3-storage-integration) * [Bring Your Own Cloud (BYOC)](/develop/storage-management/byoc) ### OAuth Authentication for MCP Server We've added **OAuth** support to the Wherobots MCP server, so you can sign in directly from your browser, with minimal setup required. With OAuth support, you can now use the Wherobots MCP server's spatial intelligence in **Claude, ChatGPT, and Codex** (both web and desktop applications). #### Get started with OAuth authentication Review the updated installation instructions for using the Wherobots MCP server with your desired agentic tool: **Note the following:** * OAuth sign-in requires an **existing** Wherobots account and Organization. * If you don't have an account or Organization yet, follow [Create an Account](/get-started/wherobots-cloud/create-account) first to get started. * The [VS Code Extension](/develop/agentic-tools/vscode) continues to use API key authentication. ### AWS us-east-2 (Ohio) Region Support Paid Organizations can now deploy their Wherobots compute environments and manage resources within the AWS `us-east-2` (Ohio) region. **Benefits:** * **Lower Latency**: Deploy closer to your users and data sources * **Architectural Flexibility**: Build geographically distributed applications [Create a notebook in the AWS us-east-2 Region](https://cloud.wherobots.com) **Ohio AWS Region Support is limited to Paid Organizations** Deployment in the `us-east-2` (Ohio) region requires a Professional or Enterprise Organization. Community Edition is limited to `us-west-2`. ### Wherobots CLI now available in Public Preview The [Wherobots CLI](/develop/cli) is a session lifecycle management tool for Wherobots Cloud. Use it directly from your terminal to submit jobs, stream logs, monitor resource usage, and manage workloads across their full lifecycle. The Wherobots CLI is designed to work with agentic coding terminals like **OpenCode**, **Claude Code**, and other AI-powered terminals, so you can manage session lifecycles using natural language. #### Key capabilities * **Agentic terminal support:** Use the CLI from AI-powered terminals to manage job lifecycles, stream logs, and access the full API with [natural language](/develop/cli-agentic-usage). * **Session lifecycle management:** Create Job runs, monitor their status, stream logs in real time, check resource metrics, and cancel or clean up sessions, all without leaving your terminal. * **API access:** API endpoints are available as CLI commands, generated dynamically from the OpenAPI specification. Use `wherobots api --tree` to explore. * **Automation-friendly output:** Switch between human-readable table output and JSON output to integrate the CLI into shell scripts, CI/CD pipelines, and orchestration tools. * **Dry-run mode:** Use the `--dry-run` flag to preview the equivalent `curl` command before executing any request. #### Get started Review the [CLI documentation](/develop/cli) for installation instructions, authentication setup, and usage examples, or see [Agentic terminal usage](/develop/cli-agentic-usage) to get started with natural language job management. ### SAM3 Text-Prompted Object Detection in RasterFlow RasterFlow now supports [Meta's Segment Anything Model 3 (SAM3)](https://ai.meta.com/research/sam3/) for text-prompted geometry inference. Given a natural language prompt like `"roofs"` or `"swimming pools"`, SAM3 detects objects in aerial imagery and returns georeferenced vector geometries or bounding boxes with confidence scores. Unlike segmentation models that produce raster outputs, SAM3 directly outputs vector geometries, making it straightforward to integrate results into geospatial workflows. **Two model recipes are available:** * **`SAM3_TEXT_BBOX`** — Detect objects and produce georeferenced bounding box geometries * **`SAM3_TEXT_GEOMETRY`** — Detect objects and produce georeferenced polygon geometries Both recipes are configured to use NAIP imagery at 30cm resolution. See [this map](https://esri.maps.arcgis.com/apps/mapviewer/index.html?webmap=6cc0dcb225de4cb8aaa23c6a9cb59db8) for coverage information. Multiple text prompts can be passed simultaneously to detect several object types at once. RasterFlow is currently in Private Preview. Wherobots is rolling out RasterFlow to a select group of Organizations. If you are interested in gaining early access to these new capabilities and helping shape the future of the product, [register your interest here](https://wherobots.com/rasterflow-preview/). **Learn more:** See the [Detecting Objects From Text Prompts with RasterFlow](/tutorials/example-notebooks/rasterflow-sam3) tutorial for a step-by-step walkthrough using SAM3 to detect rooftops in College Park, Maryland. ### Raster Inference Deprecated in Favor of RasterFlow WherobotsAI Raster Inference has been deprecated and replaced by [RasterFlow](/develop/rasterflow/index), the next generation of raster ML inference on Wherobots. All Raster Inference tutorial pages now redirect to the RasterFlow overview. ### WherobotsDB v2 is Now the Default Runtime DBv2 delivers a substantial improvement in price performance. DBv2 accelerates queries by up to 3x. We expect customers will see 20-30% better query price performance compared to DBv1. This new generation of the platform is also compatible with Apache Spark 4, and will be the default runtime version used in WherobotsDB moving forward Previously available as a preview, v2 is now the production default. The `"latest"` version parameter now resolves to the WherobotsDB v2 line. #### Faster Queries We measured DBv2 performance using SpatialBench and TPC-H benchmarks. Note the improvements compared to DBv1: | Benchmark | Peak improvement | Mean improvement | | :------------------------------------------------------------- | :--------------: | :--------------: | | **Spatial queries** (SpatialBench @ scale factor of 1000) | 2.5x | 1.9x | | **Standard analytical queries** (TPC-H @ scale factor of 1000) | 3x | 1.7x | For a detailed breakdown of Spatial Unit (SU) consumption rates, see the [Runtime specification chart](/develop/runtimes#runtime-specifications-chart). Benchmarks were performed using a general purpose medium runtime. #### Better Price Performance This next generation of WherobotsDB offers significantly more horsepower per runtime, which will be reflected by an increase in spatial units (SUs) emitted per runtime hour when DBv2 is GA. After this adjustment, we expect customers to experience **20-30% better price performance**. #### Rollout plan The transition to WherobotsDB v2 as the default will be applied based on organization type and workload: | Scenario | Default version | | :------------------------------------- | :------------------------------------------------------------------------------- | | **New Organizations** | v2 is the default for all workloads (Jobs and Notebooks) | | **Existing Organizations (Notebooks)** | Notebooks are pinned to the latest Wherobots version, which is now v2 | | **Existing Organizations (Jobs)** | v2 is the default only if the Organization has not run a Job in the last 90 days | If your Organization has run a Job within the last 90 days, your Jobs will continue to use the v1 runtime by default. You can opt in to v2 by explicitly setting the `version` parameter in your Job Run or SQL Session API requests, or by updating your [Environment Preset](/develop/notebook-management/environment-presets). #### What you need to know * **Apache Spark 4.0 & Apache Hadoop 3.4:** v2 includes upgrades to Spark 4.0 and Hadoop 3.4. Review the [2.1.0 release notes](#spark-4-0-&-hadoop-3-4-upgrade) for breaking changes. * **Pinning a version:** You can pin to a specific v1 or v2 version using the `version` parameter in API requests or through [Environment Presets](/develop/notebook-management/environment-presets). ### Upgrade to Professional Edition with Direct Billing Getting started with a paid Wherobots Organization just got simpler. You can now upgrade directly in Wherobots Cloud using a credit card or bank account — no AWS Marketplace subscription required. #### Why this matters Teams that don't use AWS, or prefer to keep their Wherobots billing separate, can now go from Community to Professional in minutes. * **Two upgrade paths:** Choose [Direct Billing](/get-started/add-payment-method#direct-billing) for a streamlined experience billed by Wherobots, or continue using the [AWS Marketplace](/get-started/add-payment-method#aws-marketplace) if that fits your workflow. * **Self-service cancellation:** Cancel your Organization directly from [Organization Settings > Billing](https://cloud.wherobots.com/organization#billing) at any time. * **Invoice management:** Invoices are emailed to your configured billing contact and accessible to any Admin via [View Invoicing](https://cloud.wherobots.com/organization#billing). * **Billing contact flexibility:** Set an individual email or a team alias (e.g., `billing@yourcompany.com`) as your billing contact. Ready to upgrade your Community Edition Organization? Go to [**Organization Settings > Billing**](https://cloud.wherobots.com/organization#billing). #### Switching billing methods For more information on switching between Direct Billing and AWS Marketplace, see [Change Your Billing Method](/get-started/organization-management/change-billing-method). ### Wherobots VS Code Extension now available The [Wherobots VS Code Extension](https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit) turns VS Code and any Code OSS-based editors into an agentic geospatial engineering workspace. The extension also supports [Kiro](https://kiro.dev/) by Amazon for users who have given Kiro access to their GitHub Copilot account. Wherobots VS Code Extension Now with the extension in Public Preview, all Organizations can install the extension and run local notebooks against Wherobots compute. Professional and Enterprise Organizations can additionally use the Wherobots MCP-powered spatial query execution, AI-assisted workflows, additional compute tiers, and job submission without leaving their editor. #### Install the extension from the command line Install the extension by running one of the following commands in your terminal or by installing directly from the marketplace for your editor: ```bash VS Code theme={"system"} code --install-extension wherobots.wherobotsjobsubmit ``` ```bash Kiro theme={"system"} kiro --install-extension Wherobots.wherobotsjobsubmit ``` ```bash Cursor theme={"system"} cursor --install-extension Wherobots.wherobotsjobsubmit ``` ```bash Windsurf theme={"system"} windsurf --install-extension Wherobots.wherobotsjobsubmit ``` ```bash Positron theme={"system"} positron --install-extension Wherobots.wherobotsjobsubmit ``` ```bash Antigravity theme={"system"} antigravity --install-extension Wherobots.wherobotsjobsubmit ``` ```bash Trae theme={"system"} trae --install-extension Wherobots.wherobotsjobsubmit ``` ```bash VS Codium theme={"system"} codium --install-extension Wherobots.wherobotsjobsubmit ``` If your editor prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload** to install it and reload the window. The Wherobots extension depends on other extensions that may not be pre-installed in all editors. ```markdown Visual Studio Marketplace theme={"system"} https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit ``` ```markdown Open VSX (Code OSS-based editors) theme={"system"} https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit ``` Review the [installation guide](/develop/vscode-extension/setup) to finish the setup. #### Key capabilities * **Accelerated notebook development:** Instead of starting from scratch, use Copilot to [generate entire notebooks with natural language prompts](/develop/vscode-extension/notebooks). * **Run notebooks on Wherobots compute:** Execute these generated notebooks using Wherobots compute, without leaving your editor. * **MCP-powered spatial Q\&A:** Query data catalogs and empower your AI assistants to execute spatial SQL and Python workflows via the automatically configured [Wherobots MCP Server](/develop/mcp/mcp-server-overview). * **Notebook lifecycle management:** [Create, start, stop, and manage workspaces](/develop/vscode-extension/workspaces) from your editor's sidebar, with access to the Spark UI and Jupyter URLs. * **Job submission:** [Submit `.py` files as cloud job runs](/develop/vscode-extension/jobs) with configurable runtime, region, timeout, and arguments -- including inline job configuration via Python comments. ### RasterFlow now available in Private Preview [Wherobots RasterFlow](/develop/rasterflow) is an inference engine for large-scale raster processing and geospatial machine learning workflows. Build mosaics from multiple raster data sources, run inference with computer vision models, and vectorize results. RasterFlow is currently in Private Preview. Wherobots is rolling out RasterFlow to a select group of Organizations. If you are interested in gaining early access to these new capabilities and helping shape the future of the product, [register your interest here](https://wherobots.com/rasterflow-preview/). #### Supported models Currently, four pre-trained models are available in RasterFlow for different geospatial use cases: **Fields of the World**, **Tile2Net**, **Meta CHM v1**, and **ChesapeakeRSC**. We have created notebooks demonstrating how to use these models for real-world applications. Click the links below to try these notebooks out in Wherobots Cloud! #### Key capabilities * **Planetary-scale processing:** Process raster data at massive scale with optimized chunking, sharding, and parallel processing * **Simple, high-level API:** Abstract away the complexity with pre-configured datasets and models—or bring your own * **Build mosaics:** Combine multiple raster datasets into unified mosaics that are ready for further analysis * **Run model inference:** Apply machine learning models to massive raster datasets at scale * **Vectorize results:** Convert raster predictions into vector geometries for spatial analysis ### Wherobots MCP Server now available for public preview Transform your spatial data workflow with SQL generation available right inside VS Code! Focus on your analysis rather than syntax. With the Wherobots MCP Server, you can explore data catalogs and turn plain text descriptions into executable spatial SQL directly within your code editor. **Key Features:** * **Natural Language Queries:** Turn plain text descriptions into valid spatial SQL. * **Organization Access:** Available for Professional and Enterprise Organizations. Usage is tracked as SQL Sessions in your [Workload History](https://cloud.wherobots.com/workloads). * **Integrated Workflow:** Draft, execute, and iterate on your spatial SQL without leaving the VS Code environment. * **Quick Setup:** [Set up the MCP Server](/develop/mcp/mcp-server-overview) and get started in minutes. * **Usage Guide:** Review the [MCP Server usage guide](/develop/mcp/mcp-server-usage) for best practices, more example prompts, and cost considerations. **Here are some interesting prompts to try:** * "What catalogs are available in my Organization?" * "What data sources should I use to analyze road networks in the US?" * "Write a SQL query to find all burger restaurants within 5 miles of downtown San Francisco." We'd love to hear from you! This is an early preview, and your feedback will shape the future of this feature. Share your experience at [support@wherobots.com](mailto:support@wherobots.com) or [schedule time with our product team](https://calendly.com/pouyan-wherobots/30min?month=2026-01). ### Job Runs section is now Workload History The **Job Runs** section in Wherobots Cloud has been renamed and expanded to **Workload History**, providing unified monitoring for all compute workloads across your Wherobots Organization. **What's new:** * **Unified view:** Monitor Notebooks, SQL Sessions, and Job Runs in a single interface * **Enhanced filtering:** Filter by time range, owner, region, and workload type * **Usage visualization:** View quota consumption over time with an interactive chart * **Execution logs:** Access detailed logs for debugging and troubleshooting directly in the UI with search, copy, and download capabilities **Key Features:** * Filter workloads by name, ID, owner, region, or type * View detailed metrics including duration, CPU utilization, memory usage, cost, and Spatial Units consumed * Access real-time execution logs with search functionality * Compare performance across different runtime configurations * Cancel running workloads directly from the interface * View estimated costs and Spatial Units consumed for each workload [View Workload History](https://cloud.wherobots.com/workloads) in Wherobots Cloud to get started! ### Spark 4.0 & Hadoop 3.4 Upgrade This release introduces significant infrastructure upgrades to Spark 4.0 and Hadoop 3.4. Please review the breaking changes below to ensure workflow continuity. This functionality is exclusive to version 2.X of the runtime, which is currently in preview. To access these changes, you must enable the **Preview WherobotsDB 2.0** checkbox in [Wherobots Cloud](https://cloud.wherobots.com) when starting your notebook. **Upgrade to Spark 4.0** * **ANSI SQL Enabled by Default:** The default SQL model has changed to ANSI SQL. * **Action Required:** Review and migrate existing SQL queries to ensure compliance with ANSI standards. * **Third-Party JAR Updates:** Existing data source JARs may no longer be compatible. * **Action Required:** Replace current jars with versions that support Spark 4. **Upgrade to Hadoop 3.4** * **Hadoop JAR Updates:** Third-party Hadoop libraries require updates. * **Action Required:** Replace current jars with versions that support Hadoop 3.4. ### WherobotsDB Introduces Spatial Support on Iceberg Views WherobotsDB now provides spatial support for Apache Iceberg views, enabling you to leverage spatial functions and operations directly on view definitions. ### System Improvements and Performance Enhancements This release includes general system improvements, performance enhancements, and backend stability updates. No breaking changes were introduced. ### Enhanced SSO Methods and Passkeys We have overhauled our authentication system to provide more flexible and secure ways to access Wherobots Cloud. **New login methods:** * **Google** account login * **GitHub** account login * **Passkeys**: Register with passkeys for faster and more secure sign-in using device biometrics or screen lock **Action Required for SSO Users** If you have previously configured Single Sign-On (SSO) for your organization, you **must re-configure it** following this update. Navigate to the [**Security**](https://cloud.wherobots.com/organization#security) page to set up SSO again. ### Multi-Organization Support A single user account can now belong to multiple Wherobots organizations with no limit on the number of organizations you can join or manage. Additionally, you can now change your first and last name within your user profile. **Available in all editions:** Community, Professional, and Enterprise ### System Improvements and Performance Enhancements This release includes general system improvements, performance enhancements, and backend stability updates. No breaking changes were introduced. ### New Functions: ST\_ApproximateMedialAxis and ST\_StraightSkeleton We have introduced two new spatial SQL functions for advanced geometry processing: * [**`ST_ApproximateMedialAxis`**](/reference/wherobots-db/geometry-data/processing/ST_ApproximateMedialAxis): Computes an approximate medial axis of polygonal geometries, useful for extracting skeletons from shapes, road centerlines, or river networks. * [**`ST_StraightSkeleton`**](/reference/wherobots-db/geometry-data/processing/ST_StraightSkeleton): Computes the straight skeleton or "centerline" of a polygon. This centerline is useful in roof modeling, map generalization, and shape analysis. ### System Improvements and Performance Enhancements This release includes general system improvements, performance enhancements, and backend stability updates. No breaking changes were introduced. ### System Improvements and Performance Enhancements This release includes general system improvements, performance enhancements, and backend stability updates. No breaking changes were introduced. ### AWS ap-south-1 (Mumbai) Region Support Paid Organizations can now deploy their Wherobots compute environments and manage resources within the AWS `ap-south-1` (Mumbai) region. **Benefits:** * **Lower latency**: Deploy closer to users, data sources, or endpoints in India and South Asia * **Architectural flexibility**: Build geographically distributed applications for South Asia [Create a notebook in the Mumbai Region](https://cloud.wherobots.com) **Mumbai AWS Region Support is limited to Paid Organizations** Deployment in the `ap-south-1` (Mumbai) region requires a Professional or Enterprise Organization. Community Edition is limited to `us-west-2`. ### System Improvements and Performance Enhancements This release includes general system improvements, performance enhancements, and backend stability updates. No breaking changes were introduced. ### Data Federation for Databricks Unity Catalog Customers can now securely connect Wherobots to their governed datasets in Unity Catalog within our Wherobots' new [**Data Hub**](https://cloud.wherobots.com/data-hub). With this capability, Paid Wherobots Organizations can connect their Unity Catalog tables to Wherobots high-performance compute and spatial ETL, without copying or moving data. **Benefits:** * Zero-Copy architecture: Read tables managed by Unity Catalog without moving or duplicating data * Maintained governance: Databricks Workspace Admins retain catalog- and table-level access control * Secure federation: Connect securely using Databricks authentication credentials * Accelerated innovation: Use Wherobots' 300+ spatial functions, raster inference, and compute on Unity Catalog data **Key features:** * Direct Unity Catalog connection from Wherobots Data Hub * Full read and write operations on Managed Iceberg tables * Read access to Delta Lake tables * Advanced Spatial analytics with 300+ spatial functions Only Professional and Enterprise Edition Organizations can use the Databricks Unity Catalog Integration. Community Edition Organizations are limited to Wherobots-managed catalogs and open datasets. [Connect Wherobots to Databricks Unity Catalog](/get-started/initial-storage/connect-to-unity-catalog) ### System Improvements and Performance Enhancements This release includes general system improvements, performance enhancements, and backend stability updates. No breaking changes were introduced. ### Enhanced Accuracy for ST\_Transform We've introduced an enhancement to the `ST_Transform` function to significantly improve the accuracy of Coordinate Reference System (CRS) transformations. The `ST_Transform` function now includes an optional `AOI` (Area of Interest) parameter. By specifying an `AOI`, the transformation process uses a relevant subset of local grid files, resulting in more precise and reliable CRS transformations for your geospatial data. This is especially beneficial for large-scale and high-precision mapping applications. **Example usage:** ```sql theme={"system"} SELECT ST_Transform( geom, 'EPSG:4326', 'EPSG:26910', '{"area_of_interest": "POLYGON((-122.5 37.7, -122.3 37.7, -122.3 37.8, -122.5 37.8, -122.5 37.7))"}' ) FROM my_table; ``` **Versions:** `1.11.1`, `2.0.1-preview` ### GeoTools Upgrade, Python Path Standardization, and WKB Writer Update This release introduces several significant updates. No workflow impact is expected, but please submit a bug report if you encounter any issues. **Potentially Breaking Changes:** * **GeoTools Library Upgrade:** The GeoTools library has been upgraded from `v28.5` to `v33.1`. This could introduce changes in behavior for `ST_Transform` and various raster functions. * **Python Import Path Standardization:** Python import paths under `sedona.XXX` are now deprecated in favor of `sedona.spark.XXX`. * **WKB Writer Default Byte Order:** The default WKB writer byte order has changed to little-endian. This change might affect GeoParquet files, Havasu-Iceberg tables, and `ST_AsWKB` functions. **Submit a bug report:** * **Community Organizations:** Share your feedback in the `#vendor-wherobots` channel on the [Apache Sedona Discord](https://discord.com/invite/9A3k5dEBsY). * **Professional & Enterprise Organizations:** Send feedback to [support@wherobots.com](mailto:support@wherobots.com). **Versions:** `1.11.0`, `2.0.1-preview` ### WherobotsDB 2.0 Preview Accelerate common data operations such as filtering, aggregation, and join queries by up to 2x. Experience significantly faster and more efficient analysis of your non-spatial data, thanks to recent optimizations in our core engine. **How to enable the preview:** In [Wherobots Cloud](https://cloud.wherobots.com), select **Preview WherobotsDB 2.0** when starting a runtime, or set the `version` parameter to `"preview"` in Job Run and SQL Session API requests. We encourage you to enable the preview, run your typical workloads, and share your feedback with us. **Version:** `2.0.0-preview` ### Dekart Integration Utilize **Wherobots'** compute directly within [**Dekart**](https://dekart.xyz/), an open-source platform that quickly creates rich, interactive map visualizations from spatial SQL queries. **Benefits:** * Go from Spatial SQL to an interactive map in seconds * Create up-to-date visualizations from large, dynamic datasets * Avoid proprietary lock-in with open-source architecture **Key Features:** * Direct authentication with Wherobots API keys * Query with Spatial SQL from Dekart interface * Instant visualization with Kepler.gl maps * Bring Your Own Data from AWS S3 [Create a Dekart Workspace](https://dekart.xyz/) ### Enhancing Isochrone and Reverse Geocoding The backend data tables that power our **isochrone** and **reverse geocoding** functions have been updated to the latest versions from the **Overture Maps Foundation**. These tables will now **automatically keep themselves up-to-date** as new Overture data is released. This means your results will always be based on the freshest and most accurate global road network and place data available. **Version:** `1.10.3` ### New Address Parsing and Standardization Functions This release introduces two powerful Spatial SQL functions for address data processing, based on the `libpostal` library: * **`ExpandAddress`**: Normalizes and expands address strings into their canonical forms (e.g., "st" becomes "street," "apt" becomes "apartment") * **`ParseAddress`**: Breaks down a single address string into its individual components (house number, street, city, state, postcode) **Version:** `1.10.2` ### Hadoop Dependency Update We have upgraded Wherobots' Hadoop dependency from version `3.3.4` to `3.3.6` to enhance platform stability and security. **Version:** `1.10.1` ### Security Updates and Scala 2.13 Migration This update focuses on enhancing the stability and security of the Wherobots Cloud platform. **Breaking Change - Migration to Scala 2.13:** To ensure future compatibility with Apache Spark 4, we've updated WherobotsDB's Scala version from 2.12 to 2.13. **Who is affected:** * Customers who compile and deploy custom Scala applications or UDFs as `.jar` files * Users of the Scala kernel for Scala notebooks **Required action:** * Update your build environment to use a Scala `2.13.x` compiler * Update all dependencies from their `_2.12` versions to their `_2.13` versions * Recompile your project to produce a new `.jar` file compatible with Scala 2.13 **Other improvements:** * Bug fixes for improved performance and reliability * Dependency security updates with latest patches **Version:** `1.10.0` ### Stability and Security Enhancements Bug fixes and dependency security updates to improve overall performance, reliability, and security of WherobotsDB. **Version:** `1.9.2` ### Vectorized Python UDFs and OSM Data Support * **New Feature:** Added support for vectorized User Defined Functions (UDFs) in Python * **New Feature:** Introduced a parser for OpenStreetMap (OSM) nodes data within the OSM PBF reader * **Improvement:** Enhanced error messaging for invalid geometries during tile generation **Version:** `1.9.0` ### Java 17, GDAL 3.8.4, Spark 3.5.5 & Ubuntu 24.04 **Platform upgrades:** * Operating System: Upgraded from Ubuntu 22.04 to 24.04 LTS * GDAL: Upgraded from version 3.4.1 to 3.8.4 * Java: Standardized on Java 17 (LTS), moving from Java 19 * Spark: Updated from 3.5.4 to 3.5.5 **Expected breaking changes:** * **Java 17 (LTS):** Custom code, UDFs, or JAR files compiled for Java 19 will need recompilation using Java 17 SDK * **GDAL 3.8.4:** May alter behavior of certain geospatial functions. Review [GDAL release notes](https://github.com/OSGeo/gdal/releases) for versions 3.5-3.8 **Version:** `1.9.0` ### AWS us-east-1 (N. Virginia) Region Support Paid Organizations can now deploy their Wherobots compute environments and manage resources within the AWS `us-east-1` (N. Virginia) region. **Benefits:** * **Lower Latency**: Deploy closer to US East Coast users and data sources * **Optimized AWS Ecosystem Integration**: Seamless integration with existing AWS resources in `us-east-1` * **Data Residency & Compliance**: Meet data residency requirements on the US East Coast * **Architectural Flexibility**: Build geographically distributed applications [Create a notebook in the N. Virginia Region](https://cloud.wherobots.com) ### EU Region Support (AWS eu-west-1) Our first compute region outside the United States! Workload capabilities are now available in AWS `eu-west-1` (Ireland). **Benefits:** * **Compliance**: Run notebook compute resources within the EU to aid in meeting GDPR and data sovereignty requirements * **Latency Reduction**: Potentially increase performance for data sources located in Europe * **Workflow Efficiency**: Set a default EU region for new notebooks **Key Features:** * Notebooks, Job Runs, and SQL Sessions can run in `eu-west-1` * Default Region Preference for Admins * Wherobots File System storage located within your selected region **EU Region Support is limited to Paid Organizations** Only Professional and Enterprise Edition Organizations can use `aws-eu-west-1`. Community Edition Organizations are limited to AWS `us-west-2`. ### SAM2 Support in WherobotsAI Raster Inference Wherobots is excited to announce enhancements to **WherobotsAI Raster Inference**, including the introduction of Text-Based Raster Detection & Segmentation. We've integrated support for Meta AI's **Segment Anything Model 2 (SAM2)** and Google DeepMind's **OWLv2** models for text-prompted inference. **New features:** * **`RS_Text_to_BBoxes`**: Text-prompted object detection returning bounding boxes, confidence scores, and labels * **`RS_Text_to_Segments`**: Text-prompted instance segmentation returning segmentation polygons, confidence scores, and labels **New example notebook:** Demonstrates detecting and segmenting airplanes in NAIP imagery using the simple text prompt "airplanes". Access requires execution on **GPU-Optimized runtimes** within Wherobots Cloud. By default, GPU access is limited to **Professional and Enterprise Edition Organizations** who have requested and been granted access. Professional and Enterprise Organizations needing GPU access should submit a compute request to **[support@wherobots.com](mailto:support@wherobots.com)**. [Access Wherobots Cloud](https://cloud.wherobots.com/) ### Audit Logs Admins for Professional and Enterprise Organizations now have access to the Wherobots [**Audit Logs**](https://cloud.wherobots.com/organization/audit-logs) feature and its associated REST API endpoint. **Benefits:** * **Enhanced Security**: Monitor key activities to identify potential security risks * **Improved Accountability**: Track user actions and system events * **Operational Transparency**: Gain insights into resource usage * **Data Retention**: Use the API to preserve logs beyond Wherobots' 90-day retention period **Key Features:** * Comprehensive activity tracking across security, files, jobs, notebooks, organization, data, and runtimes * Intuitive UI with flexible filtering * On-demand CSV export from UI * Programmatic export via REST API * Admin-only access [View Audit Logs](https://cloud.wherobots.com/organization/audit-logs) ### Travel Isochrones Functionality and Dataset Professional and Enterprise Organizations now have access to `ST_Isochrone` and `ST_Isochrones` for generating travel time isochrones. We're also releasing the **Overture Places with Isochrones** dataset, which augments the original Overture Places dataset with columns defining the 5, 10, 15, and 20-minute travel time boundaries from each of 13.3 million US Places. **New Features:** * **`ST_Isochrone`**: Generate a single polygon representing the reachable area within a specified time * **`ST_Isochrones`**: Generate an array of polygons for multiple time limits * **Dataset Enrichment**: Overture Places enriched with 4 new isochrone geometry columns ```sql theme={"system"} -- ST_Isochrone Example ST_Isochrone(geometry, 1, 'car', false) -- ST_Isochrones Example ST_Isochrones(geometry, array(1, 1.5, 2), 'car', false, true) ``` Only Professional and Enterprise Edition Organizations have access to `ST_Isochrone`, `ST_Isochrones`, and the Overture Places with Isochrones dataset. ### Job Run Monitoring Wherobots Cloud now provides integrated visualizations for [**Job Runs**](https://cloud.wherobots.com/job-runs), allowing you to monitor Job Run execution, resource usage, and configuration directly in the Wherobots Cloud platform for Paid Organization Tiers. **Key Features:** * Job Runs Summary View with status, trigger, duration, and details * Detailed information including consumption metrics (Spatial Units, CPU, Memory) * Filtering capabilities by name * Job Run cancellation directly from the UI * Configuration information display [Monitor Job Runs](https://cloud.wherobots.com/job-runs) ### Idle Timeout for Notebooks Wherobots Cloud has a new **Idle Timeout** feature to help you better manage your notebook runtime resources and optimize costs. **Key Features:** * **Customizable Timeout**: Select 15 minutes, 45 minutes (default), or 120 minutes * **Persistent User Settings**: Your chosen setting is saved across sessions * **Automatic Kernel Termination**: Jupyter kernel terminates after idle period * **Notebook Instance Specific**: Only applies to Notebook Instances, not Job Runs [Start a Notebook](https://cloud.wherobots.com/notebooks) ### STAC Reader for Wherobots The new **STAC Reader** data source loads STAC (SpatioTemporal Asset Catalog) items and collections directly into Sedona DataFrames. **Benefits:** * **Direct STAC Integration**: Access STAC-compliant catalogs directly in Wherobots workflows * **Performance Optimization**: Spatial and Temporal Filter Pushdown reduces data transfer and processing * **Flexible Data Access**: Connect via HTTP/HTTPS endpoint, S3-compatible object store, or local JSON file **Example usage:** ```python theme={"system"} df = sedona.read.format("stac").load("https://earth-search.aws.element84.com/v1/collections/sentinel-2-pre-c1-l2a") df.printSchema() df.show() ``` [Read the STAC Reader Documentation](/reference/wherobots-db/vector-data/stac) ### 1.4 - A Major Leap Forward for Wherobots Wherobots 1.4 delivers significant advancements with a host of new features for **WherobotsDB** and **WherobotsAI**. **Key Features:** | Feature | Professional/Enterprise | Community | | :---------------------------------: | :---------------------: | :-------: | | Job Run Automation with Airflow | ✅ | ❌ | | Amazon S3 Storage Integration | ✅ | ❌ | | WherobotsAI Raster Inference | ✅ | ❌ | | Reverse Geocoding | ✅ | ✅ | | Long-lived Token Management | ✅ | ❌ | | Distributed K Nearest Neighbor Join | ✅ | ✅ | | Spatial Join Optimizations | ✅ | ✅ | | GeoStats Toolbox | ✅ | ✅ | **Amazon S3 Integration:** Accelerate spatial data product creation by using data directly from Amazon S3 public or private buckets, bypassing time-consuming data transfers. **Job Run Automation with Airflow:** Integrate Wherobots' geospatial processing into your Airflow workflows using the `WherobotsRunOperator`. **WherobotsAI Raster Inference:** Uses computer vision to gather insights from raster data at planetary scale (requires GPU-Optimized runtime for Paid Organizations). **AWS Marketplace Listing:** Create a new Professional Organization or upgrade through the [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-ndy62v6hhwrne). **Long-lived Token Management:** Professional Edition Organization Administrators can use service principals for API authentication through long-lived tokens. ### Wherobots 1.3 This major release includes: **WherobotsDB** - A scalable spatial analytics database system: * Spatial query engine: compatible with Apache Sedona * Havasu Iceberg data lake storage layer: compatible with Apache Iceberg * Vtiles: a scalable PMTiles-style vector tile generator **WherobotsAI** - A scalable AI and machine learning engine: * Raster inference: a scalable raster inference engine in SQL and Python * Map matching: a scalable map matcher for snapping massive GPS traces to the road network **Compatible with Apache Sedona 1.6.0** ### Wherobots 1.2 This major release includes: **WherobotsDB** - A scalable spatial analytics database system, powered by Havasu data lake format: * Spatial query engine: compatible with Apache Sedona * Havasu Iceberg data lake storage layer: compatible with Apache Iceberg **Compatible with Apache Sedona 1.5.1** # Install Agent Skills Source: https://docs.wherobots.com/develop/agent-skills Install Wherobots Agent Skills to give AI assistants domain-specific knowledge about Wherobots workflows, APIs, and best practices. Public Preview **Agent Skills** are domain-specific knowledge files that give AI assistants structured context about Wherobots workflows, APIs, and best practices. With skills installed, your AI assistant produces more accurate commands, better interprets results, and handles multi-step operations more reliably. Without skills, the agent relies only on CLI help text and its general training data. With skills, it has structured context -- leading to fewer errors, less back-and-forth, and more reliable multi-step operations. If you use the [Wherobots VS Code Extension](/develop/agentic-tools) in **VS Code**, Agent Skills are included with the extension and available automatically -- no manual installation needed. In **Cursor**, other Code OSS editors, **Claude Code**, and other tools without the extension, skills must be installed manually using the commands below. See the [Agentic Tools Overview](/develop/agentic-tools) for a full breakdown of what each tool installs automatically. ## Before you start * An agentic terminal or AI-powered editor such as **OpenCode**, **Claude Code**, **Cursor**, or another tool with terminal access. * [Node.js](https://nodejs.org/) installed (required for `npx`). ## Install agent skills Install all Wherobots skills: ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` Or install a specific skill: ```bash theme={"system"} npx skills add wherobots/agent-skills --skill wherobots-usage ``` For more information on skills and the `skills` CLI, see the [Skills documentation](https://skills.sh/docs/cli). ## Available skills To see all available Wherobots skills, visit the [wherobots/agent-skills repository](https://github.com/wherobots/agent-skills). ## How skills work Skills are installed as `SKILL.md` files in your project or globally. When your AI assistant starts a session, it reads these files to gain structured context about: * **Wherobots APIs and endpoints** -- correct parameter names, expected payloads, and response formats. * **Spatial SQL patterns** -- common query structures, function signatures, and best practices for geospatial operations. * **Workflow patterns** -- recommended sequences for tasks like job submission, log streaming, and error recovery. This context helps the agent make fewer mistakes and resolve errors without manual intervention. ## Next steps Use the CLI with AI-powered terminals like Claude Code and OpenCode for natural language job management. Set up the Wherobots MCP Server for spatial data exploration and query generation. Install and configure the Wherobots CLI for terminal-based access. See which agentic components are installed automatically and which require manual setup. # Get Started with Agentic Development Source: https://docs.wherobots.com/develop/agentic-tools Pick your editor or terminal and set up Wherobots' AI-assisted geospatial development -- extension, MCP Server, Agent Skills, and CLI. Wherobots provides agentic components that bring AI-assisted geospatial development to your editor or terminal. What you need to install depends on your tool. Pick yours below to get started. ## Pick your tool Wherobots supports a variety of Code OSS-based editors and terminal-only tools. Full automatic setup. Extension installs MCP Server and Agent Skills for you. Extension + manual MCP Server and Agent Skills configuration. Terminal-only. MCP Server, Agent Skills, and CLI configured manually. Terminal-only. MCP Server, Agent Skills, and CLI configured manually. Desktop or web. MCP Server enabled from Claude's official connector Directory. Desktop or web. MCP Server configured as a Custom App. Terminal or desktop. MCP Server, Agent Skills, and CLI configured manually. Extension + manual MCP Server and Agent Skills configuration. Extension + manual MCP Server and Agent Skills configuration. Data science-focused Code OSS editor by Posit. Code OSS-based editor by Antigravity. AI-powered Code OSS editor by ByteDance. Freely-licensed community distribution of VS Code. Using a Code OSS editor not listed here? The setup process is the same as any of the editors above, just substitute your editor's CLI command. The extension is available from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). ## What each component does The [**Wherobots VS Code Extension**](https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit) turns Code OSS editors into a geospatial workspace with [notebook development](/develop/vscode-extension/notebooks), [job submission](/develop/vscode-extension/jobs), [data browsing](/develop/vscode-extension/integrate-your-data), and [workspace management](/develop/vscode-extension/workspaces). In VS Code, it also automatically configures the MCP Server and includes Agent Skills. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Setup by tool Every supported editor and terminal gets the same AI-assisted job submission and MCP features. What differs is how the MCP Server and Agent Skills are installed: the Wherobots extension configures them automatically in VS Code, while other tools require a one-time manual setup. Here's what you'll set up for each tool: | Tool | Wherobots Extension | Wherobots MCP Server | Wherobots Agent Skills | | ------------------ | :------------------ | :----------------------------- | :----------------------------- | | **VS Code** | Included | Included | Included | | **Cursor** | Included | Additional Setup
Required | Additional Setup
Required | | **Windsurf** | Included | Additional Setup
Required | Additional Setup
Required | | **Kiro** | Included | Additional Setup
Required | Additional Setup
Required | | **Other Code OSS** | Included | Additional Setup
Required | Additional Setup
Required | | **Claude Code** | N/A | Additional Setup
Required | Additional Setup
Required | | **OpenCode** | N/A | Additional Setup
Required | Additional Setup
Required | * **Included**: configured for you when the extension installs. * **Additional Setup Required**: you install or configure it yourself (see the tool's setup page). * **N/A**: Not applicable to the tool in its current form factor (e.g. no extension for terminal-only tools). # Set Up Wherobots in Antigravity Source: https://docs.wherobots.com/develop/agentic-tools/antigravity Install the Wherobots VS Code Extension in Antigravity and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview Draft **Antigravity** is a Code OSS-based editor. The Wherobots VS Code Extension installs but MCP Server and Agent Skills must be configured manually. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start * [Antigravity](https://antigravity.dev/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * An AI assistant extension installed in your editor (for AI-assisted features). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} antigravity --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). If Antigravity prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Configure it manually: Open the **Command Palette** ( + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux). 1. Type **MCP: Add Server** and select it. 2. Select **HTTP (HTTP or Server-Sent Events)** as the server type. 3. Enter the URL: `https://api.cloud.wherobots.com/mcp/` 4. Enter a name for the server (e.g., `wherobots-mcp-server`). Your `mcp.json` file opens automatically. Add a `headers` object with your Wherobots API key: ```json theme={"system"} "servers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "type": "http", "headers": { "x-api-key": "" } } } ``` Save the file. Open the **Command Palette** and select **Reload Window**. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Install Agent Skills [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Verify installation 1. Open your AI assistant's chat panel. 2. Select **Agent** as the chat mode (if available). 3. Ask a test question: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 4. If successful, the assistant will call `list_catalogs` and display your available tables. 5. Open the **Command Palette** and type **MCP: List Servers** to confirm the server appears. ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Set Up Wherobots in ChatGPT Source: https://docs.wherobots.com/develop/agentic-tools/chatgpt Configure the Wherobots MCP Server as a custom App in the ChatGPT desktop app or ChatGPT's web interface for AI-assisted geospatial development. Public Preview [**ChatGPT**](https://chatgpt.com/) is OpenAI's AI assistant, available as a [native desktop app](https://chatgpt.com/download) for macOS and Windows and a [browser-based app](https://chatgpt.com). Both support MCP integrations through **Apps**, allowing you to connect Wherobots tools directly. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * A [ChatGPT](https://chatgpt.com) account with an active paid plan (Plus, Pro, Business, or Enterprise). * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). * For the desktop flow: [ChatGPT Desktop](https://chatgpt.com/download) installed. ## Install and configure In ChatGPT, custom MCP servers are added as **Apps**. Each user creates the Wherobots App on their own account. The same steps work in ChatGPT on the web and ChatGPT Desktop. 1. In ChatGPT, go to [**Settings > Apps > Advanced settings**](https://chatgpt.com/#settings/Connectors/Advanced). 2. Enable **Developer mode**. This allows you to add custom MCP servers as Apps in ChatGPT. ChatGPT Developer mode toggle in Advanced settings 3. Go back to [**Settings > Apps**](https://chatgpt.com/#settings/Connectors). 4. Click **Create app**. ChatGPT Apps settings page with the Create app button visible In the **New App** form, enter: * **Name:** `wherobots` or a name of your choice (e.g. `Wherobots Geospatial Assistant`) * **Description** (optional): a short description, such as `AI-assisted geospatial development with Wherobots` * **MCP Server URL:** `https://api.cloud.wherobots.com/mcp/` * **Authentication:** `OAuth` Review the warning about custom MCP servers and tick **I understand and want to continue**, then save the app. ChatGPT New App form with Name, MCP Server URL, and OAuth Authentication fields 1. A new browser tab opens to the Wherobots sign-in page. 2. Sign in to Wherobots, select your Organization from the **Organization access** dropdown, and click **Allow access**. Wherobots Allow screen 3. Return to ChatGPT, go to [**Apps**](https://chatgpt.com/#settings/Connectors). **Wherobots** now appears under your **Enabled apps** with the `DEV` badge. ChatGPT Apps settings page with Wherobots app listed ## Verify installation Ask a question in ChatGPT: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` If configured correctly, ChatGPT will call the Wherobots MCP server (showing a tool such as `list_catalogs`) and return the catalogs available in your Organization. To make sure ChatGPT has the Wherobots MCP server app as context: 1. Use the Wherobots App in a conversation. 2. Open the **+** menu in the chat composer. 3. Click **... More**. 4. Enable **Wherobots** before sending your prompt. ChatGPT chat composer with Wherobots app enabled ## Next steps Common tasks, example prompts, and cost considerations for the MCP Server. Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation. Learn more about available skills and installation options. Understand when to use the MCP Server vs. the CLI. # Set Up Wherobots in Claude Code Source: https://docs.wherobots.com/develop/agentic-tools/claude-code Configure the Wherobots MCP Server, Agent Skills, and CLI in Claude Code for AI-assisted geospatial development from your terminal. Public Preview **Claude Code** is a terminal-based agentic tool by Anthropic. Unlike the VS Code extension, Claude Code requires separate installation of the MCP Server, Agent Skills, and CLI. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * [Claude Code](https://code.claude.com/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). * A Wherobots [API key](/get-started/wherobots-cloud/api-keys). * You will need a Wherobots API key to use the Wherobots CLI with the MCP server and Claude Code. ## Install and configure 1. In a terminal, run the following command, replacing the placeholder with your preferred server name: ```shell theme={"system"} claude mcp add --transport http https://api.cloud.wherobots.com/mcp/ --scope user ``` The `--scope user` flag makes the server available to all your Claude Code agents. For more information on scope options, see the [Claude Code documentation](https://code.claude.com/docs/en/mcp#scope-hierarchy-and-precedence). When you first use the MCP server, a browser window opens for you to sign in to Wherobots and select your organization. 2. Restart Claude Code after adding the server. For more information on downloading, installing, and using Claude Code, see [Claude Code overview](https://code.claude.com/docs/en/overview) and [Quickstart](https://code.claude.com/docs/en/quickstart) in the Claude Code Documentation. [Agent Skills](/develop/agent-skills) give your AI assistant structured context about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` The [Wherobots CLI](/develop/cli) wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. 1. Run the following command to install the CLI: ```bash theme={"system"} curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash ``` 2. Set your API key: ```bash theme={"system"} export WHEROBOTS_API_KEY='' ``` 3. Verify the connection: ```bash theme={"system"} wherobots --tree ``` ## Verify installation Ask a question in Claude Code: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` If configured correctly, Claude Code will call the Wherobots MCP server (showing a tool such as `list_catalogs`) and return the catalogs available in your Organization. ## Next steps Common tasks, example prompts, and cost considerations for the MCP Server. Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation. Learn more about available skills and installation options. Use the CLI with Claude Code for natural language job management. Submit jobs, stream logs, and access the full Wherobots API. Understand when to use the MCP Server vs. the CLI. # Add Wherobots as an Official Connector in Claude Source: https://docs.wherobots.com/develop/agentic-tools/claude-official-connector Enable the official Wherobots connector in Claude Desktop or Claude on the web for AI-assisted geospatial development. Public Preview **Claude** is Anthropic's AI assistant, available as a [native desktop app](https://claude.ai/download) for macOS and Windows and a [browser-based app](https://claude.ai). Both support MCP integrations through Claude's connector Directory, where Wherobots can be added as an official connector. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * A [Claude](https://claude.ai) account with an active paid [subscription](https://www.anthropic.com/pricing). * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). * For the desktop flow: [Claude Desktop](https://claude.ai/download) installed. * If you are on Claude's **Team** or **Enterprise** plan, ask your Claude plan's **Owner** or **Primary Owner** to enable connectors for your Claude organization. * Each user still must authenticate individually after the Connector is enabled. * For more information, see the [Wherobots connector does not appear in the Directory](#the-wherobots-connector-does-not-appear-in-the-directory) section of this page or [Use Connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_bbcedba6ca). ## Install and configure When Wherobots is available in your Claude Directory as an official connector, each user can enable it from their own account. The same steps work in Claude on the web and Claude Desktop. On **Team** and **Enterprise** plans, an Owner or Primary Owner may need to enable connectors for the organization before you can add Wherobots. If the connector does not appear or you cannot enable it, ask your team's owner to enable it for the organization. Each user still authenticates individually after it is enabled. For more information, see [Use Connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_bbcedba6ca). 1. Open the connectors page: * **Web:** Go to [https://claude.ai/directory](https://claude.ai/directory). * **Desktop:** Open **Customize > Connectors > Browse** from the left sidebar. 1. In the **Directory** modal, search for `wherobots`. 2. Select the official **Wherobots Spatial AI Assistant**. 3. Click **+** to enable the Connector in your Claude Organization. 1. A new browser tab will open to the Wherobots sign-in page. 2. Sign in to Wherobots, select your Organization from the **Organization access** dropdown, and click **Allow access**. Wherobots OAuth consent screen prompting Claude access for the selected Organization 3. Return to Claude. The **Wherobots** connector will appear in the **Web** section of the **Connectors** page. You have successfully connected Wherobots to Claude! You can now use the Wherobots connector in your Claude conversations and agentic workflows. ## Verify installation Ask a question in Claude: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` If configured correctly, Claude calls the Wherobots MCP server (showing a tool such as `list_catalogs`) and returns the catalogs available in your Organization. ## Troubleshooting The following section details how to troubleshoot the installation of the Wherobots Spatial AI Assistant in Claude. ### The Wherobots connector does not appear in the Directory On **Team** and **Enterprise** plans, connectors must be enabled at the organization level before individual users can add them. If you search the **Directory** and Wherobots does not appear—or the option to add it is unavailable—ask your team's Owner or Primary Owner to enable connectors for the organization. Once enabled at the org level, each user still completes the [Install and configure](#install-and-configure) steps and authenticates individually. See [Use Connectors to extend Claude's capabilities](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities#h_bbcedba6ca) for details on connector permissions. ### Sign-in or OAuth fails If the consent screen does not complete or Claude reports it cannot connect: * Confirm you have a stable internet connection and an active Wherobots Account in a Professional, Innovation, or Enterprise Organization. * Make sure you selected the correct Organization from the **Organization access** dropdown before clicking **Allow access**. * On the Claude **Connectors** page, disconnect the Wherobots connector and reconnect to restart the OAuth flow. ### Claude does not call the Wherobots MCP server If Claude answers without invoking a Wherobots tool (such as `list_catalogs`): * Confirm the **Wherobots** connector is enabled on the **Connectors** page and toggled on for the conversation. * Start a new conversation and ask an explicitly geospatial question so Claude selects the connector: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` ## Next steps Common tasks, example prompts, and cost considerations for the MCP Server. Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation. Learn more about available skills and installation options. Understand when to use the MCP Server vs. the CLI. # Set Up Wherobots in Codex Source: https://docs.wherobots.com/develop/agentic-tools/codex Configure the Wherobots MCP Server, Agent Skills, and CLI in OpenAI Codex — in the desktop app or terminal — for AI-assisted geospatial development. Public Preview [**Codex**](https://developers.openai.com/codex) is OpenAI's agentic coding tool, available as both a [terminal CLI](https://developers.openai.com/codex/cli) and a [native desktop app](https://developers.openai.com/codex/app). Unlike the VS Code extension flow, Codex requires separate installation of the MCP Server, Agent Skills, and CLI. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * Either the [Codex CLI](https://developers.openai.com/codex/cli) (run in a modern terminal emulator) or the [Codex desktop app](https://developers.openai.com/codex/app) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). * An API key for the Wherobots CLI. For more information, see [API Keys](/get-started/wherobots-cloud/api-keys). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install and configure Codex stores MCP server entries in `~/.codex/config.toml`. The Codex CLI and the Codex desktop app share the same config file, so the following steps apply to both interfaces: 1. Open `~/.codex/config.toml` in your editor (create the file if it does not exist): Remote HTTP servers like Wherobots must be added by editing this file directly — `codex mcp add` only supports local stdio servers. * Add a `[mcp_servers.]` section. * Replace `` with your preferred name for the Wherobots MCP server (e.g. `wherobots-mcp-server`): ```toml theme={"system"} [mcp_servers.] url = "https://api.cloud.wherobots.com/mcp/" ``` 2. Save the file, then start the OAuth flow: ```shell theme={"system"} codex mcp login ``` A browser window opens for you to sign in to Wherobots. Select your Organization and click **Allow access**. Alternatively, the terminal will display a URL you can copy and paste into any browser to complete the login. 3. Restart Codex so it picks up the new MCP server. Skip `codex mcp login` and add an `X-API-Key` header to the server entry: ```toml theme={"system"} [mcp_servers.] url = "https://api.cloud.wherobots.com/mcp/" http_headers = { "X-API-Key" = "" } ``` For more information on downloading, installing, and using Codex, see the [Codex documentation](https://developers.openai.com/codex/cli). [Agent Skills](/develop/agent-skills) give your AI assistant structured context about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` The [Wherobots CLI](/develop/cli) wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ```bash theme={"system"} curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash ``` Set your API key as an environment variable: ```bash theme={"system"} export WHEROBOTS_API_KEY='' ``` Verify the connection: ```bash theme={"system"} wherobots --tree ``` ## Verify installation To confirm the installation, ask a question in Codex: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` If configured correctly, Codex will call the Wherobots MCP server and return the catalogs available in your [Wherobots Data Hub](https://cloud.wherobots.com/data-hub). Additionally, you can verify that the Agent Skills were installed correctly, if the **Wherobots MCP Server** is listed as a **Source** within Codex as it processes your query. Codex agentic verify ## Next steps Common tasks, example prompts, and cost considerations for the MCP Server. Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation. Learn more about available skills and installation options. Use the CLI with Codex for natural language job management. Submit jobs, stream logs, and access the full Wherobots API. Understand when to use the MCP Server vs. the CLI. # Set Up Wherobots in Cursor Source: https://docs.wherobots.com/develop/agentic-tools/cursor Install the Wherobots VS Code Extension in Cursor and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview [**Cursor**](https://cursor.com/product) by Anysphere is a Code OSS-based editor with built-in AI features. The Wherobots extension installs from the Open VSX Registry, but the MCP Server and Agent Skills must be configured manually. Cursor uses its own `mcp.json` schema (`mcpServers`, not `servers`), so follow the Cursor-specific steps below to install the MCP Server and Agent Skills. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * [Cursor](https://www.cursor.com/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} cursor --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). The Wherobots extension depends on the Jupyter extension from `ms-toolsai`. If Cursor prompts that it cannot activate the extension because of a missing Jupyter dependency, click **Install and Reload**. Cursor dialog prompting to install the Jupyter dependency and reload ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ### Apply the extension to all profiles (optional) If you use multiple Cursor profiles, right-click the **Wherobots - Spatial AI Coding Assistant** entry in the Extensions view and select **Apply Extension to all Profiles** so the extension is available in every profile. Cursor extension context menu with Apply Extension to all Profiles highlighted ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Cursor expects a project-level `.cursor/mcp.json` file with an `mcpServers` object. Open the **Command Palette** ( + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux), type **Cursor Settings: Tools & MCPs**, and press Enter. Under **Installed MCP Servers**, click **Add Custom MCP**. Cursor opens (or creates) `.cursor/mcp.json` in your project root. Cursor Settings Tools & MCPs empty state with Add Custom MCP button Paste the following into `.cursor/mcp.json`, then save the file: ```json theme={"system"} { "mcpServers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/" } } } ``` When you first use the MCP server, Cursor initiates an OAuth flow — a browser window opens for you to sign in to Wherobots and select your organization. Add a `headers` object with your [Wherobots API key](/get-started/wherobots-cloud/api-keys/): ```json theme={"system"} { "mcpServers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "headers": { "x-api-key": "" } } } } ``` Cursor requires the top-level key `mcpServers` (plural, camel-case) and **does not** accept the VS Code–style `servers` key or the `"type": "http"` field. If the file has either, Cursor will show *"Invalid config: mcpServers must be an object"* in Settings. Cursor editing .cursor/mcp.json 1. Open the **Command Palette** and select **Developer: Reload Window**. 2. Return to **Cursor Settings > Tools & MCPs** and confirm that `wherobots-mcp-server` is listed, has a green status dot, and lists its tools (for example, `list_catalogs_tool`, `list_tables_tool`, `describe_table_tool`, `execute_query_tool`, `search_documentation_tool`) plus prompts and a `get_version` resource. wherobots-mcp-server enabled in Cursor Settings Tools & MCPs The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Install Agent Skills [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. The Wherobots skill pack is distributed via the [skills CLI](https://skills.sh/). From a terminal in your project root, run: ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` The installer clones the Wherobots skills repository and launches an interactive wizard. When prompted with **Select skills to install**, press Space to toggle each skill and Enter to confirm. Select all three: * `wherobots-develop` — guidance for writing Wherobots jobs and using the SDK/CLI. * `wherobots-explore` — catalog discovery and spatial query generation via the MCP server. * `wherobots-usage` — interface decision matrix, auth setup, and scheduled-job patterns. skills CLI select skills prompt On the **Which agents do you want to install to?** screen, make sure **Cursor** is selected under **Universal** (it is included by default). You can optionally add other agents from the **Additional agents** list (for example, Claude Code at `~/.claude/skills`). Press Enter to continue. skills CLI agent selection prompt showing Cursor in the Universal list The installer prints an installation summary and security risk assessments (Gen, Socket, Snyk). When prompted **Proceed with installation?**, type `Yes` and press Enter. ## Verify your setup 1. Open a **New Agent** chat in Cursor (the chat panel on the right). 2. Confirm **Agent** is selected as the chat mode. 3. Ask a test question, for example: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 4. If everything is configured, Cursor's agent calls `search_documentation_tool`, `list_catalogs_tool`, `list_databases_tool`, and `list_tables_tool` on `wherobots-mcp-server` and returns the catalogs, databases, and tables in your Organization. Cursor agent listing tables in wherobots_pro_data using MCP tools 5. Re-open **Cursor Settings → Tools & MCPs** and confirm `wherobots-mcp-server` shows a green dot with all tools enabled. ## Pin the extension for easy access If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Troubleshooting ### `Invalid config: mcpServers must be an object` or `JSON syntax error` Cursor validates `.cursor/mcp.json` against its own schema and will display these errors in **Cursor Settings → Tools & MCPs** when the file is malformed. Common causes: * Missing the outer `{ ... }` wrapper around the config — the JSON parser fails with *"End of file expected."* * Using the VS Code key `"servers"` instead of Cursor's `"mcpServers"`. * Including a `"type": "http"` field — Cursor does not use it. Re-paste the snippet from [Configure the MCP Server](#configure-the-mcp-server) exactly as shown, save the file, and reload the window. ## Next steps Explore the following resources to get the most out of Wherobots in Cursor: Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Set Up Wherobots in Kiro Source: https://docs.wherobots.com/develop/agentic-tools/kiro Install the Wherobots VS Code Extension in Kiro and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview [**Kiro**](https://kiro.dev/) by Amazon Web Services is a Code OSS-based editor with spec-driven AI development. The Wherobots extension installs from the Open VSX Registry, but MCP support must be enabled in Kiro's settings before the server will connect, and the MCP config file must use Kiro's `mcpServers` schema. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## What you'll do Here's a high-level overview of the steps to set up Wherobots in Kiro: Install the Wherobots extension and sign in to Wherobots Cloud. [Jump to section](#install-the-extension). Turn on MCP in Kiro's settings so the server can connect. [Jump to section](#enable-mcp-support). Add the Wherobots MCP server to `mcp.json`. [Jump to section](#configure-the-mcp-server). Give your AI assistant Wherobots-specific knowledge. [Jump to section](#install-agent-skills). Confirm the setup with a test query. [Jump to section](#verify-your-setup). ## Before you start Prior to installing the Wherobots VS Code extension, make sure you have: * [Kiro](https://kiro.dev/) installed. * For more information on Kiro Plans see [Kiro Pricing](https://kiro.dev/pricing/). * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. * For more information, see [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} kiro --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. If Kiro prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots`. You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## Enable MCP support Kiro requires MCP to be explicitly enabled before it will connect to any MCP server. Press + , on macOS or Ctrl + , on Windows/Linux to open **Settings**. Make sure the following are enabled: * `wherobotsjobsubmit.mcpServerEnabled` * `kiroAgent.configureMCP` Kiro Settings panel with the Wherobots MCP server and job submission settings enabled In Kiro's **Command Palette**, search for `kiro: open MCP Config`. Kiro Settings with MCP enabled dropdown ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Kiro stores MCP configuration in `mcp.json` using a `mcpServers` object. Choose the appropriate level for your use case: | Config level | File path & When to use | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **User Config** | `~/.kiro/settings/mcp.json` — Applies to every Kiro workspace; use when you want the Wherobots MCP server available globally. | | **Workspace Config** | `.kiro/settings/mcp.json` (project root) — Applies only to the current workspace; use when projects need different API keys or server configurations. | The steps below use the **User Config** so the server is available in all workspaces. To use Workspace Config instead, create `.kiro/settings/mcp.json` in your project root with the same content. In the same MCP Settings view, click **Open User MCP Config (JSON)**. Kiro opens `~/.kiro/settings/mcp.json`. You can also open it via the **Command Palette** ( + Shift + P) by typing **Kiro: Open User MCP Config (JSON)**. Kiro MCP config editor showing User Config and Workspace Config tabs 1. Copy and paste the following snippet into your `mcp.json`, replacing `YOUR_WHEROBOTS_API_KEY` with your [Wherobots API key](/get-started/wherobots-cloud/api-keys/): If the file already contains other servers, add the new entry alongside them. ```json wrap theme={"system"} { "mcpServers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "headers": { "x-api-key": "YOUR_WHEROBOTS_API_KEY" } } } } ``` Kiro requires the top-level key `mcpServers` and **does not** accept the VS Code-style `servers` key or the `"type": "http"` field. Using either will produce an *"Error loading powers config: Unexpected token"* message in the Output panel. 2. Save the file. Kiro automatically detects the change and may add `disabled`, `autoApprove`, and `disabledTools` fields to the entry. 1. Open the **Output** panel ( + Shift + U) 2. Look for the following message in the **Kiro - MCP Logs** output stream: ```sh wrap theme={"system"} [info] [wherobots-mcp-server] Successfully connected and synced tools and resources for MCP server ``` If you see this message, the server is connected and ready to use. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Agent Skills The Wherobots [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. Install all three Wherobots skills for comprehensive AI assistance across your Wherobots development workflow. These Skills enable your AI assistant to provide accurate, Wherobots-specific guidance in chat and notebooks. | Skill | Purpose | | ------------------- | ------------------------------------------------------------------ | | `wherobots-develop` | Guidance for writing Wherobots jobs and using the SDK/CLI. | | `wherobots-explore` | Catalog discovery and spatial query generation via the MCP server. | | `wherobots-usage` | Interface decision matrix, auth setup, and scheduled-job patterns. | ### Import Agent Skills Kiro can import skills directly from GitHub through the **Agent Steering & Skills** panel in the sidebar.
  1. Click the Kiro logo Kiro icon in the Activity Bar to open the sidebar.
  2. Open the AGENT STEERING & SKILLS section.
  3. Click the + button to add a new skill.
  4. Kiro Agent Steering & Skills section with + button to add a new skill highlighted
1. Type **Agent Skills** in the search bar that appears. 2. Select either **Global agent skills** or Project-specific agent skills from the dropdown. Kiro Agent Steering & Skills section with search bar for Agent Skills highlighted 3. Click **Import skill from GitHub**. Kiro import skill dialog with Import skill from GitHub option highlighted 4. This opens a dialog where you can paste the URL of the skill's GitHub repository. Kiro dialog prompting for a GitHub repository URL to import a skill 1. For each URL below, hover over the URL and click on the right-hand side to copy the URL to your clipboard. ```sh wrap theme={"system"} https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-develop ``` ```sh wrap theme={"system"} https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-explore ``` ```sh wrap theme={"system"} https://github.com/wherobots/agent-skills/tree/main/.agents/skills/wherobots-usage ``` 2. Paste the URL into Kiro's import dialog and press Enter. After each import, Kiro downloads the `SKILL.md` file and adds the skill to the **AGENT STEERING & SKILLS** section in the sidebar. We recommend installing **all three skills** to get the full benefits of AI-assisted development with Wherobots. All three skills should appear under **AGENT STEERING & SKILLS** in the sidebar. Kiro sidebar with all three Wherobots skills installed under Agent Steering & Skills
## Verify your setup 1. Check the **MCP SERVERS** section in Kiro's sidebar (left panel). You should see `wherobots` with **Connected (8 tools)** and a list of tools including `list_catalogs_tool`, `list_tables_tool`, `describe_table_tool`, `execute_query_tool`, and `search_documentation_tool`. Kiro sidebar showing wherobots MCP server connected with 8 tools 2. Open a **New Session** chat panel. 3. Ask a test question, for example: > List the catalogs I have access to in Wherobots 4. Kiro's agent calls `list_catalogs_tool` on the `wherobots` MCP server. You may be prompted to **Trust** or **Run** the tool call. Kiro chat calling list_catalogs_tool via MCP 5. If successful, the agent returns your available catalogs, which includes `wherobots_open_data`, `wherobots_pro_data` (for Professional, Innovation, and Enterprise Organizations), and any private catalogs in your Organization. ## Pin the extension for easy access If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Kiro Activity Bar ## Troubleshooting ### `MCP: Browse MCP Servers` results in an error Kiro does not implement the VS Code `workbench.mcp.browseServers` command. Running **MCP: Browse MCP Servers** from the Command Palette will display *"command 'workbench.mcp.browseServers' not found"*. Kiro error dialog showing the workbench.mcp.browseServers command not found This does **not** mean the MCP server is broken. To verify the server is working: * Check the **MCP SERVERS** section in Kiro's sidebar for a green **Connected** status. * Check the **Output** panel → **Kiro - MCP Logs** for the "Successfully connected" message. * Test the server directly in chat by asking a question like: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` ### `Error loading powers config: Unexpected token` This error appears in the Output panel and as a notification when `mcp.json` contains invalid JSON or uses the wrong schema. Common causes: * Using the VS Code key `"servers"` instead of Kiro's `"mcpServers"`. * Including a `"type": "http"` field. Kiro does not use this field and it will cause an error. * Missing the outer `{ ... }` wrapper or a trailing comma. Re-paste the snippet from [Configure the MCP Server](#configure-the-mcp-server) exactly as shown, save the file, and check the Output panel for a successful connection. ### `MCP is currently disabled` If you see a banner saying *"MCP is currently disabled. To start using MCP, please enable it in the settings."*, review the [Enable MCP support](#enable-mcp-support) section above to ensure MCP is turned on in Kiro's settings. ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Set Up Wherobots in OpenCode Source: https://docs.wherobots.com/develop/agentic-tools/opencode Configure the Wherobots MCP Server, Agent Skills, and CLI in OpenCode for AI-assisted geospatial development from your terminal. Public Preview [**OpenCode**](https://opencode.ai/) is an open-source terminal-based agentic coding tool. Unlike the VS Code extension, OpenCode requires separate installation of the MCP Server, Agent Skills, and CLI. The following instructions work for both the **Open Code Agentic Terminal** and the **OpenCode desktop application**. For more information on OpenCode, see the [OpenCode documentation](https://opencode.ai/docs/). ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * [OpenCode](https://opencode.ai/) installed with a [modern terminal emulator](https://opencode.ai/docs/#prerequisites). * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). * A Wherobots API key. For more information, see [API Keys](/get-started/wherobots-cloud/api-keys). * You will use this to install the Wherobots CLI, which is recommended for accessing Wherobots features in OpenCode. * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install Wherobots MCP Server in OpenCode These steps connect OpenCode to the Wherobots MCP Server, giving your AI assistant access to your Wherobots Organization's catalogs, datasets, and tools. Choose one of two methods to add the Wherobots MCP server to OpenCode. 1. In your terminal, start the OpenCode MCP setup wizard: ```bash theme={"system"} opencode mcp add ``` 2. Respond to each prompt as follows: | Prompt | Value | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Location | `Global` or `Local` | | Enter MCP server name | `YOUR-WHEROBOTS-MCP-SERVER-NAME`

Replace with your desired name for the Wherobots MCP server | | Select MCP server type | `Remote` | | Enter MCP server URL | `https://api.cloud.wherobots.com/mcp/` | | Does this server
require OAuth authentication? | `Yes` | | Do you have a pre-registered
client ID? | `No` | Choose the **Global** location to make the server available in all your projects, or **Local** to keep it separate from other projects. OpenCode writes the entry to `~/.config/opencode/opencode.jsonc` and prints `MCP server "YOUR-WHEROBOTS-MCP-SERVER-NAME" added successfully`. Terminal showing the completed opencode mcp add wizard prompts 3. Authenticate the new server with OAuth, replacing `` with your desired name for the Wherobots MCP server (e.g. `wherobots-mcp-server-opencode`): ```bash theme={"system"} opencode mcp auth ``` This opens a browser window prompting you to log in to your Wherobots account and authorize OpenCode to access your account information. 4. In the browser, select the Wherobots Organization that you want OpenCode to access, then click **Allow Access**. Wherobots OAuth consent screen prompting OpenCode access for the selected Organization 5. Once the browser shows **Authorization Successful**, close the tab and return to your terminal. OpenCode prints `Authentication successful!`. Browser page confirming Authorization Successful 6. Verify the server is connected: ```bash theme={"system"} opencode mcp list ``` You should see something similar to the following, `YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth)` along with the server URL. ```bash theme={"system"} ┌ MCP Servers │ ● ✓ YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth) │ https://api.cloud.wherobots.com/mcp/ │ │ └ 1 server(s) ```
1. Open your OpenCode config file in your editor — the path determines the scope (create the file if it does not exist): * **Global** (available in all projects): `~/.config/opencode/opencode.jsonc` (or `~/.config/opencode/opencode.json`). * **Local** (project-specific): `opencode.jsonc` (or `opencode.json`) in your project root. 2. Add a `YOUR-WHEROBOTS-MCP-SERVER-NAME` entry under `mcp`, replacing `YOUR-WHEROBOTS-MCP-SERVER-NAME` with your desired name for the Wherobots MCP server (e.g. `wherobots-mcp-server-opencode`): ```jsonc theme={"system"} { "$schema": "https://opencode.ai/config.json", "mcp": { "YOUR-WHEROBOTS-MCP-SERVER-NAME": { "type": "remote", "url": "https://api.cloud.wherobots.com/mcp/", "oauth": {} } } } ``` 3. Save the file, then start the OAuth flow: ```bash theme={"system"} opencode mcp auth YOUR-WHEROBOTS-MCP-SERVER-NAME ``` Sign in to Wherobots in the browser, select your Organization, and click **Allow Access**. Wherobots OAuth consent screen prompting OpenCode access for the selected Organization The browser shows **Authorization Successful**. Browser page confirming Authorization Successful 4. In the terminal, verify the server is connected: ```bash theme={"system"} opencode mcp list ``` You will see something similar to the following, `YOUR-WHEROBOTS-MCP-SERVER-NAME connected (OAuth)` along with the server URL. ```bash theme={"system"} ┌ MCP Servers │ ● ✓ wherobots-opencode-oauth connected (OAuth) │ https://api.cloud.wherobots.com/mcp/ │ │ └ 1 server(s) ```
For more information on downloading, installing, and using OpenCode, see [Install](https://opencode.ai/docs/#install) and [Usage](https://opencode.ai/docs/#usage) sections in the OpenCode documentation.
[Agent Skills](/develop/agent-skills) give your AI assistant structured context about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` The [Wherobots CLI](/develop/cli) wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ```bash theme={"system"} curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash ``` Set your API key as an environment variable: ```bash theme={"system"} export WHEROBOTS_API_KEY='' ``` Verify the connection: ```bash theme={"system"} wherobots --tree ```
## Verify installation The following steps confirm that OpenCode is properly connected to the Wherobots MCP server and that your AI assistant can access your Wherobots data and tools. ### Test the MCP Server connection To confirm that OpenCode can communicate with the Wherobots MCP server, ask a question in your AI assistant within OpenCode: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` If configured correctly, OpenCode will call the Wherobots MCP server (showing a tool such as `list_catalogs`) and return the catalogs available in your Organization. ## Next steps Explore the following resources to learn how to use Wherobots in OpenCode and get ideas for using your AI assistant to automate geospatial workflows. Common tasks, example prompts, and cost considerations for the MCP Server. Watch the MCP Server automate catalog discovery, spatial queries, and notebook generation. Learn more about available skills and installation options. Use the CLI with OpenCode for natural language job management. Submit jobs, stream logs, and access the full Wherobots API. Understand when to use the MCP Server vs. the CLI. # Set Up Wherobots in Positron Source: https://docs.wherobots.com/develop/agentic-tools/positron Install the Wherobots VS Code Extension in Positron and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview Draft **Positron** by Posit is a Code OSS-based editor designed for data science workflows. The Wherobots VS Code Extension installs but MCP Server and Agent Skills must be configured manually. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start * [Positron](https://positron.posit.co/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * An AI assistant extension installed in your editor (for AI-assisted features). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} positron --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). If Positron prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Configure it manually: Open the **Command Palette** ( + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux). 1. Type **MCP: Add Server** and select it. 2. Select **HTTP (HTTP or Server-Sent Events)** as the server type. 3. Enter the URL: `https://api.cloud.wherobots.com/mcp/` 4. Enter a name for the server (e.g., `wherobots-mcp-server`). Your `mcp.json` file opens automatically. Add a `headers` object with your Wherobots API key: ```json theme={"system"} "servers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "type": "http", "headers": { "x-api-key": "" } } } ``` Save the file. Open the **Command Palette** and select **Reload Window**. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Install Agent Skills [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Verify installation 1. Open your AI assistant's chat panel. 2. Select **Agent** as the chat mode (if available). 3. Ask a test question: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 4. If successful, the assistant will call `list_catalogs` and display your available tables. 5. Open the **Command Palette** and type **MCP: List Servers** to confirm the server appears. ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Set Up Wherobots in Trae Source: https://docs.wherobots.com/develop/agentic-tools/trae Install the Wherobots VS Code Extension in Trae and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview Draft **Trae** by ByteDance is a Code OSS-based editor with AI-powered development features. The Wherobots VS Code Extension installs but MCP Server and Agent Skills must be configured manually. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start * [Trae](https://www.trae.ai/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * An AI assistant extension installed in your editor (for AI-assisted features). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} trae --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). If Trae prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Configure it manually: Open the **Command Palette** ( + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux). 1. Type **MCP: Add Server** and select it. 2. Select **HTTP (HTTP or Server-Sent Events)** as the server type. 3. Enter the URL: `https://api.cloud.wherobots.com/mcp/` 4. Enter a name for the server (e.g., `wherobots-mcp-server`). Your `mcp.json` file opens automatically. Add a `headers` object with your Wherobots API key: ```json theme={"system"} "servers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "type": "http", "headers": { "x-api-key": "" } } } ``` Save the file. Open the **Command Palette** and select **Reload Window**. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Install Agent Skills [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Verify installation 1. Open your AI assistant's chat panel. 2. Select **Agent** as the chat mode (if available). 3. Ask a test question: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 4. If successful, the assistant will call `list_catalogs` and display your available tables. 5. Open the **Command Palette** and type **MCP: List Servers** to confirm the server appears. ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Set Up Wherobots in VS Code Source: https://docs.wherobots.com/develop/agentic-tools/vscode Install the Wherobots VS Code Extension in Visual Studio Code. The extension automatically configures the MCP Server and includes Agent Skills. Public Preview **Visual Studio Code** by Microsoft is a Code OSS-based editor. In VS Code, the [Wherobots VS Code Extension](https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit) automatically configures the **MCP Server** and includes **Agent Skills**, so no separate MCP or Skills setup is required. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start The following prerequisites are required: * [Visual Studio Code](https://code.visualstudio.com/) version 1.85 or later. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * Active [GitHub Copilot](https://github.com/features/copilot) subscription (for AI-assisted features). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} code --install-extension wherobots.wherobotsjobsubmit ``` Or install from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=wherobots.wherobotsjobsubmit). If VS Code prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## MCP Server and Agent Skills **Automatic:** The extension automatically configures the [Wherobots MCP Server](/develop/mcp/mcp-server-overview) and includes [Agent Skills](/develop/agent-skills) in VS Code. No manual setup is needed. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Verify installation 1. Open **GitHub Copilot Chat** via **View > Chat**. 2. Select **Agent** as the chat mode from the dropdown at the top of the chat panel. Screenshot showing the Agent mode dropdown 3. Select an advanced model (Claude Opus, Claude Sonnet, GPT Codex, or Gemini Pro) for best results. 4. Ask a test question: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 5. If successful, the assistant will confirm it is using the Wherobots MCP server (showing `Ran list_catalogs` or a similar tool) and display your available tables. Screenshot showing the MCP server catalogs response ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute with GitHub Copilot. Submit Python scripts as Wherobots job runs from your editor. Create, start, stop, and manage notebook workspaces. Common tasks, example prompts, and cost considerations for the MCP Server. Submit jobs and access the full Wherobots API from your terminal. # Set Up Wherobots in VS Codium Source: https://docs.wherobots.com/develop/agentic-tools/vscodium Install the Wherobots VS Code Extension in VS Codium and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview Draft **VS Codium** is a community-driven, freely-licensed distribution of VS Code. The Wherobots VS Code Extension installs but MCP Server and Agent Skills must be configured manually. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start * [VS Codium](https://vscodium.com/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * An AI assistant extension installed in your editor (for AI-assisted features). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} codium --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). If VS Codium prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Configure it manually: Open the **Command Palette** ( + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux). 1. Type **MCP: Add Server** and select it. 2. Select **HTTP (HTTP or Server-Sent Events)** as the server type. 3. Enter the URL: `https://api.cloud.wherobots.com/mcp/` 4. Enter a name for the server (e.g., `wherobots-mcp-server`). Your `mcp.json` file opens automatically. Add a `headers` object with your Wherobots API key: ```json theme={"system"} "servers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "type": "http", "headers": { "x-api-key": "" } } } ``` Save the file. Open the **Command Palette** and select **Reload Window**. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Install Agent Skills [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Verify installation 1. Open your AI assistant's chat panel. 2. Select **Agent** as the chat mode (if available). 3. Ask a test question: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 4. If successful, the assistant will call `list_catalogs` and display your available tables. 5. Open the **Command Palette** and type **MCP: List Servers** to confirm the server appears. ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Set Up Wherobots in Windsurf Source: https://docs.wherobots.com/develop/agentic-tools/windsurf Install the Wherobots VS Code Extension in Windsurf and manually configure the MCP Server and Agent Skills for AI-assisted geospatial development. Public Preview Draft **Windsurf** by Cognition AI is a Code OSS-based editor with AI-powered development features. The extension installs but MCP Server and Agent Skills must be configured manually. ## Component Overview Wherobots' Agentic Tools consist of the following components that work together to provide our agentic experience: Connects your AI assistant to Wherobots Cloud for catalog exploration, Spatial SQL generation, and query execution. Gives your AI assistant domain-specific Wherobots knowledge for more accurate commands and fewer errors. Wraps the full Wherobots API into a single binary for job submission, log streaming, and automation. ## Why use Wherobots' agentic tools? Wherobots' agentic tools connect your AI assistant to Wherobots Cloud and your local development environment so you can interact with your spatial data, catalogs, and jobs in a more intuitive way. The MCP Server connects your AI assistant to Wherobots Cloud so you can browse catalogs, databases, and table schemas (including Overture Maps and your own datasets) by asking questions in plain language instead of navigating the console. Describe a geospatial task (e.g. "find buildings within 500m of this point") and the MCP Server returns optimized Spatial SQL using WherobotsDB's ST functions, spatial joins, and indexing patterns. Use the CLI or the extension to submit Spark job runs, stream logs in real time, check resource metrics, and cancel jobs without leaving your editor or terminal. Agent Skills teach your AI assistant Wherobots-specific APIs, query patterns, and workflow sequences so it produces correct `wherobots` CLI commands, valid MCP tool calls, and accurate notebook code on the first try. ## Before you start * [Windsurf](https://windsurf.com/) installed. * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). **Organization Availability:** Available to all Wherobots Organization Editions (Professional, Innovation, and Enterprise). * Active Windsurf AI subscription or your editor's equivalent AI assistant (for AI-assisted features). * [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your system (required for installing Agent Skills via `npx`). ## Install the extension Run the following command in your terminal: ```bash theme={"system"} windsurf --install-extension Wherobots.wherobotsjobsubmit ``` Or install from the [Open VSX Registry](https://open-vsx.org/extension/Wherobots/wherobotsjobsubmit). If Windsurf prompts you to install a missing dependency extension (e.g., Jupyter), click **Install and Reload**. ### Configure the extension After installation, connect to Wherobots Cloud by signing in from your browser (OAuth) or setting an API key. These steps apply to VS Code, Cursor, Windsurf, [Kiro](https://kiro.dev/), Positron, Antigravity, Trae, VS Codium, and other Code OSS editors. All use the same Command Palette and extension settings. To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Click `Wherobots: Sign In` to start the OAuth flow. A browser window opens for you to sign in to Wherobots and select your Organization; when you're done, return to your editor. To sign out at any time, run `Wherobots: Sign Out` from the Command Palette. Sign in through OAuth **Prefer an API key?** Click `Wherobots: Set API Key` and enter your existing or newly created [Wherobots API key](/get-started/wherobots-cloud/api-keys/) when prompted, then press Enter. If you don't have a key yet, click `Wherobots: Generate API Key on Wherobots Cloud` to create one first. ### Verify the installation To confirm the extension is installed and configured correctly: To open the **Command Palette**, click the search bar at the top of your editor and type `>wherobots:`. Command Palette You can also press + Shift + P on Mac, Ctrl + Shift + P on Windows/Linux to open the **Command Palette**. Type **Wherobots** to see the available extension commands. At this point, you should see commands, including: * `Wherobots: Sign In` * `Wherobots: Sign Out` * `Wherobots: Set API Key` * `Wherobots: Create Workspace` * `Wherobots: Submit Job` * `Wherobots: Refresh Workspaces` * `Wherobots: Open Settings` * `Wherobots: Install Jupyter Extension` ## Configure the MCP Server The [Wherobots MCP Server](/develop/mcp/mcp-server-overview) enables AI assistants to explore your spatial data catalogs, generate Spatial SQL, and execute queries. Configure it manually: Open the **Command Palette** ( + Shift + P on macOS, Ctrl + Shift + P on Windows/Linux). 1. Type **MCP: Add Server** and select it. 2. Select **HTTP (HTTP or Server-Sent Events)** as the server type. 3. Enter the URL: `https://api.cloud.wherobots.com/mcp/` 4. Enter a name for the server (e.g., `wherobots-mcp-server`). Your `mcp.json` file opens automatically. Add a `headers` object with your Wherobots API key: ```json theme={"system"} "servers": { "wherobots-mcp-server": { "url": "https://api.cloud.wherobots.com/mcp/", "type": "http", "headers": { "x-api-key": "" } } } ``` Save the file. Open the **Command Palette** and select **Reload Window**. The extension exposes optional settings for the MCP server — including query timeout, runtime size, and cloud region. See [Extension Settings](/develop/vscode-extension/settings). ## Install Agent Skills [Agent Skills](/develop/agent-skills) give your AI assistant domain-specific knowledge about Wherobots workflows, APIs, and best practices. ```bash theme={"system"} npx skills add -g wherobots/agent-skills ``` If the Wherobots VS Code Extension is pinned to your sidebar, you can also create a new workspace by clicking the **Create Workspace** button. Create Workspace button in the Wherobots sidebar To pin the Wherobots extension to the sidebar: Right-click the **Activity Bar** (the vertical icon bar on the left side of your editor). A menu will appear showing all available extensions. To pin the extension, find **Wherobots** in the list and click on it to ensure it's checked. Wherobots extension checked in the Activity Bar Now you'll have easy access to the extension in your editor's sidebar. ## Verify installation 1. Open your AI assistant's chat panel (Cascade). 2. Select **Agent** as the chat mode. 3. Ask a test question: ```text wrap theme={"system"} List the catalogs in my Wherobots Data Hub ``` 4. If successful, the assistant will call `list_catalogs` and display your available tables. 5. Open the **Command Palette** and type **MCP: List Servers** to confirm the server appears. ## Next steps Browse catalogs, schemas, and tables in the Data Hub sidebar. Create and connect local notebooks to remote Wherobots compute. Submit Python scripts as Wherobots job runs from your editor. Common tasks, example prompts, and cost considerations for the MCP Server. # Wherobots Apache Airflow Provider Source: https://docs.wherobots.com/develop/airflow-provider Wherobots offers an Apache Airflow provider that enables Wherobots Job Runs and SQL Sessions to be orchestrated from Apache Airflow DAGs. These features are particularly useful for automating spatial ETL workloads. ## Benefits You can use Airflow to streamline, automate, and manage complex ETL workload tasks that are running on your data. For example, you might want to perform your training and inference on large datasets in batches rather than all at once due to potential efficiency increases. Airflow can schedule these batch jobs to run at specific time intervals or trigger those batch jobs based on events like the arrival of new data. ## Before you start Before installing the Wherobots Apache Airflow Provider, ensure that you have the following required resources: * Python version 3.8, 3.9, 3.10, 3.11, or 3.12. Python 3.13 is not yet supported. For details on how to circumvent this limitation, see the **uv** tab in [Install from PyPI](#install-from-pypi). * Wherobots API key. For more information, see [API keys](/get-started/wherobots-cloud/api-keys) in the Wherobots documentation. * Apache Airflow. For more information see, [Installation of Airflow](https://airflow.apache.org/docs/apache-airflow/stable/installation/index.html) in the Apache Airflow documentation. ## Setup You can install the Wherobots Apache Airflow provider with `pip` or `uv pip`. You can also add the Wherobots Apache Airflow provider to the dependencies of your Apache Airflow application. ### Install from PyPI To install the Wherobots Apache Airflow provider, run the following commands in your terminal: ```bash theme={"system"} pip install airflow-providers-wherobots ``` The provider currently supports Python **3.8 to 3.12**. If your environment is running Python 3.13, use `uv` to create a compatible environment. 1. Create a virtual Python 3.12 environment. ```bash theme={"system"} uv venv .venv-wherobots-airflow --python 3.12 ``` 2. Activate the virtual environment. ```bash theme={"system"} source .venv-wherobots-airflow/bin/activate ``` 3. Install `airflow-providers-wherobots`. ```bash theme={"system"} # Recommended if using Python 3.13+ uv pip install airflow-providers-wherobots ``` * Replace `3.12` with your desired compatible Python version. * Replace `.venv-wherobots-airflow` with your desired virtual environment name. ### Create a new Connection in Airflow Server You first need to create a Connection in the Airflow Server. There are two ways to create a connection: through the CLI or through the UI. #### Create through CLI You can create the connection through the Apache Airflow CLI. Execute the following from your command line, replacing `$(< api.key)` with your Wherobots API key. ```bash theme={"system"} airflow connections add "wherobots_default" \ --conn-type "generic" \ --conn-host "api.cloud.wherobots.com" \ --conn-password "$(< api.key)" ``` These commands should return a link to the Airflow Server. For more information, see [Managing Connections](https://airflow.apache.org/docs/apache-airflow/stable/howto/connection.html) in the Apache Airflow Documentation. #### Create through UI Or you can create the connection through the Apache Airflow UI following the steps below: Navigate to your Apache Airflow UI home page. click the `Admin` tab on the top right corner, and select `Connections`. Airflow UI connections Click the `+` button to add a new connection. Airflow UI connections Fill in the connection details: Connection ID: `wherobots_default` Connection Type: `generic` Host: `api.cloud.wherobots.com` Password: Your Wherobots API key Airflow UI connections Click `Save` to confirm the connection. # Install Wherobots CLI Source: https://docs.wherobots.com/develop/cli Submit and manage Job runs, stream logs, and access the full Wherobots API from your terminal. Public Preview The **Wherobots Command Line Interface (CLI)** wraps the entire Wherobots Cloud API into a single binary. Submit jobs, stream logs, filter runs, and hit any API endpoint — all from your terminal. Commands are generated directly from the API spec, so every endpoint is a CLI command and new capabilities show up without a CLI update. Use it from any terminal: VS Code, Cursor, Claude Code, OpenCode, or a plain shell. The CLI is designed for interactive and agent-driven use. Commands and their underlying APIs may change between releases. Do not take a dependency on this CLI for recurring production pipelines. ## Quickstart Already familiar with CLIs? Get up and running quickly. 1. Install the CLI: ```bash wrap theme={"system"} curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash ``` 2. Sign in: ```bash theme={"system"} wherobots auth login ``` 1. Confirm that the confirmation code matches the one printed in the terminal, select your Organization, and authorize the CLI. You can also set an API key instead: ```bash theme={"system"} export WHEROBOTS_API_KEY='' ``` 3. Verify the connection to confirm the CLI can reach Wherobots Cloud: ```bash theme={"system"} wherobots --tree ``` ## Benefits The Wherobots CLI provides a powerful and flexible interface to Wherobots Cloud, with features designed for both interactive use and automation: Use the CLI from AI-powered terminals like Claude Code, OpenCode, and Cursor. Your AI assistant translates natural language into the correct CLI commands. [Install agent skills](/develop/agent-skills) to give your agent domain-specific Wherobots knowledge for more accurate results. Commands are generated dynamically from the Wherobots API. New endpoints and capabilities are available immediately without a CLI update. Create Job runs, stream logs in real time, and check metrics without leaving the command line. Local script files are automatically uploaded to managed storage. Switch between human-readable table output and JSON output to integrate the CLI into shell scripts, CI/CD pipelines, and orchestration tools. Use the `--dry-run` flag to print the equivalent `curl` command instead of executing it, so you can inspect exactly what the CLI will send. ## Before you start Before using the Wherobots CLI, ensure you have the following: * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). While the Wherobots CLI can be used with any Organization Edition, some API features, like job runs, require a paid subscription. * A way to authenticate: sign in from your browser with `wherobots auth login`, or a Wherobots **API key** for CI and scripts. See [API Keys](/get-started/wherobots-cloud/api-keys). * A Unix-like shell (`bash`, `zsh`, or similar) with `curl` available. ## Install the CLI Run the install script to download the latest release binary: ```bash wrap theme={"system"} curl -fsSL https://raw.githubusercontent.com/wherobots/wherobots-cli/main/scripts/install-release.sh | bash ``` If prompted for a password in the terminal, enter your local system password. ## Configure authentication The CLI supports two ways to authenticate with Wherobots Cloud: * **Browser sign-in (OAuth)** — sign in interactively with `wherobots auth login`. Best for local, interactive, and agent-driven use. * **API key** — set the `WHEROBOTS_API_KEY` environment variable. Best for CI, scripts, and other non-interactive environments. When both are present, `WHEROBOTS_API_KEY` takes precedence, so scripts behave predictably. ### Sign in with your browser (OAuth) ```bash theme={"system"} wherobots auth login ``` The command prints a one-time confirmation code and opens your browser. Sign in to Wherobots, confirm the code matches, and select your Organization to authorize the CLI. No browser on this machine (for example, over SSH)? Run `wherobots auth login --no-browser` to print just the sign-in URL, then open it on any other device to complete the confirmation. Run `wherobots auth status` to see which credential is active, and `wherobots auth logout` to sign out. Run `wherobots --tree` to confirm the CLI can reach Wherobots Cloud. You should see a tree of available commands, or an error if the connection failed. ### Use an API key You can also login to Wherobots Cloud using an API key. Set the `WHEROBOTS_API_KEY` environment variable in your shell: ```bash theme={"system"} export WHEROBOTS_API_KEY='' ``` To persist this across sessions, add the export to your shell profile (for example, `~/.zshrc` or `~/.bashrc`). Do not commit your API key to version control. Use a secrets manager or environment-specific configuration to keep it safe. Run `wherobots --tree` to confirm the CLI can reach Wherobots Cloud. You should see a tree of available commands, or an error if the connection failed. If you encounter issues, ensure your API key is correctly set and that you have network connectivity to Wherobots Cloud. ### Environment variables The CLI uses the following environment variables for configuration: | Variable | Description | Default | | ----------------------- | ---------------------------------------------------------------------- | --------------------------------- | | `WHEROBOTS_API_KEY` | API key.
Takes precedence over a
browser sign-in when set. | — | | `WHEROBOTS_API_URL` | API base URL | `https://api.cloud.wherobots.com` | | `WHEROBOTS_UPLOAD_PATH` | S3 root for file uploads | Auto-resolved | | `OPENAPI_CACHE_TTL` | OpenAPI spec cache duration | `15m` | | `OPENAPI_HTTP_TIMEOUT` | Spec fetch timeout | `30s` | ## Add agent skills If you use the CLI from an agentic terminal (OpenCode, Claude Code, Cursor, or similar), installing Wherobots agent skills gives the agent structured context about Wherobots workflows, APIs, and best practices. This leads to fewer errors and more reliable multi-step operations. See [Agent Skills](/develop/agent-skills) for installation instructions and the full list of available skills. ## Troubleshooting The following are common issues you may encounter when using the Wherobots CLI, along with their causes and solutions: **Cause:** The CLI cannot find a browser sign-in or an API key in your environment. **Solution:** * Sign in from your browser: `wherobots auth login`. Run `wherobots auth status` to confirm the session is active. * Or export an API key: `export WHEROBOTS_API_KEY=''`. Check that the variable is set in the shell session where you are running the CLI (not just in another terminal). **Cause:** Your credentials are invalid or expired. **Solution:** * If you signed in from your browser, your session may have expired. Run `wherobots auth login` again, or check `wherobots auth status`. * If you use an API key, generate a new one in the Wherobots Cloud console. See [API Keys](/get-started/wherobots-cloud/api-keys). Confirm you copied the full key without leading or trailing whitespace. **Cause:** The binary is not on your `PATH`. **Solution:** * Verify the install directory: `ls ~/.local/bin/wherobots`. * Add the directory to your `PATH`: `export PATH="$HOME/.local/bin:$PATH"`. * If you built from source, the binary is at `bin/wherobots` inside the repository. **Cause:** The CLI cannot reach the Wherobots API to download the specification. **Solution:** * Check your network connection and proxy settings. * The CLI falls back to a cached spec at `~/.cache/wherobots/spec.json`. If the cache is stale, delete it and retry. * Increase the timeout with `OPENAPI_HTTP_TIMEOUT=60s`. ## Next steps Review the following resources to explore more features of Wherobots Cloud and the CLI: Use the CLI with AI-powered terminals like Claude Code and OpenCode for natural language job management. Configure and use the MCP Server for advanced data exploration and query generation. # Using the Wherobots CLI with Agentic Terminals Source: https://docs.wherobots.com/develop/cli-agentic-usage Use the Wherobots CLI from agentic coding tools like OpenCode, Claude Code, and other AI-powered terminals for natural language job management and automation. Public Preview The [**Wherobots CLI**](/develop/cli) works with agentic coding tools like **OpenCode**, **Claude Code**, and other AI-powered terminals out of the box. Because these tools execute commands in your terminal, you can manage Wherobots jobs, stream logs, and access the full API using natural language. ## Before you start The following requirements must be met to use the Wherobots CLI in an agentic terminal: * A **Wherobots Account** within a Professional, Innovation, or Enterprise Organization. See [Create a Wherobots Account](/get-started/wherobots-cloud/create-account). * While all Organization Editions can use the CLI, certain API features and job creation require a Professional, Innovation, or Enterprise Organization. See [Organization Editions](/get-started/organization-management/organization-editions) for details. * A Wherobots **API key**. See [API Keys](/get-started/wherobots-cloud/api-keys). * The **Wherobots CLI** installed and on your `PATH`. See [Install Wherobots CLI](/develop/cli). * Your `WHEROBOTS_API_KEY` environment variable set. See [Configure authentication](/develop/cli#configure-authentication). * An agentic terminal such as **OpenCode**, **Claude Code**, **Cursor**, or another AI-powered coding tool with terminal access. * Models such as **Claude Opus**, **GPT Codex**, or **Gemini Pro** for the best results when using natural language commands. ## Add agent skills Agent skills give your agentic terminal domain-specific knowledge about Wherobots so it produces more accurate commands and better interprets results. Without skills, the agent relies only on CLI help text and its general training data. With skills installed, it has structured context about Wherobots workflows, APIs, and best practices — leading to fewer errors, less back-and-forth, and more reliable multi-step operations. See [Agent Skills](/develop/agent-skills) for installation instructions and the full list of available skills. ## Benefits Describe what you want in plain language. The agentic terminal resolves the correct commands, subcommands, and flags for you. Chain together operations like submitting a job, waiting for completion, and retrieving logs without writing a script. When a command fails, the agent reads the error, suggests a fix, and can retry automatically. ## Example tasks Once the CLI is installed and your API key is set, just ask. Your agentic terminal translates natural language into the right `wherobots` commands, picks the appropriate flags, and interprets the results. Wherobots recommends using the latest high-performing AI model available in your agentic terminal for the best results such as Claude Opus, GPT Codex, or Gemini Pro. ### Explore the API | Terminal Prompt | What you can expect | | ---------------------------------- | --------------------------------------------------------------------- | | *List available CLI commands* | Prints the full command tree so you can see every available endpoint. | | *Preview a job submission request* | Previews the exact API request without executing it. | ### Submit and monitor jobs | Terminal Prompt | What you can expect | | ---------------------------------------------- | ------------------------------------------------------------------------- | | *Submit a script as a job and stream the logs* | Uploads the script, creates a run, and tails the output until completion. | | *Check the status of a recent job* | Fetches the most recent run and reports its state. | | *Get resource metrics for a running job* | Pulls live CPU and memory metrics for the specified run. | ### Debug and triage | Terminal Prompt | What you can expect | | ---------------------------------------------- | ---------------------------------------------------------------------------------------- | | *List recent failed jobs and summarize errors* | Fetches recent failures, parses the structured output, and gives you a readable summary. | | *Retrieve logs from a failed run* | Tails the logs for the most recent failure so you can jump straight to the error. | ### Automate | Terminal Prompt | What you can expect | | ---------------------------------------------- | --------------------------------------------------------- | | *List running jobs as JSON* | Returns the running jobs in JSON format. | | *Cancel all running jobs in a specific region* | Filters runs by region and status, then cancels each one. | ## Next steps Install and configure the CLI for terminal-based Wherobots access. Configure the Wherobots MCP Server for catalog exploration and spatial query generation. # Build & Deploy Source: https://docs.wherobots.com/develop/index Build, run, and manage spatial analytics workloads in Wherobots Cloud Wherobots Cloud provides multiple ways to develop and run spatial analytics workloads — from interactive notebooks to automated pipelines. ## Agentic Development Bring AI-assisted geospatial development to your editor or terminal. Pick your tool and get set up with the Wherobots VS Code Extension, MCP Server, Agent Skills, and CLI. Full automatic setup — extension, MCP, and skills. Extension + manual MCP and skills config. Terminal-only MCP, skills, and CLI setup. VS Code, Cursor, Windsurf, Kiro, Positron, Antigravity, Trae, VS Codium, Claude Code, and OpenCode. ## Interactive Development In Wherobots, you can develop interactively in Jupyter notebooks or SQL sessions. Start pre-configured JupyterLab environments with scalable runtimes. No setup required. Execute SQL queries on demand or on a schedule via the Spatial SQL API. ## Automated Development In Wherobots, automated workloads are defined as Job Runs, which can execute Python or JAR scripts on demand or on a schedule, and SQL Sessions, which can execute SQL queries via the SQL Operator. You can submit Job Runs from the UI, API, or Airflow provider. Execute Python or JAR scripts on demand or on a schedule via the REST API. Execute SQL queries against Wherobots catalogs from Airflow. ## SQL API & SDKs The Wherobots Spatial SQL API lets you execute spatial queries programmatically from Python, Java, and REST. Use it to integrate Wherobots into your applications, automate workflows, or run queries from your local machine. Execute Spatial SQL queries programmatically via Python, Java, and REST. ## Storage Wherobots Cloud offers multiple storage options for your spatial data, including built-in managed storage and integration with your own Amazon S3 buckets. In notebooks, you can seamlessly access data from the file system, managed storage, and S3 in a unified way. Understand the storage options available in Wherobots Cloud. Built-in S3 storage included with every organization (5 GB free). Connect your own Amazon S3 buckets with IAM role authentication. How file system, managed storage, and S3 work together in notebooks. Read Databricks Unity Catalog Delta tables directly in Wherobots without data migration. ## RasterFlow Image preparation and inference engine for large-scale raster processing and geospatial ML workflows. Overview of RasterFlow: mosaics, inference, and vectorization. Built-in datasets and how to bring your own imagery. Built-in models and how to bring your own PyTorch models. ## Orchestration Schedule and automate Wherobots workloads from Apache Airflow DAGs. Use the Airflow provider to orchestrate notebooks, SQL sessions, and job runs alongside your other data workflows. Orchestrate Wherobots workloads from Apache Airflow DAGs. Submit Python or JAR scripts as Job Runs from Airflow. Execute SQL queries against Wherobots catalogs from Airflow. ## Monitoring Workload History provides a comprehensive view of all your Wherobots workloads, including notebooks, SQL sessions, job runs, and automated workloads executed via the MCP server. Monitor resource consumption, track performance, and troubleshoot issues in one place. Monitor notebooks, SQL sessions, job runs to track Spatial Unit (SU) consumption. ## Runtimes & Compute Understand runtime types (General Purpose, Memory Optimized), billing in Spatial Units, and how to request compute access. # MCP Server vs CLI Source: https://docs.wherobots.com/develop/mcp-vs-cli Understand when to use the Wherobots MCP Server and when to use the Wherobots CLI. The [**Wherobots MCP Server**](/develop/mcp/mcp-server-overview) and [**Wherobots CLI**](/develop/cli) are complementary tools for working with Wherobots Cloud. Each is optimized for different tasks. Use this guide to pick the right tool for your workflow. ## When to use the MCP Server The MCP Server is designed for query generation and conversational data exploration. Use it when you want to interact with your data conversationally through an AI assistant. Browse catalogs, databases, and table schemas using natural language. Describe what you want in plain language and get Spatial SQL back. Assess data quality, inspect schemas, and run preliminary analysis. Ask about spatial functions, best practices, and documentation. Generate Jupyter notebooks or other interactive documents based on your data queries and spatial analysis. Configure the Wherobots MCP Server in your editor or agentic terminal. ## When to use the CLI The CLI is designed for **job management and automation**. Use it when you need to run jobs, monitor workloads, or script against the Wherobots API. Create Spark job runs, stream logs, and check resource metrics. List, filter, and inspect job runs by status, name, or timestamp. Every Wherobots API endpoint is available as a CLI command. Integrate with CI/CD pipelines, shell scripts, and orchestration tools. Install and configure the Wherobots CLI. # How to Automate Spatial SQL with Natural Language & Wherobots MCP Server Source: https://docs.wherobots.com/develop/mcp/mcp-server-automating-geospatial-workflows Watch a detailed walkthrough of how the Wherobots MCP server automates data exploration and spatial query generation. Use the [Wherobots Model Context Protocol (MCP) server](/develop/mcp/mcp-server-overview) to go from **no prior schema knowledge** of your spatial data to **production-ready spatial analysis** in minutes. No schema memorization or manual SQL debugging. ## Automated catalog discovery (0:30)