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".
- Author
- csansoon ↗
- Repository
- hostel ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 5
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
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
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. Choose the machine and the TLS mode
- 2. Install
- 3. Initialize
- 4. Edit server.toml
- 5. The systemd service
- 6. The configuration in the database
- 7. Invites on the server machine
- 8. Backups
- 9. Update
- Next
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 协议混淆等问题。