These are the docs for 11.0, 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 →

Deploying to the cloud

In a nutshell

To deploy a project to the cloud:

  1. (First time only) Configure the project.

  2. Build the project: spatial worker build -t=deployment.

  3. Upload the project assembly: spatial cloud upload <assembly name>

  4. Choose the snapshot to start the world from.

  5. Deploy: spatial cloud launch <assembly name> <launch configuration file> <deployment name> --snapshot=<snapshot file>

  6. (Optional) Launch a client: Go to

Unity cheat sheet

For a handy guide to how to deploy Unity changes, see this cheat sheet:

Unity build cheat sheet

Step-by-step guide

1. (First time only) Configure the project

If you’re deploying for the first time, configure your project’s spatialos.json:

  1. In the project’s root directory, open spatialos.json. This file holds your project’s global configuration.
  2. In the name field, rename the value to your assigned SpatialOS project name.

    You can find your project name in the Console. It’ll be something like beta_someword_anotherword_000.

2. Build the project

Now you need to build an assembly.

To keep build times down, see this cheat sheet for what to build when (Unity only).

Or, you can build the whole project from the command line:

  1. If your project includes a Unity worker, close the Unity Editor (otherwise the build will fail).

  2. In the project’s root directory, run spatial worker build --target=deployment.

    When it finishes successfully, you’ll see build finished in your console output.

For more details, see Building.

3. Upload project assembly to the cloud

To upload the assembly you just built from your project, run spatial cloud upload <assembly name>

where assembly name is a name you choose. It’ll identify the assembly you just built.

When this has run successfully, you’ll see upload <assembly name> finished in your console output.

NOTE: When you update SpatialOS versions, you must rebuild the assembly and upload it with a different name. You could add a date or a commit hash to the name; for example, my_assembly_name_160809.

4. Choose the snapshot to start from

All deployments must start from a snapshot. You can:

You’ll use this snapshot in step 5.

Alternatively, you can configure your project to load from a specific snapshot.

5. Deploy the project

To deploy the project to the cloud, run

spatial cloud launch <assembly name> <launch configuration file> <deployment name> --snapshot=<snapshot file> [flags]


  • assembly name is the name of the assembly you uploaded with spatial cloud upload.
  • launch configuration file is a launch configuration file. It’s usually default_launch.json in the project’s root directory.
  • deployment name is the label for this deployment in the Console. Must be in lowercase.
  • snapshot file is the snapshot to start the world from, which you chose in step 4
  • flags are optional flags. Run spatial cloud launch --help to see the list of available flags.

Note: This command defaults to deploying to an US production cluster (such as us3-prod). If you’re in Europe, add --cluster_region=eu to to deploy to a European cluster.


spatial cloud launch my_assembly_name_160809 default_launch.json my_deployment_name --snapshot==snapshots/default.snapshot --cluster_region=eu

Run spatial cloud launch --help for more information.

When this finishes successfully, you’ll see Successfully created deployment in your console output. The output will also give you a link to your deployment in the Console.

6. (Optional) Launch a client

If your project has a client, you can follow these steps to launch it:

  1. Open the Console.
  2. Find your deployment and click on its name. The page that opens will shows an overview of the deployment.
  3. Launch a client:

    1. Click the ▶ Launch button.

    2. If you don’t already have it, install the Improbable Launcher (Windows / Mac).

    3. Click Launch Your Deployment:

    Console - launcher dialog

You can now explore your project from the client.

7. Stop the deployment

Manually stopping a deployment

We recommend manually stopping a deployment after you’ve finished with it, to save on resource usage.

To manually stop a deployment:

  1. Open the Console.

  2. Find your deployment and click on its name.

  3. In the page that opens, click the STOP button:

    Stop deployment

Automatically stopping deployments

By default, deployments are stopped automatically 6 hours after they start. You can add tags in the Console to change this behaviour:

  • To keep the deployment running until 5pm UTC on the next weekday, add the tag nightly.
  • To keep the deployment running indefinitely, add the tag leave_me_up.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums