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

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"
        }
    }
}).PollUntilCompleted().GetResultOrNull();

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
	}
}).PollUntilCompleted().GetResultOrNull();

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