Setup Guide · v2.4

# Get up and running with Spaces on StartOS

A step-by-step walkthrough to install StartOS, configure your environment, and launch your first Space — typically in under ten minutes.

Start the setup Read the intro

- ⏱ ~10 minutes
- 💻 macOS · Linux · Windows
- 📦 No prior setup required

## Introduction

Spaces is the workspace layer of StartOS — a lightweight runtime for organizing services, data, and collaborators into isolated environments you can spin up, snapshot, and tear down on demand. Whether you're prototyping a side project or operating a fleet of production deployments, Spaces gives you a consistent, reproducible foundation.

This guide will walk you through installing StartOS, performing the initial setup, and launching your first Space. By the end, you'll have a running instance with one workspace ready for work.

The StartOS dashboard after a fresh install.
Heads up: StartOS is still moving fast. If something looks different from a screenshot, check the version badge in the bottom-left corner of the dashboard.

## Prerequisites

Before you begin, make sure you have:

- A machine running macOS 12+, Ubuntu 20.04+, or Windows 10+ (with WSL2).
- At least 4 GB of RAM and 10 GB of free disk space.
- Administrator (sudo) access on the target machine.
- Network access to `downloads.startos.example`.
- A StartOS account — create one for free if you don't have one.

## 1. Install StartOS

The fastest way to install StartOS is via the official installer. It bundles the runtime, CLI, and a local control plane into a single setup flow.

### Download the installer

Open a terminal and run the install script:

    $ curl -fsSL https://get.startos.example | sh

The installer will detect your platform, fetch the appropriate package, and guide you through a four-step wizard. When prompted, select Standard Installation unless you have specific infrastructure requirements.

The installation wizard — step 2 of 4.
Tip: On Linux servers without a desktop environment, pass `--headless` to skip the GUI wizard: `sh -c "$(curl -fsSL https://get.startos.example) --headless"`.

## 2. Configure your instance

Once StartOS is installed, open the dashboard at `http://localhost:8080`. You'll be guided through a short first-run configuration. Most users only need to set a hostname, choose a port, and enable HTTPS.

Configuring networking from the Settings panel.

### Recommended defaults

Setting | Recommended value | Notes
--- | --- | ---
Hostname | `startos-spaces` | Used for service discovery.
Port | `8080` | Change if another service is bound.
Enable HTTPS | On | StartOS will provision a self-signed cert.
Domain | `spaces.example.com` | Optional — leave blank for local-only access.

## 3. Create your first Space

From the dashboard, click Create Your First Space. Give your Space a name, pick the region closest to you, and choose a resource tier. The Medium tier is a good starting point for most projects.

Creating a new Space takes about 30 seconds.

1. Name your Space. Use something descriptive like `my-workspace` or `acme-prod`.
2. Pick a region. Latency-sensitive workloads should run closest to their users.
3. Choose a tier. You can resize the Space later without downtime.
4. (Optional) Add tags. Tags make it easier to filter Spaces in larger teams.
5. Click Create Space. You'll be redirected to the Space's overview page.

After a few moments, your Space will appear in the Spaces list with a green Running badge.

Multiple Spaces, each with live CPU and memory metrics.

## 4. Verify the installation

From any terminal, you can confirm that StartOS is healthy and that all services are reporting in:

`startos status` should report every service as OK.

If any service is in a `DEGRADED` or `DOWN` state, jump to the Troubleshooting section below.

## Troubleshooting

The installer fails with "port 8080 is in use"

Another service is already bound to port 8080. Either stop the conflicting service or re-run the installer with `--port 9090` to use a different port.

The dashboard won't load at `http://localhost:8080`

Run `startos status` in a terminal. If the `web` service is not reporting OK, restart it with `startos restart web`.

I see "Permission denied" during install on Linux

The installer needs to write to `/usr/local/bin`. Re-run the script with `sudo`, or specify a writable prefix with `--prefix=$HOME/.local`.

My Space is stuck on "Provisioning"

Provisioning typically completes in under a minute. If it takes longer, check the activity log on the Space's overview page. Most often this indicates a temporary region capacity issue — try a different region.

## Next steps

You're up and running. Here are some good places to go from here:

#### Deploy a service

Drop a service into your Space from the template gallery.

Browse templates →

#### Invite your team

Add collaborators and set role-based permissions.

Manage members →

#### Automate with the CLI

Use the `startos` CLI to script common tasks.

Read the CLI docs →