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 →

Capacity limiting

The deployment service is in alpha and may have breaking changes before stabilizing. For more information on maturity stages see Maturity stages.


You can configure worker connection rate and capacity limit at launch, or while a deployment is running using the Deployment APIs. This functionality requires that clients connect using the alpha version of the Worker.Locator class (C#/C++).

This scenario demonstrates how to configure capacity limits for a running deployment. (It doesn’t cover rate limit configuration, as this is very similar.) If you’re looking for how to configure capacity and rate limits on launch, refer to the documentation on worker connection limits.

Find out how to download the Platform SDK from the setup guide.

You can find the full code example for this scenario on GitHub.

Example: applying a dynamic capacity limit to a running cloud deployment

1. Instantiate clients

Instantiate clients of the DeploymentServiceClient types.

Use the Create method of the DeploymentServiceClient.

private readonly DeploymentServiceClient _deploymentServiceClient = DeploymentServiceClient.Create();

By default, this uses your refresh token saved locally by the SpatialOS CLI. You can find your token at:

  • Windows: C:\Users\<username>\AppData\Local\.improbable\oauth2\oauth2_refresh_token\
  • Mac: ~/.improbable/oauth2/oauth2_refresh_token

If you want to provide a refresh token, you can instantiate a PlatformRefreshTokenCredential object and supply it to create:

var credentialsWithProvidedToken = new PlatformRefreshTokenCredential("my_refresh_token");
private readonly DeploymentServiceClient _deploymentServiceClient = DeploymentServiceClient.Create(credentials: credentialsWithProvidedToken);

Since this use case is intended as part of your deployment management server, we recommend using the refresh token of a service account. To create a service account, see Service account maintenance. You need to create one with at least read and write permissions on your project. See Permissions for details.

2. Choose a running deployment to apply the capacity limit to

You can only dynamically change rate and capacity limits for running deployments. Choose the first running deployment:

var suitableDeployment = _deploymentServiceClient.ListDeployments(new ListDeploymentsRequest
    ProjectName = ProjectName,
    DeploymentName = DeploymentName
}).First(d => d.Status == Deployment.Types.Status.Running));

3. Set the capacity limit for the worker type “my_worker_type” to 2

You apply capacity limits per worker type, so you must specify a valid worker type when setting the capacity limit.

suitableDeployment.WorkerConnectionCapacities.Add(new WorkerCapacity
    WorkerType = "my_worker_type",
    MaxCapacity = 2
_deploymentServiceClient.UpdateDeployment(new UpdateDeploymentRequest {Deployment = suitableDeployment});

To modify an existing capacity limit, you can modify the value of that object directly.

    .First(c => c.WorkerType == "type_to_change")
    .MaxCapacity = 2;
_deploymentServiceClient.UpdateDeployment(new UpdateDeploymentRequest {Deployment = suitableDeployment});

4. Clear all existing capacity limits for a deployment

To clear all capacity limits, pass in an empty array for the capacity field.

_deploymentServiceClient.UpdateDeployment(new UpdateDeploymentRequest {Deployment = suitableDeployment});

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums