Skip to content
Skills Library
DevOps & cloud · Automation

hostel-server-setup

/hostel-server-setup

Set up, configure, back up, or update a Hostel server on a Linux VPS or a home machine. Use it when the user says "set up a Hostel server", "deploy hostel", "run hostel server", "put Hostel behind Caddy/a proxy", "change a server setting", "server.toml", "back up Hostel", or "update the server".

Repository
hostel ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
5
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Set up, configure, back up, or update a Hostel server on a Linux VPS or a home machine. Use it when the user says "set up a Hostel server", "deploy hostel", "run hostel server", "put Hostel behind Caddy/a proxy", "change a server setting", "server.toml", "back up Hostel", or "update the server".

Triggers from the description

set up a Hostel serverdeploy hostelrun hostel serverput Hostel behind Caddy/a proxychange a server settingserver.tomlback up Hostelupdate the server
Original author description

Set up, configure, back up, or update a Hostel server on a Linux VPS or a home machine. Use it when the user says "set up a Hostel server", "deploy hostel", "run hostel server", "put Hostel behind Caddy/a proxy", "change a server setting", "server.toml", "back up Hostel", or "update the server".

How it works

  1. 1. Choose the machine and the TLS mode
  2. 2. Install
  3. 3. Initialize
  4. 4. Edit server.toml
  5. 5. The systemd service
  6. 6. The configuration in the database
  7. 7. Invites on the server machine
  8. 8. Backups
  9. 9. Update
  10. Next
Original SKILL.md headings · 249 lines, 1,344 words
SKILL.md preview
---
name: hostel-server-setup
description: Set up, configure, back up, or update a Hostel server on a Linux VPS or a home machine. Use it when the user says "set up a Hostel server", "deploy hostel", "run hostel server", "put Hostel behind Caddy/a proxy", "change a server setting", "server.toml", "back up Hostel", or "update the server".
---

# Set up a Hostel server

The server keeps the queue, the users, the configuration, and the SSH gateway.
Run one server for a team. Agents and people connect to it from their own
computers (`hostel-install`).

## 1. Choose the machine and the TLS mode

- A Linux machine with systemd (amd64 or arm64; 2 CPUs and 4 GB are enough), or
  a home machine that stays on. The repository documents only the systemd
  service; on another OS, run `hostel server run` with your own service manager.
- One HTTPS address that clients can reach. The API and the gateway share it:
  the gateway accepts SSH inside a WebSocket on `/v1/gateway`.

| TLS mode | Use it when | Clients check |
|---|---|---|
| `self-signed` (default) | No domain or no proxy: an IP address, a LAN name, a VPN name. The server serves HTTPS with its own certificate. | The pinned key from the invite code. |
| `off` | A proxy with TLS is in front of the server (Caddy, a cloud load balancer). | The proxy's certificate, in the normal way. |

## 2. Install

As an administrator on the server machine:

```sh
curl -fsSL -o install.sh https://raw.githubusercontent.com/csansoon/hostel/main/install.sh
sudo sh install.sh --dir /opt/hostel/bin --server /opt/hostel
sudo chown -R alice /opt/hostel          # the user that runs the service
sudo ln -sf /opt/hostel/bin/hostel /usr/local/bin/hostel
```

`/opt/hostel/bin/hostel` is the server binary. The service's user owns
`/opt/hostel`, so that an admin can update the server from the app or from a
computer (section 9). `/opt/hostel/helpers` gets the binaries for all machines (`hostel-<os>-<arch>`,
`mise-<os>-<arch>`). The server uses the tools in its binary: the install
script does not copy tool definitions.

## 3. Initialize

Run `hostel server init` as the user that runs the service (not root). In a
terminal it asks for the server name, the addresses, and your name when the
flags do not give them. Flags:

| Flag | Meaning |
|---|---|
| `--server-id` | The server's name, `[a-z0-9]{1,20}` (default: from the host name). It is part of the names of machines that the server creates. |
| `--listen` | The API address (default `127.0.0.1:7410`). |
| `--tls` | `self-signed` (default) or `off`. |
| `--url` | An address that clients use. Repeat it for several. Invite codes contain them. |
| `--user` | Your name, for the first admin. |
| `--helper-dir` | The binaries for the machines: `/opt/hostel/helpers` after `install.sh --server /opt/hostel` (default: `data_dir/helpers`). |
| `--config` | The file to write (default `~/.config/hostel/server.toml`). |

Self-signed, on its own port (open TCP 7410 in the firewall):

```sh
hostel server init --server-id demo --listen 0.0.0.0:7410 \
  --url https://hostel.example.com:7410 --user "Alice Example" \
  --helper-dir /opt/hostel/helpers
```

Behind a proxy with TLS:

```sh
hostel server init --server-id demo --tls off --listen 127.0.0.1:8000 \
  --url https://hostel.example.com --user "Alice Example" \
  --helper-dir /opt/hostel/helpers
```

With `--tls off` and an `https://` address, `init` also writes
`gateway_public = "wss://hostel.example.com/v1/gateway"`: guests and joined
machines reach the SSH gateway through the proxy. The proxy must forward
`/v1/gateway` (a WebSocket) to the server.

`init` writes `server.toml`, `hostel.schema.json`, the data directory
(`~/.local/share/hostel`: the database, `server_ed25519`, `gateway_host_ed25519`,
and the TLS certificate), and prints the server's SSH public key and the first
admin invite:

```
Connect your computer as the first admin. Run this on your computer:

  hostel connect hostel1-...
```

Run that command on your own computer within 24 hours (`hostel-install`).

## 4. Edit `server.toml`

`server.toml` has only the keys that the server needs before it opens its
database: `server_id`, `listen`, `gateway_listen`, `gateway_public`, `tls`,
`public_urls`, `data_dir`, `helper_dir`. A `platforms_dir` key (written by
the install script before M10e) is ignored with a warning: delete it. `init` writes
`helper_dir` (with `--helper-dir`) and, behind a proxy, `gateway_public`. Check
them:

```sh
grep -E 'helper_dir|gateway_public' ~/.config/hostel/server.toml
hostel admin config check
```

Without `helper_dir`, the server cannot give machines their helper, and `hostel
machine join` cannot download the binary. Without `gateway_public` behind a
proxy, every guest SSH session and every joined machine fails.

A Caddy example (Caddy passes WebSocket upgrades without more settings):

```
hostel.example.com {
	reverse_proxy 127.0.0.1:8000
}
```

With `tls = "self-signed"`, the default `gateway_public` is `/v1/gateway` on the
same address; do not set it. Check the file (it prints each problem and the
effective values):

```sh
hostel admin config check
```

A change of `server.toml` needs a restart of the server.

## 5. The systemd service

`/etc/systemd/system/hostel.service` (replace `alice` with the user that ran
`init`):

```ini
[Unit]
Description=Hostel server
After=network-online.target
Wants=network-online.target

[Service]
User=alice
ExecStart=/opt/hostel/bin/hostel server run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```sh
sudo systemctl daemon-reload
sudo systemctl enable --now hostel
journalctl -u hostel -f
```

`hostel server run --config <file>` selects another `server.toml`. The log is
JSON on stderr. If the configuration is invalid, the server does not start and
the log says why.

For Namespace machines, the `devbox` and `nsc` CLIs must be on the service's
`PATH` (`hostel-machines`, section "Namespace").

## 6. The configuration in the database

Everything else (providers, machines with their tools, and the settings) is the
configuration document in the database. An admin changes it from any
connected computer. A valid change applies at once, without a restart.

```sh
hostel config                    # show the document (members see secrets as ***)
hostel config edit               # change it in $VISUAL / $EDITOR
hostel config apply file.toml    # replace it with a file (or - for stdin)
hostel config history            # the revisions, with user and time
hostel config settings           # the settings that are not defaults
hostel config settings set idle_timeout=20m
```

Settings: `idle_timeout` (10m), `poll_timeout` (5m), `limit_retry` (2m),
`port_process_offline` (10m), `intervals.scheduler` (10s),
`intervals.reconcile` (5m), `intervals.tunnel_check` (30s),
`intervals.presence` (30s), `mise.idiomatic_tools` (`["node", "python"]`),
`mise.github_token`, `mise.agent_device` (true).

The server refuses a change if another revision came first (edit again) or if
it is invalid (the error names the key path). Machines and providers:
`hostel-machines`. Tools: `hostel-tools`. Users: `hostel-users`.

## 7. Invites on the server machine

If nobody can sign in as admin, make an invite on the server machine itself (it
does not use the API):

```sh
hostel server invite                     # an admin
hostel server invite --role member --name "Bob Example"
```

## 8. Backups

The state is in the data directory (`~/.local/share/hostel`). Back up the keys
once (`server_ed25519`, `gateway_host_ed25519`, `tls_cert.pem`, `tls_key.pem`).
Back up the database with SQLite, not with a file copy:

```sh
sqlite3 ~/.local/share/hostel/hostel.db ".backup /var/backups/hostel.db"
```

- A lost database: users must connect again; on-demand machines with this
  `server_id` are destroyed at the next reconcile.
- A lost `server_ed25519`: put the new public key (`hostel admin pubkey`) on each
  static machine.
- A lost TLS key (self-signed): each client must connect again with a new
  invite code.

## 9. Update

From v0.2.0, the server updates itself. Each way checks the signature of the
release, replaces the server binary and the machine binaries in `helper_dir`, and
refuses a release that is not newer. The server sends the new helper to each
machine before its next lease.

- **From the app** (an admin): Front desk › This server › Update the server shows when a
  newer release exists. The server starts again by itself with the new binary.
  Leases and their jobs continue; a `hostel run` that streams output at that
  moment loses the stream (`hostel attach <job>` continues it).
- **From a connected computer** (an admin): `hostel server update --remote`.
  It waits until the server runs the new version.
- **On the server machine**, as the service's user (or with `sudo` when that
  user cannot write the files), then restart:

  ```sh
  hostel server update
  sudo systemctl restart hostel
  ```

A remote update needs that the service's user can write the binary's directory
and `helper_dir` (section 2); otherwise it fails with "this user cannot write
…". `--version vX.Y.Z` selects a release. A server before v0.2.0, or one
installed in `/usr/local/bin`: install again, then restart:

```sh
curl -fsSL -o install.sh https://raw.githubusercontent.com/csansoon/hostel/main/install.sh
sudo sh install.sh --dir /opt/hostel/bin --server /opt/hostel
sudo systemctl restart hostel
```

Machines that joined from behind NAT run their own copy of `hostel` for the
connection: the app shows "Out of date" on them (`hostel-machines`).

## Next

- Add machines: `hostel-machines`.
- Invite people: `hostel-users`.

Versions

The database has no other skills named hostel-server-setup.

Database snapshot: 13.11.2026 · package version 2557acdb08ec (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100hostel-use
    Use a Hostel machine from a repository - acquire a lease with the tools that you need, run builds and tests, sync files, take screenshots, open tunnels, and release. Use it when the user or agent says "build the Android/iOS app", "run the tests on Windows/Linux/macOS", "QA on…
  • 90hostel
    The entry point for Hostel. Use it when the user mentions Hostel, machines, leases, or "a remote Mac/Windows/Linux machine for my agent", and you must find the skill for the task (install, set up a server, add a machine, add a tool, invite a coworker, use a machine, fix a problem).
  • 90install-open-mail-server
    Installs Open Mail Server on a Linux VPS over SSH. Asks for the server host, username, and password, installs Docker when it is missing, copies this project and its Compose file, and starts the container. Use when the user asks to install, deploy, or set up Open Mail Server on a…
  • 100coolify-vps-baseline
    Prepare a Linux VPS to run production containers under Coolify. Use when setting up a new server, auditing an existing one, or connecting a registry, firewall, proxy and monitoring before the first deploy.
  • 100margin-setup
    Install Margin and set up a private hub (docs where many people and many AI agents write together) on the user's own machine, their VPS, or their Cloudflare account, then connect Codex / Claude Code agents to it. Use when the user wants to install, host, deploy, invite people…
  • 100vps-panel-3xui
    在一台 Linux VPS 上全自动部署、重装或迁移 3x-ui(x-ui)代理面板——SSH 探测、非交互安装、验收、备份数据库、凭据落盘一次做完。当用户提供 VPS 的 IP / SSH 端口 / root 密码,并说"搭面板""装 3x-ui""节点面板""重装面板""续费后恢复面板""帮我配代理服务器"时使用;也用于排查面板打不开、密码登不上、端口不通、HTTP/HTTPS 协议混淆等问题。

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.