title: 'Cloud Connect' sidebar_label: 'Cloud Connect' description: 'Connect a self-hosted Spice instance to Spice Cloud for remote management.' keywords: [spice.ai, cloud connect, enrollment key, remote management] sidebar_position: 1 tags:
Cloud Connect attaches a self-hosted Spice instance to the Spice Cloud Platform, where it can be monitored and configured from the portal. The data stays on the host that runs the instance.
The instance dials out to Spice Cloud. Spice Cloud never opens an inbound connection to it.
| Method | The instance runs | Command |
|---|---|---|
| Development (opens in a new tab) | in the terminal that started it | spice cloud link, then spice run |
| Service (opens in a new tab) | as a Linux or macOS service | spice cloud service install |
| Headless (opens in a new tab) | in a container or under any supervisor | spiced --token <key> |
Windows has no managed service. A Windows host runs the instance with spice run or under its own supervisor.
Cloud Connect state belongs to an instance directory, not to the host: the issued identity lives at <dir>/.spice/identity.json. Commands act on the directory they run from.
SPICE_CONFIG_DIR replaces the derived path entirely, which is how a container places the identity on a mounted volume.
An enrolled directory reconnects on its own. A later spice run or spiced started there connects with no Cloud Connect flag.
:::warning An identity expires after 30 days offline. An instance that has been down longer must enroll again. :::
Two credentials can enroll an instance:
spice cloud link. It requires the owner or admin role in the organization, and attaches the instance to a project that already exists — spice cloud project create <name> creates one.spiced --token. A key enrolls exactly one instance and creates no project; the runtime log carries a portal link for that.A key is shown once and is never recoverable from Spice Cloud. What restarts an instance is the issued identity under <dir>/.spice, which belongs on persistent storage.
A deployment from the portal reconciles into the running process; it never restarts the instance. These sections apply while it serves:
datasetsviewsmodelsfunctionscatalogsEvery other section is read only when the runtime starts, as is a removed catalog. The runtime names the pending sections as it applies the deployment, and the project in Spice Cloud reports the same set:
Whatever owns the process performs the restart: spice cloud service restart for a service, a stop and a fresh spice run in a terminal, or a recreated container or pod.
spice cloud unlink releases the instance in Spice Cloud, uninstalls its service, and clears the local identity. It refuses while the instance is running, and it leaves the project in place — delete that with spice cloud project delete <org>/<project>.
spice cloud service uninstall is the narrower operation: it removes the service and keeps the Cloud identity, so a later install resumes the same enrollment.