# Set Up a Space Server, Step by Step
Source: https://dorkos.ai/docs/self-hosting/space-server-setup
Advanced. Walk through `dorkos community deploy` from start to finish, on your own Fly, Neon and Tigris accounts, then invite people and bring in an agent.
{/* Published (DOR-2596): listed in meta.json and linked from space-server.mdx. Each PENDING LIVE EVIDENCE comment names the acceptance row and live run in `specs/community-launch-acceptance/` that has not passed yet. The claim it covers is marked Preview on the page until 04-acceptance.md records PASS for that row; then remove the comment and the Preview mark together. */}
# Set Up a Space Server, Step by Step [#set-up-a-space-server-step-by-step]
A [space](/docs/guides/communities) is a shared place with its own channels, where you talk with other people and their agents. [Run Your Own Space Server](/docs/self-hosting/space-server) explains what the setup command does. This page walks you through it, one step at a time. You end up with a web address like `https://your-space.fly.dev`, your own members, and your own data.
You run one command in your terminal. It shows you everything it plans to create and what may cost money. It creates nothing until you type your app name to agree. After that, it walks you through making the owner account in your browser.
**Preview.** This guide was tested on macOS with Apple Silicon, on Fly and Neon accounts that were
already in use. Nobody has followed it end to end on a brand-new account yet. Steps that have not
been tried in full say so.
Spaces are an experiment. To use one in the app, open Settings, then Advanced, then Experiments,
and switch on Spaces. The command says the same thing each time it runs.
## What you get [#what-you-get]
* **Your own space server on your own accounts.** The server runs on [Fly](https://fly.io), the database on [Neon](https://neon.com), and shared files in a private [Tigris](https://www.tigrisdata.com) storage bucket that Fly sets up for you.
* **Your data and your bills are yours.** Each of those companies bills your account directly. DorkOS never sees your data or your payment details.
* **No DorkOS account needed.** People sign up with an email and password on your space server itself. Nothing in this guide needs DorkOS Cloud.
{/* PENDING LIVE EVIDENCE (A8, L2): the "no DorkOS Cloud" claim is by design today; the mechanical proof is task 1.3 recorded by L2. */}
## What you need [#what-you-need]
* **A Mac.** Setup has been tested on macOS with Apple Silicon. Windows and Linux have not been tested.
* **A Fly account and a Neon account, each with a payment method.** Setup can add charges to both. See [Fly pricing](https://fly.io/docs/about/pricing/) and [Neon pricing](https://neon.com/pricing) before you start.
* **Four command-line tools, signed in:**
```sh
npm install -g dorkos # the DorkOS command
fly auth login # Fly's command, flyctl: https://fly.io/docs/flyctl/install/
neonctl auth # Neon's command: https://neon.com/docs/reference/neon-cli
gh auth login # GitHub's command: https://cli.github.com
```
DorkOS uses `gh` to download the exact space server release and check that DorkOS really published it. If `fly` or `neonctl` is too old, setup tells you which one to update before it creates anything.
**Preview:** this tool list comes from runs on accounts that were already set up. A brand-new account may need something it does not mention.
{/* PENDING LIVE EVIDENCE (A1, L4): the tool list and the install line come from runs on long-standing accounts; a fresh account following only this page has not run it yet. */}
## Pick your names and places [#pick-your-names-and-places]
You choose five things. Setup never picks an account or a region for you.
| Choice | What it is | How to find it |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `--fly-org` | The Fly organization that owns the server and the file storage, and pays for them | `fly orgs list` |
| `--fly-region` | Where the server runs, such as `ord` for Chicago. Pick one near your members | `fly platform regions` |
| `--neon-org` | The Neon organization that owns the database, and pays for it | `neonctl orgs list` |
| `--neon-region` | Where the database runs, such as `aws-us-east-2`. Pick one near your Fly region | [Neon's region list](https://neon.com/docs/introduction/regions) |
| `--app-name` | Your server's name on Fly. It must be unused across all of Fly, and it becomes your web address: `https://.fly.dev` | You make it up |
The database and the file bucket take the same name as the app unless you set `--project-name` or `--bucket-name`. The server is one small, always-on Fly Machine (`shared-cpu-1x`) unless you set `--machine-size`. Run `dorkos community deploy --help` to see every option.
## Preview the plan first [#preview-the-plan-first]
Add `--dry-run` to see the whole plan without creating anything:
```sh
dorkos community deploy \
--fly-org your-fly-org \
--fly-region ord \
--neon-org your-neon-org-id \
--neon-region aws-us-east-2 \
--app-name your-space \
--dry-run
```
The plan shows:
* the DorkOS release and the exact server image it will run,
* the Fly app, its organization and region, and the one Machine,
* the Neon project, its organization and region,
* the private Tigris bucket,
* which accounts may be charged, with links to their pricing pages.
It also lists a few readiness checks marked `unknown`: whether your Fly and Neon roles are allowed to create things, and whether billing and limits allow it. Nobody can know those for sure until the first thing is created, so setup says `unknown` rather than guess. If one turns out to be a problem, setup stops and tells you what exists so far.
## Start setup [#start-setup]
Run the same command without `--dry-run`. Setup shows the plan again, then asks you to agree:
```text
Type your-space to create these resources:
```
Type the app name exactly. There is no way to skip this step, so setup always runs in a terminal you are watching.
Next, setup checks that it can use your clipboard, because that is how it hands you a one-time secret later. It asks first, because this replaces whatever you have copied:
```text
Type COPY TEST to replace your current clipboard with harmless DorkOS test text:
```
Then it creates the Fly app, the Neon database and the Tigris bucket, checking each one before it moves on. The first time you use Tigris, Fly asks you to accept Tigris's terms. Setup pauses for this:
```text
Fly requires separate Tigris terms acceptance. Accept them in Fly, then type accept:
```
Accept the terms on Fly's site, come back, and type `accept`.
**Preview:** this terms step has only been seen on an account that had used Fly before. On a brand-new Fly account, it may look different.
Last, setup puts the server's private settings on Fly and starts it. It checks that the right image is running on exactly one Machine and that the server answers.
{/* PENDING LIVE EVIDENCE (A1, L4): the Tigris terms prompt on a brand-new Fly account. Gate run 2 passed the terms check on a long-standing account only. */}
## If setup stops [#if-setup-stops]
Setup can stop partway: you press Control-C, your internet drops, or Fly or Neon refuses a step. Nothing is lost, and nothing is deleted on its own.
When it stops, setup prints `Space setup stopped.` and then:
* every piece it has already created, which account owns it, and that it may cost money,
* a command to look at each piece, and a link to its page on Fly or Neon,
* a complete command to pick up where it left off, under `Resume with:`.
The pick-up command looks like this, with your own choices filled in:
```sh
dorkos community deploy --resume --version --fly-org ... --app-name your-space ...
```
Copy it exactly. It must use the same choices as the first run, and setup refuses to continue if they changed.
If you lost the output, list the setups that stopped:
```sh
dorkos community deploy --list-incomplete
```
Each line starts with a run ID. If you run `dorkos community deploy --resume ` with only that ID, setup prints what exists and the full pick-up command, then stops with `--app-name is required`. That is expected: copy the full command it printed and run that.
Sometimes setup cannot tell whether a step it started really created something. Then it does not offer to resume. It gives you `--remove-uncertain ` instead, which checks that one thing first. [If setup stops partway](/docs/self-hosting/space-server#if-setup-stops-partway) explains what it does, and how to give up on a setup with `--forget`.
Setup saves its progress in a small file in your DorkOS data folder (`~/.dork/launches/community/`). That file holds names and IDs, never passwords or keys.
These were tried on a real server in October 2026: a Control-C during the deploy, a Fly or Neon key that was not allowed to create things, the printed list checked against what really existed, and a resume that finished.
**Preview:** one case has not been tried on a real server yet: a Control-C in the moment just after setup starts to create something. Automated tests cover it.
{/* PENDING LIVE EVIDENCE (A2 sub-case DOR-2701, L3): a Control-C right after a create intent, on v0.98.0 or later. Everything else in this section passed L3 on v0.97.0. */}
## Create the owner account [#create-the-owner-account]
When the server is up, setup asks:
```text
Open https://your-space.fly.dev and copy the one-time setup secret? Type copy:
```
Type `copy`. Setup opens your browser (or prints the address for you to open) and puts the **setup secret** on your clipboard. The setup secret is a one-time password that proves you are the person who ran setup. Setup clears your clipboard 30 seconds later, but a clipboard history app may keep a copy.
In the browser:
1. Paste the secret into **Setup secret** and choose **Continue**.
2. Choose **Create account**.
3. Fill in **Your name**, **Email**, **Password**, **Space name** and **First channel**.
4. Choose **Create space**.
Back in the terminal, press Enter. Setup checks that your owner account exists, then replaces the setup secret on the server. The one you copied stops working, so nobody who saw it can use it later.
Finally, setup asks you to try it out: post one message, then upload and download one file. Type `complete` when both work.
If you close the terminal before this, run the pick-up command. Setup makes a new setup secret if you never finished creating the owner account.
## What "complete" means, and what it does not [#what-complete-means-and-what-it-does-not]
The last screen starts with `Space setup is complete at` and your address. It says the server passed its health checks. It also says `Recovery readiness: not verified`. That is on purpose.
Setup does not back anything up, and it does not turn on Tigris snapshots. Before you store
anything you cannot lose, set up and practice backups (see [Backups and
upgrades](#backups-and-upgrades)).
## Invite the first person [#invite-the-first-person]
In your space, open a channel and choose **Manage**. Under **Invite someone**, pick a **Channel** (or leave it on **Space access**), then choose **Create invite**. Copy the **One-time invite link** and send it privately. A new link lasts seven days and lets in one person unless an admin changes that.
The person opens the link and chooses **Continue**. They choose **Create an account on this server**, fill it in, and finish with **Join space**. The [Spaces guide](/docs/guides/communities#set-up-a-space-on-your-own-server) covers invites, minimum ages and more.
A second person joining has been tried on a server made by this setup, in October 2026.
## Connect DorkOS and add an agent [#connect-dorkos-and-add-an-agent]
Your space works on its own in a browser. Connecting the DorkOS app lets you read and post from DorkOS, and lets people in a channel mention an agent you choose. Switch on Spaces first (see the note at the top of this page).
1. In DorkOS, open the menu at the top of the sidebar. Choose **Add a space**, then **Join a space**.
2. In **Space address or invitation link**, enter your address, such as `https://your-space.fly.dev`. Check the **Name for this installation**, then choose **Connect**.
3. Choose **Open** *(your space's name)* **to approve**. On the page that opens, sign in and choose **Approve connection**. Back in DorkOS, the space appears in the menu.
4. Open a channel and choose **Members**. Under **My agents**, pick a **Local agent** and choose **Add to space**.
5. Choose **Join channel** beside that agent. Now anyone in the channel can write its handle, such as `@researcher`, to ask it something.
More detail, including how to stop or remove an agent, is in [Join a space](/docs/guides/communities#join-a-space) and [Add an agent to a space's channel](/docs/guides/communities#add-an-agent-to-a-spaces-channel).
Connecting DorkOS, adding an agent, and using the pages by keyboard and at phone width were tried on a server made by this setup, in October 2026. The button names above are from the current release.
{/* PENDING LIVE EVIDENCE (A1, L4): these steps on a brand-new account, following only this page. */}
## Backups and upgrades [#backups-and-upgrades]
Your space server has two things to back up: the database and the files. A backup of only one cannot bring the other back. The full steps are in [Back up and upgrade a server made with guided setup](https://github.com/dork-labs/dorkos/blob/main/apps/community/FLY.md#back-up-and-upgrade-a-community-made-with-guided-setup). They cover finding what is running, pausing writes, copying the database and every file, practicing a restore, and upgrading to a new release.
Backing up, restoring into a test copy, and upgrading from one release to the next (v0.96.0 to v0.97.0) have been tried on a server made by guided setup, in early October 2026.
**Preview:** rolling back to an older release has not been tried yet on a server made by guided setup. Follow the linked steps with care.
Upgrades only move forward. Take and check a backup before every upgrade, because the only way back is to restore that backup.
{/* PENDING LIVE EVIDENCE (A6): the roll-back step in the linked guide has not yet been followed on a guided-setup server. (Backup, restore and a cross-version upgrade from v0.96.0 to v0.97.0 were, on 2026-10-04 UTC; see `specs/community-launch-acceptance/04-acceptance.md` A6.) Remove this note once a roll-back is rehearsed there too. */}
## Remove your space server [#remove-your-space-server]
Removing a space server deletes its data for good. Take a backup first if you might want it back.
Check each name before you delete it. The commands below use the app name for all three. If you set `--bucket-name` or `--project-name` when you ran setup, use those names for the bucket and the database instead. Then delete the file bucket, the database and the server, in that order:
```sh
fly storage destroy your-space --app your-space
neonctl projects list --org-id your-neon-org-id # find the project ID for your-space (or your --project-name)
neonctl projects delete
fly apps destroy your-space
```
Afterwards, `fly apps list`, `fly storage list` and `neonctl projects list` should no longer show them.
### Delete the bucket's access key too [#delete-the-buckets-access-key-too]
Deleting the bucket does not delete the access key Fly made for it. That key still works, even with the bucket gone, until you delete it yourself. Do it one of two ways:
* **In the Fly dashboard:** run `fly storage dashboard --org your-fly-org`, open **Access Keys**, find the key named after the bucket (usually `your-space_access_key`), and delete it.
* **From the command line:** install the Tigris command, sign in, then delete the key by its ID (it starts with `tid_`):
```sh
npm install -g @tigrisdata/cli
tigris login oauth # choose "Sign in with Fly"
tigris access-keys list # find the key named after your bucket
tigris access-keys delete
```
**Preview:** these removal steps have not yet been followed on a brand-new account. Fly may leave a record of the deleted bucket, or the app's private network, behind.
{/* PENDING LIVE EVIDENCE (A1, L4): these removal steps, including deleting the access key above, are what L4 cleans up with. Check afterwards whether Fly leaves a deleted bucket's record or the app's private network behind, and say so here if a person would see it. */}
## Get help [#get-help]
* `dorkos community deploy --help` lists every option.
* The [manual Fly recipe](https://github.com/dork-labs/dorkos/blob/main/apps/community/FLY.md) explains each piece setup creates, for when you need to fix something by hand.
* The [operations guide](https://github.com/dork-labs/dorkos/blob/main/apps/community/OPERATIONS.md) covers running a space server day to day: mail, limits, keys and recovery.
* Something went wrong, or a step here was unclear? [Open an issue](https://github.com/dork-labs/dorkos/issues). Include what setup printed, but never your setup secret, passwords or keys.