Local API service workflow

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.

The following example shows the basic local workflow that you can follow to use the Platform SDK for local deployments.

You can also find the deployment log files. For more information, see Accessing log files.

Example: Basic local workflow

1. Start the local API service

This process runs in the background, and defaults to port 9876. You can change the port the daemon runs on by passing the --port flag. Only one local API service instance can be running on your machine at one time.

  • To start an instance of the local API service inside your project's directory structure, navigate to your project's root directory and run spatial service start.

    This command first downloads any updates to the local API service, and then starts the service. The command exits when the service is running and ready to receive requests.

    The updates to the local API service always apply regardless of the version of your SpatialOS SDK.

  • To start a local API service instance from outside your project's directory structure, or if your main configuration file (usually called spatialos.json) isn't in the project root, you can specify it by passing the --main_config flag.

For example:

# Will run on port 9876 and attempt to find a spatialos.json file in this directory.
spatial service start
# Will run on port 1234, using the project configuration at the provided path.
spatial service start --port 1234 --main_config path/to/project/spatialos.json

2. Connect to the local API service

Use the normal ServiceClient creation methods (such as DeploymentServiceClient.Create), but specify a PlatformApiEndpoint that points to your locally running instance of the local API service. This must include:

  • the hostname "localhost"
  • the port your instance is running on
  • insecure: true (because the local API service does not support TLS connections)

For example:

var localApiPort = 9876;
var localApiEndpoint = new PlatformApiEndpoint("localhost", localApiPort, insecure: true);
var deploymentServiceClient = DeploymentServiceClient.Create(localApiEndpoint);
var snapshotServiceClient = SnapshotServiceClient.Create(localApiEndpoint);

3. Check the status of the service

Run spatial service status to get information on the running local API service instance.

You can run this command from anywhere, so you don't need to be in a project directory.

If the service is already running, running this command prints out:

  • the process ID of the service
  • the port that the service is running on
  • the project that the service is currently running in

4. Start a local deployment

You need to provide:

  • your cloud project name
  • a name for your deployment
  • a launch configuration file, supplied as JSON
  • a SpatialOS Runtime version

Note: You can specify a snapshot ID in your request to start a local deployment. If you don't specify one, default.snapshot is used.

For example:

var createdDeployment = deploymentServiceClient.CreateDeployment(new CreateDeploymentRequest
    Deployment = new Deployment
        ProjectName = projectName,
        Name = deploymentName,
        LaunchConfig = new LaunchConfig
            ConfigJson = "your launch config"
        RuntimeVersion = runtimeVersion

5. Take a snapshot of the running deployment

You need to provide:

  • the cloud project name
  • the deployment name you chose in step 4

For example:

var latestSnapshot = snapshotServiceClient.TakeSnapshot(new TakeSnapshotRequest
	Snapshot = new Snapshot
		ProjectName = createdDeployment.ProjectName,
		DeploymentName = createdDeployment.Name

6. Stop the deployment

You need to provide:

  • the deployment ID, which is the unique identifier for this particular run of the deployment; you can find the deployment ID on the Deployment object
  • the cloud project name

For example:

deploymentServiceClient.StopDeployment(new StopDeploymentRequest
	Id = createdDeployment.Id,
	ProjectName = createdDeployment.ProjectName

7. Stop the local API service

Run spatial service stop to shut down the running local API service instance.

Stopping the local API service also shuts down any locally running deployment that you started using the local API service.

Accessing log files

You can find the deployment and service log files in <project>/logs/<deployment_name>/<date_and_time_of_deployment>/, and the local API service process log files in ~/.improbable/spatiald/log/.

For more information about log files and how to change log file location, see Logging with the SpatialOS CLI.

2019-08-06 Page updated with editorial review

Updated 11 months ago


Suggested Edits are limited on API Reference Pages

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