Let's get started! By the end of this guide you'll have deployed a Unison service to the web, issued a request to it, and verified that it's visible in your Cloud application management UI.

Before you begin

Install Unison

Via Homebrew:

brew tap unisonweb/unison
brew install unison-language

Manually for Linux:

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-linux.tar.gz \
	| tar -xz

Manually for MacOS:

mkdir -p unisonlanguage && cd unisonlanguage
curl -L https://github.com/unisonweb/unison/releases/latest/download/ucm-macos.tar.gz \
  | tar -xz

On Windows:

Download the package here and extract it to a folder. Run ucm.exe from the command line.

👉 Then sign up for Unison Cloud

Authorize your Unison account

Start up Unison with ucm in your terminal and enter auth.login in the UCM console.

$ ucm

  Now starting the Unison Codebase Manager (UCM)...

   _____     _
  |  |  |___|_|___ ___ ___
  |  |  |   | |_ -| . |   |

  👋 Welcome to Unison!

.> auth.login

@unison/base/slug> auth.login

  Please navigate to
  to authorize UCM with the codebase server.


Great! Your UCM console is set up to deploy to the Unison Cloud.

Deploy a template project

Create a project in the UCM and pull the @unison/cloud-start library into it. The cloud-start project contains some sample services and the latest versions of several relevant libraries.

.> project.create-empty
amusing-giraffe/main> pull @unison/cloud-start/releases/latest

🕰️ Give the project a moment to download if this is your first time using the Cloud. Later downloads will be much faster.

This creates an empty project with a random name, and one of the examples it installs is the "hello-world" service we'll be deploying.

Check out what the deployment function looks like while you're in the UCM console:

amusing-giraffe/main> view examples.helloWorld.deploy

  examples.helloWorld.deploy : '{IO, Exception} ()
  examples.helloWorld.deploy = Cloud.main do
      serviceHash = deployHttp !Environment.default helloWorld.logic
      name = ServiceName.create "hello-world"
      base.ignore (ServiceName.assign name serviceHash)
      printLine "Logs available at:\n  https://app.unison.cloud"

This one function is responsible for shipping the helloWorld service logic from your machine to the Cloud, returning a unique hash based on its contents, and assigning it a static service name.

Ship it and verify

Next run the deployment:

amusing-giraffe/main> run examples.helloWorld.deploy

Your service is live! It should print out a URL that you can try out in a browser or with CURL:

$ curl https://<yourusername>.unison-services.cloud/s/hello-world/Unison
👋 hello Unison
$ curl https://<yourusername>.unison-services.cloud/s/hello-world/Alice
👋 hello Alice
$ curl https://<yourusername>.unison-services.cloud/s/hello-world/Bob
👋 hello Bob

You can then visit app.unison.cloud to view all your deployed services and their logs. That's it, you're now connected! Go forth and build. ⭐️

Next up

Troubleshooting and community

If you have any trouble with these instructions or have questions after getting going, we're here to help:

  • The #cloud channel on Discord is a place to follow Unison Cloud news and updates, get help, and find tips and tricks.
  • The corner chat widget of unison.cloud is another place you can get help.
  • For general Unison language questions and announcements, visit the Unison Discord.

Bug reports, feature requests, ideas, and feedback are most welcome on any of these channels. The Discord is also a nice place to meet other folks using Unison + Unison Cloud. We're a friendly and supportive group!

Important limitations

For the durable storage support, see the State API docs for a note on size limits of entries and transaction size limits.

Storage on the free tier of Unison Cloud expires every 3 months.

As a conservative security measure, we also (for now) strip cookies from all service requests and responses. Custom domains (a paid feature) will let you read and write whatever cookies you wish. We're also working on allowing cookies within a subdomain of unison-services.cloud scoped to just your user. There are some security issues with cookies in webapps that can serve up arbitrary JavaScript, so we want to make sure we do this properly.