These are the docs for 13.8, an old version of SpatialOS. The docs for this version are frozen: we do not correct, update or republish them. 14.5 is the newest →

Using the Platform SDK locally

The SpatialOS CLI ships with a local API service. This runs as a background daemon on your machine, and allows you to use the Platform SDK to develop tools for local deployments.

You must run the local API service in order to use the Platform SDK locally, and you can only run one instance of the local API service on a machine at any time.

You can use the SpatialOS CLI commands to interact with the local API service.

Example: basic local workflow

1. Start the local API service

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

The 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 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 serice. 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

You can get information on the running local API service instance, if it exists, using spatial service status.

You can run this command from anywhere - you don’t need to be in a project directory.

4. Start a local deployment

You need to provide:

  • your project name
  • a name for your deployment
  • a launch configuration file, supplied as JSON

For example:

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

5. Take a snapshot of the running deployment

You need to provide:

  • the 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 (the unique identifier for this particular run of the deployment; you can find this on the Deployment object)
  • the project name

For example:

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

7. Stop the local API service

To shut down the running local API service instance, run spatial service stop.

Stopping the local API service also shuts down any locally running deployment that was started with 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>/.

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

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums