Documentation

Everything you need to get around your box. Don’t have an account yet? 👉 Sign up first.

Logging in

ssh -p 2222 <user>@mbox.blue

You’ll land straight inside your own box as root (of your container — you can’t touch anyone else’s). Your home directory is /root.

Persistence

Your box keeps running between logins. Disconnect whenever you like and SSH back in later — your files and any background processes are still there.

💡 To keep interactive programs running across disconnects, use tmux: start it with tmux, detach with ^b d (CTRL + b, then d), and re-attach next time with tmux attach.

Re-entering your box

Re-entering is just logging back in:

ssh -p 2222 <user>@mbox.blue

You can also be explicit:

ssh -p 2222 <user>@mbox.blue attach

Depending on your SSH client you may see the input device is not a TTY, in which case pass -t to force a terminal:

ssh -t -p 2222 <user>@mbox.blue attach

Running one-off commands

You can run a command without opening an interactive shell:

ssh -p 2222 <user>@mbox.blue uptime

The command runs directly (no extra shell), so if you want pipes or redirection, wrap it yourself:

ssh -p 2222 <user>@mbox.blue sh -c 'ls -la | head'

Your web presence

A static page — anything in ~/public_html is served, with HTTPS handled for you, at both https://<you>.mbox.blue and https://mbox.blue/~<you>:

mkdir -p ~/public_html
echo '<h1>hello from my box</h1>' > ~/public_html/index.html

A web app — run a server on a port inside your box, then tell mbox.blue which port to publish. That port then takes over https://<you>.mbox.blue (instead of your static page):

# e.g. a quick static server on :8080
cd ~/public_html && python3 -m http.server 8080 &

# publish port 8080
mkdir -p ~/.mbox && echo 8080 > ~/.mbox/expose

Your app appears at https://<you>.mbox.blue within a few minutes (or right away on your next login). Remove ~/.mbox/expose to fall back to serving your ~/public_html there again. Use tmux to keep your server running after you disconnect.

Plain HTTP (no forced redirect) — by default your box is served over HTTPS and any http:// visitor is redirected up to it. If you’d rather also serve over plain HTTP without that redirect (e.g. for a client or webhook that can’t do TLS), create an empty flag file:

touch ~/.mbox/no-redirect

This applies to both https://<you>.mbox.blue and any custom domains below; HTTPS keeps working as before, you just also get plain HTTP. Remove the file (rm ~/.mbox/no-redirect) to restore the default redirect.

PHP — your box ships with PHP (CLI + FPM), the common extensions (PDO/MySQL/SQLite, mbstring, gd, curl, intl, …) and composer, so you can run PHP sites and apps. Two ways:

Serve ~/public_html as PHP, hands-off. Create the flag file and drop .php in your web root:
```
touch ~/.mbox/php
echo '<?php echo "hello from ".gethostname();' > ~/public_html/index.php
```
Your ~/public_html is then served with PHP at https://<you>.mbox.blue (static files still work). PHP runs inside your box, so keep your box running; rm ~/.mbox/php returns to plain static serving. If you set ~/.mbox/expose (below), that takes precedence.

Run a PHP app on a port (frameworks, a full app), then publish that port just like any other app:

cd ~/public_html && php -S 0.0.0.0:8080 &   # or: php artisan serve, etc.
mkdir -p ~/.mbox && echo 8080 > ~/.mbox/expose

For your safety we never serve .php files as raw source. So until you enable PHP, a .php file in ~/public_html returns 404 (not its source) — if you dropped one in and it 404s, that’s the reason: run touch ~/.mbox/php. PHP only ever runs via the box, so any .php requested from the static https://mbox.blue/~<you> path always returns 404. If you enabled PHP on a box created before PHP was added, recreate it once to pick up the new tools: ssh -p 2222 <you>@mbox.blue destroy, then log back in.

Your own domain — you can serve any of the above on a domain you own, with HTTPS handled for you. It takes three steps:

List the domain. Put one hostname per line in ~/.mbox/domains:
```
mkdir -p ~/.mbox
echo www.example.com >> ~/.mbox/domains
```
Each listed domain serves your app if you’ve set ~/.mbox/expose, otherwise your ~/public_html.
Prove you own it. Add a TXT record at your DNS provider so we know the domain is really yours (replace <you> with your username):
```
_mbox.www.example.com.   TXT   "mbox-verify=<you>"
```
Point it at us. For a subdomain use a CNAME; for a bare/apex domain use an A record (CNAME isn’t allowed at the apex):
```
www.example.com.   CNAME   <you>.mbox.blue.
example.com.       A       <the mbox.blue host IP>
```

Once the TXT record is in place and the name points at us, your site comes up on https://www.example.com automatically — we obtain the certificate on the first visit. We only ever serve and request a certificate for a domain whose TXT record names you, so nobody else can claim your domain (or one of ours). DNS changes can take a little while to propagate; if it’s not up yet, give it a few minutes. Remove the line from ~/.mbox/domains to unpublish.

Handy commands

A few extras are baked into your box:

me — a snapshot of your box: your public URL and your current usage (memory, processes, CPU, disk) against your limits.
finger <user> — see what another member is up to (their ~/.plan). With no argument it fingers you.
free, uptime — the usual, reporting your box’s limits.

Say who you are

Tell the rest of mbox.blue what you’re up to: drop a few free-form lines in ~/.plan and a one-line summary in ~/.project.

echo "Tinkering with a small Gopher server. Say hi!" > ~/.plan
echo "building a gopherhole" > ~/.project

Anyone can then finger <you> from their box, run finger <you>@mbox.blue from another system, or click your name on the members page.

Meet the others

mbox.blue is a shared world; here’s how to find each other:

Members — everyone with a box. Click a name to visit their page, or click a row to finger them.
Guestbook — leave a note for passers-by.
Status — a live look at the host: uptime, load, and who’s online right now.
Webring — once you have a page, paste the webring snippet (from the members page) so visitors can hop between member sites.

Resetting your box

To get a fresh box (for example to pick up a newer image), destroy the current one and then log back in:

ssh -p 2222 <user>@mbox.blue destroy
ssh -p 2222 <user>@mbox.blue

Lifecycle commands

Special words you can pass when logging in to manage your box:

status — report whether your box is running.
attach — (re)enter your box with a shell (the default when you log in).
destroy — tear your box down; a fresh one is created on next login.

💡 Most commands can be shortened to their first letter, e.g. s for status. A periodic reaper cleans up any stopped boxes every few minutes.