Local API service

The local API service enables you to use the Platform SDK to develop tools for local deployments easily. This, in turn, helps you iterate on local deployments much faster than using the SpatialOS CLI. Projects using the SpatialOS GDK for Unreal now use the local API service directly. However, to use the local API service for other projects, you must write your own tooling using the Platform SDK.

The SpatialOS local API service is a background process that runs on your machine, which allows you to use the Platform SDK to interact with local deployments.

By using the local API service, you are able to:

  • Create and manage local deployments using the Platform SDK. This means you can write tools that work for both local and cloud deployments.
  • Use the same player login flow locally that you use in the cloud, allowing you to test integration with your login server or matchmaker.
  • Take and download snapshots of local deployments on demand, rather than having to wait for an automatic snapshot to occur.

The SpatialOS CLI ships with the local API service, and you can use the SpatialOS CLI commands to start and stop the local API service. For more information, see the spatial service commands.


If you’ve followed the tools installation guide (Windows/Mac/Linux), you will already have the SpatialOS CLI and so are ready to start the local API Service.

Otherwise, you can set up the CLI manually (Windows/Mac) or using a package manager (Windows/Mac).

Differences between the local API service and the cloud APIs

The local API service runs on your machine and so has both advantages and disadvantages compared to the cloud APIs. One advantage is being able to access your project files directly without uploading them.

Differences when you create local deployments

Because the local API service has direct access to the project files on your local file system, you do not need to upload an assembly or a snapshot before creating a deployment.

Because the service automatically finds the built workers inside your project, in your CreateDeployment request, you do not need to specify an Assembly ID.

The service also reads your project directory’s snapshots folder, so you do not need to upload them before using them in a CreateDeployment request. To create a deployment, in your CreateDeployment request, you specify the value of StartingSnapshotId using the file name of the snapshot file. For example, if you use default.snapshot to create a deployment, you specify default as StartingSnapshotId in your CreateDeployment request.

Restrictions when you use the local API service

Before you use the local API service, review the following restrictions on the Local API service, which are different from the cloud APIs:

  • You can run only one local deployment at a time. This limitation applies both to the SpatialOS CLI and to the local API service.
  • You can run only one instance of the local API service for a single project at a time.
  • When you run deployments using the SpatialOS CLI, the deployment logs are printed to your terminal. However, when you run local deployments using the local API service, you can access the deployment logs only in your project’s logs directory: <project>/logs/<deployment_name>/<deploymentId>/runtime.log.
  • Although, like the cloud APIs, the local API service keeps a history of the deployments that you have run (which is returned by the ListDeployments request), this history is not kept when you restart the service.

Local API service and network activity

The local API service communicates with the Improbable servers at various times:

  • Authorization: Checking that users are using the platform from authorized accounts. This is the step that opens a web page. Once checked, authorization lasts for a few hours.
  • Updates: Checking for updates to the underlying infrastructure, such as the SpatialOS Runtime. These updates happen both periodically and when a new deployment is launched.
  • Analytics: Logging to help us understand how people are using the platform.

For more information, see Network settings.

If you’ve run a local deployment at least once while online and haven’t since changed your launch configuration file or SDK version, the local API service is able to use cached resources next time you create the same deployment. As a result, you can iterate on your project without requiring a network connection.

2019-08-06 Page updated with editorial review

Updated about a year ago

Local API service

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.