About GroundSeg

This collection of documents describes the operation of GroundSeg, an open source application for managing Urbit instances ("piers") and related services.

GroundSeg is developed by Native Planet for our line of dedicated home Urbit servers, but GroundSeg can run on nearly any old PC you have lying around, including Raspberry Pi and very old computers. That said, we recommend using a dedicated device for GroundSeg, due to its elevated permissions.

GroundSeg ('GS') is fundamentally a container orchestration application with a friendly user interface. This means that GS runs other applications in containers, which are a bit like virtual machines. Each Urbit instance and the associated applications are run in their own containers. If you don't know what this means, don't worry! GS is designed to be friendly enough that you can ignore how it works.

The only requirements for installing GS on a computer are systemd and Docker, the latter of which will install automatically through the install script (sudo wget -O - get.groundseg.app|bash) -- typically, this means Debian-based Linux distributions, like Ubuntu and its derivatives. Native Planet also offers a Linux distro image with GS pre-installed, called ColonyOS, based on Linux Mint. GS is designed to run headless (i.e. not connected to a monitor), but ColonyOS includes a full desktop environment and works as a daily driver PC.

GroundSeg allows you to run multiple ships -- there's no hard limit, only the limits of the device it's running on. One of the innovations included in GroundSeg is StarTram, a custom networking backend system that allows you to access the ships and services running on your home network from anywhere without any manual networking configuration. The onboarding process for StarTram is as simple as entering a registration password. After you register, your GS device will automatically configure itself to forward its web interfaces to a preconfigured server that serves your ship interfaces over HTTPS. StarTram works for all of the ships you run on your device. StarTram is a managed subscription service (which comes for free with purchase of a device!), but an open source self-hosted version called Anchor is available for you to run on your own VPS if you prefer, with full feature parity.

GroundSeg also includes automatic self-hosted S3, allowing you to host images and media for your ships without any manual configuration -- you just click a button. If you've configured S3 before, this probably sounds much simpler than what you did before! Since our S3 service, MinIO, is hosted entirely on your device, your data remains on your own computer.

GroundSeg and StarTram contain many other features and conveniences. We encourage you to try it out and let us know what you think! We're always hanging around at ~nattyv/nativeplanet.

See you on the network!

Device setup

• Find a good spot for your Native Planet device to live. Your device can connect to your home network with a network cable, or by connecting to your wifi network. It should be placed somewhere within cable distance of your router, or within range of a strong wifi signal. You can connect a monitor and keyboard to your device, but it is not necessary for normal use or configuration.

• Before powering on your device, attach the antennas if you plan to use wifi. Do not attach antennas to a device that is already powered on, as it may damage the device. Power on your device and wait 2-3 minutes for it to start up. The Tellurian will automatically power on as soon as it is plugged in; you will need to push the power button on the Aurora to power it on.

  • If your device doesn't detect a network connection on boot, it will broadcast its own wifi network ("connect-to-connect"), which you can use to configure it to use your home wifi network.

  • On your phone or computer, open your wifi settings and connect to the NativePlanetConnect network using the password nativeplanet. Once connected, navigate to http://nativeplanet.local (not https) in your browser. Use the web interface to connect your Native Planet device to your home wifi network. Once connected to your home network, the device will stop broadcasting the C2C network.

• Once connected to the home network / internet, give the device ~5 minutes to update its software and restart. You will not be able to connect to the device until the update is complete.

• On a device on your home network, open http://nativeplanet.local (not https) in your browser.

• If you’re unable to open nativeplanet.local, try http://nativeplanet.localdomain.

If you’re still unable to connect, make sure you’re on the same wifi network and not using a VPN — try from another device if necessary.

Welcome to GroundSeg! You will be asked to set a password for your device and be presented with the device's control panel. From here you can boot a new ID, import an existing ID, and control general functionality for your hardware and any Urbit instances you run on this machine.

Booting your Urbit ID

Getting an Urbit ID

GroundSeg does not support comets. If you don’t already have a planet, reach out to us.

• Go to bridge.urbit.org and log in with your master ticket, or use your planet code if you have not already claimed it.

• Download your passport and keyfile from Bridge.

• In GroundSeg, select ‘Boot a new Urbit ID’, enter your ship’s name, and paste or upload the keyfile from Bridge.

If you already have a ship somewhere else that you don’t want to migrate to GroundSeg, you can still use it to spawn moons that you can run in GroundSeg. Use your moon’s key or keyfile the same way you’d boot a planet.

If you want another ID or don't already have one, you can follow this guide on urbit.org.

Using an existing ID

If you already have a running Urbit and you want to move it to your Native Planet device:

• Shut down your Urbit wherever it is running. (this step is crucial!)

• Export your pier.

  • If you are using a hosting provider, use their data export function

  • If you are self-hosting, compress your pier directory in a zip or tar file

• Upload your pier using the 'Boot an existing Urbit ID' option in the GroundSeg UI. Make sure the file you upload has the your ship's name as the file name (example: sampel-palnet.zip if your ship’s name is ~sampel-palnet)

Configuring StarTram & S3

StarTram is Native Planet’s remote access service, that allows you to access your home-hosted Urbit from anywhere with zero configuration. Unless you only plan to access your Urbit from your home network, you are going to need a StarTram subscription — 1 year of service comes free with the purchase of you Native Planet device.

Activating StarTram in GroundSeg

• Click on the 'Profile' menu in the upper right hand corner.

• Enter Your registration code, select a region, submit, and wait for it to complete.

• Select your ship's menu in GroundSeg. The 'Remote access' toggle will disable and enable remote access to your ship via StarTram. When ‘Remote’ is enabled, you can access your ship from anywhere using the address in the 'URL' button.

Configuring MinIO S3 (Only available with StarTram)

• In your ship’s settings, create a password for MinIO

• Click “Link to Urbit”

• You’re done! Enjoy sharing images and files hosted safely on your Native Planet.

SSH

Your box is accessible via SSH using the default username & password nativeplanet. We strongly recommend you change the default password!

• In a terminal: ssh nativeplanet@nativeplanet.local

• Log in with the password nativeplanet

• After logging in, run: passwd

• Set a strong new password

Booting a ship

GroundSeg allows you to boot a brand new ship, or upload one you've run elsewhere. You can find instructions for both below.

1. Boot a new Urbit ID
2. Boot an existing Urbit ID

Booting a new Urbit ID

If your ship has never been started before, use these instructions.

To boot a brand new ship, you need a keyfile. This is not the same thing as a master ticket!

Stars, planets and galaxies

To get your keyfile:

• Go to bridge.urbit.org and log in with your crypto wallet or master ticket.
• Click the 'OS' menu option:

• At the top of the OS menu, click 'Download keyfile':

Next, in GroundSeg, click the new ship + icon:

In the top text field, enter the @p (name) of your ship -- like ~sampel-palnet or ~wanzod (the ~ is optional).

In the bottom field, upload the keyfile you just downloaded, and click Create a new pier.

Voila! Wait a few minutes for initial bootstrapping, and you're ready to fly.

Moons

Moons are booted the same way, but you don't need to get a keyfile from Bridge. Spawn a moon from your ship by running |moon in the dojo, or by using an app like %houston, an Urbit app used for managing moons in a web interface (available at ~nodmyn-dosrux/houston).

When you run |moon, it will print a moon's @p and a long random-looking string in the dojo. Copy both of them, paste the @p in the top text field in the 'Boot a new Urbit ID' menu, and paste the long string into the bottom field. Then, click the 'Create a new pier' button.

Important note for macOS users

It has been reported that macOS may corrupt keyfiles downloaded from Bridge on disk due to the extension's association with the Keynote app. If you are using a mac, we recommend opening the keyfile in a text editor and pasting its contents into this text area instead of uploading the file.

Booting an existing Urbit ID

If you've already booted a ship and want to migrate it to GroundSeg, the process is very straightforward.

• On the device that was previously running your ship, turn the ship off -- sounds obvious, but it's worth double checking! Your ship may be damaged if you don't do this.
• Next, compress the pier directory. Navigate to the directory containing your pier -- e.g., if you type ls, you should be able to see the pier directory. Rename the pier directory to be the same as your planet (for example, mv myplanet sampel-palnet).
• If you're using Linux, the compress command might look like...

tar cvzf sampel-palnet.tar.gz sampel-palnet/

• In GroundSeg click the 'new ship' + icon in your dashboard, then the 'Import Pier' button:

• Proceed through the warning after double checking that your ship is shut off.
• Upload the archive you created here:

Note that the upload form supports .tgz, .tar, .tar.gz, and .zip files.

If your ship fails to boot, make sure that both the archive and the directory inside of it have the name of your ship!

Ship controls

This document describes the settings present in the ship controls menu.

1. Title
   • This shows the @p of your ship, and the version of Vere your ship is using.
2. System resources
   • This shows the amount of memory and disk usage your ship's container is currently reporting (refreshes every 10 seconds)
3. Power
   • Use the checkbox to save your ship's power status (e.g. restart a running ship on power reset). Use the toggle to turn your ship on and off.
4. Urbit Information
   • The 'Access Key' button will copy your +code login password to your clipboard when you click it. The 'URL' button will open your ship's URL in your browser -- either the .local URL if your ship isn't toggled to remote, or the remote StarTram/Anchor URL if it is.
5. Set Custom Urbit Domain
   • The custom Urbit domain field allows you to set a custom URL for your remote-toggled ship. See the custom domain guide for instructions on configuring a custom domain.
6. Minio
   • Copy Minio Password will copy your console password to allow you to login to the Minio console
   • Settings will take you to the Minio console URL (remote-only)
   • Connect to Urbit auto-configures S3 on your ship using the Minio settings
   • See the custom domain guide for instructions on configuring a custom domain.
7. Pack Pier
   • 'Pack & Meld' will immediately shut down your ship and perform a pack and meld, 'defragmenting' the memory arena.
   • 'Pack' will only perform an online pack
   • The calendar icon allows you to schedule recurring packs/melds
8. Remote Access
   • Switch the toggle to connect or disconnect your ship with StarTram and enable/disable the remote access URL
9. Developer Mode
   • This option allows you to SSH into the container your ship is running in and enter the CLI Dojo, at the expense of having logs printed
   • See Dev mode guide
10. Loom size
    • Your loom size is the maximum amount of memory your Urbit can use
    • Urbit use a default 2GB loom -- you can increase it if necessary, but probably shouldn't unless you have a specific reason
    • If your ship's loom exceeds the selected loom size, it will not boot successfully.

Developer Mode

Access your ship's console via SSH.

1. Start Developer Mode
2. Access The Console

1. Start Developer Mode

Switch the Developer Mode toggle

2. Access The Console

SSH into the Native Planet device

1. Open the Command Prompt/PowerShell (Windows) or the Terminal application (MacOS/Linux)
2. Type the following command: ssh nativeplanet@<hostname>.local
3. Press Enter and enter the password when prompted (default: nativeplanet)

Enter the Docker container

1. Type the following command: sudo docker exec -it <your-patp> tmux a
2. Enter the sudo password (default: nativeplanet)

Success!

Press ctrl-b followed by d to detach from your tmux session and return to the host device's shell.

Custom StarTram domains

1. Creating a CNAME
2. Custom domains for a ship
3. Custom domains for MinIO

StarTram supports custom domains for your ship. Instead of the gratis sampel-palnet.startram.io URL, you can easily use a subdomain for a domain you already own. You can also use your own domain for your MinIO S3 bucket’s public URL, so you can migrate your bucket without breaking your links.

1. Creating a CNAME

To make use of this feature, you’ll need a planet that is already registered with StarTram — make sure your ship can toggle to ‘remote’.

Go to your domain registrar’s website and find where you can manage DNS entries for the domain you want to use. You’ll need to create a CNAME record pointed at your default StarTram URL. If you’re creating CNAME for an S3 bucket, put an s3. in front of it, like s3.sampel-palnet.startram.io.

CNAMEs have to use a subdomain, so enter the subdomain as your entry’s name — for example, if you want to use urbit.example.com, use urbit for the entry. For the target, enter your ship’s startram.io URL — like sampel-palnet.startram.io, without https://. You may need to put a . at the end of your domain for it to work correctly.

2. Custom domains for a ship

In GroundSeg, open the settings for the ship you want to use from the main menu. Select your ship's card from the dashboard, enter your custom domain in the 'Custom Urbit Domain' text bar and submit.

3. Custom domains for Minio

Minio's custom domain field is located in the same ship card menu, directly underneath the ship's custom domain field.

If you get an error, try waiting a few minutes and trying again — DNS can be a little slow to update sometimes. Once you successfully submit it, your custom domain should be accessible immediately.

StarTram

StarTram is Native Planet's custom networking stack that lets you access GroundSeg from the public internet, even if it's hosted on your home network, with no technical configuration on your part. This document describes how to use the StarTram menu.

If you have already registered your device on StarTram, your menu will look similar to the above screenshot. Your current subscription information is described in the boxes:

Information

• Your Region is the region your StarTram subscription is set to.
• Your Expiration Date is the date that your StarTram subscription will expire.
• Plan will say 'Recurring' if you have an ongoing subscription -- your expiry date will automatically extend upon being billed.

The Region your StarTram is in is the physical location of the data center that you connect to. You should choose the location that is physically closest to you, in order to reduce latency.

You can use the New Key button to register your device using a registration code. If you are a StarTram subscriber, this is emailed to you upon your first payment. If you are using a self-hosted anchor, this is the password that you assigned when you were setting it up.

You can re-register with a new region if you decide to change it in the future.

Advanced options

Restart can be used to restart the Wireguard container on your GroundSeg device -- under unusual circumstances, this may be necessary to fix a broken connection.

The Edit Endpoint text field is used when you enter a new registration code. By default, this is api.startram.io, Native Planet's official StarTram service. If you are self-hosting anchor, you should set your custom domain here (e.g. api.anchor.mydomain.com).

You can use the cancellation field in this menu to cancel an ongoing StarTram subscription. Just enter your registration code and submit it -- your subscription will still be valid until the expiry date. You can also cancel it at nativeplanet.io/startram.

Settings menu

This document describes the options and features present in the system settings menu.

1. Connection
   • Use the toggle to enable or disable wifi if your device is supported
   • If wifi is enabled, you can select a network and enter the password here.
2. System Details
   • The 'Restart GroundSeg' button will restart the GroundSeg binary, not any of your ships or services.
   • The 'Use Storage for RAM' buttons will allow you to set the swap memory usage on your device
   • RAM, disk and CPU load and temperature are reported below
3. Power
   • Shut down or restart the host device using these buttons
4. System logs
   • You can view the GroundSeg system logs in with this button (also available in /opt/nativeplanet/groundseg/logs/<date>.log)
5. PenpAI
   • Enable experimental local LLM feature (see 'Apps' tab in the top menu if enabled)
6. Support
   • Use the 'Report bug' button to submit a bug report (see bug report guide
   • 'Netdata' is a tool for monitoring the GroundSeg host's analytics with in-depth reporting
   • Use the 'Twitter/email/Urbit' links to contact us for further support

Bug reports

This document describes how to use the Bug Report feature in GroundSeg.

Navigate to the Bug Report menu by going to your System menu, and scrolling to the bottom.

You can use the bug reports feature of GroundSeg to submit a collection of logs and system information to Native Planet for analysis. The optional "Deep Profile" option will send us a 30 second CPU profile to assist in debugging performance issues. Our devs will receive your report in their email and reach out to you with assistance as soon as they're able.

Native Planet takes privacy seriously, so we don't scoop up your ship's logs by default. You can manually select logs from any piers that you wish to include in your bug report. It will copy the last 1000 lines from the ship's logs (note that ships in dev mode do not save logs for GroundSeg).

Include a way to contact you, like your @p or email address, and any additional notes or context, like what exactly the problem you're having is. The more specific you are, the better.

Release channels

GroundSeg uses three release channels for its software:

1. The latest channel is the default, meant for public use. Almost everyone should be using this.
2. The edge channel is used for internal testing. You are welcome to use it, but it may have stability issues. You might be asked to switch to it for troubleshooting if you're having a problem.
3. The canary channel is the same as latest, except it uses a modified version of the latest tloncorp/vere image. If you want to run the testing versions of the Urbit binary, this is the option for you.

If you're unsure about which one to use, just stick with latest! The other two are for testing and may be unstable.

ssh nativeplanet@nativeplanet.local
<default password: nativeplanet>
sudo nano /opt/nativeplanet/groundseg/settings/system.json

Scroll down until you find the following line:

"updateBranch": "latest",

You can edit latest to edge, or canary, then run:

sudo systemctl restart groundseg

...and Groundseg will restart itself and download the appropriate packages -- this may take a minute or two.

You can switch back to latest any time -- however, you may run into issues if you boot a ship with a newer version of Vere (for instance, a test version on the canary channel) and try to go backwards by switching to latest. This is uncommon but worth bearing in mind.

You can see which version of Vere you're running in your ship's 'Advanced' menu: