start9labs/start-os

Open source Linux distro optimized for self-hosting

StartOS

Welcome to the era of Sovereign Computing

StartOS is an open source Linux distribution optimized for running a personal server. It facilitates the discovery, installation, network configuration, service configuration, data backup, dependency management, and health monitoring of self-hosted software services.

Running StartOS

There are multiple ways to get started with StartOS:

💰 Buy a Start9 server

This is the most convenient option. Simply buy a server from Start9 and plug it in.

👷 Build your own server

This option is easier than you might imagine, and there are 4 reasons why you might prefer it:

1. You already have hardware
2. You want to save on shipping costs
3. You prefer not to divulge your physical address
4. You just like building things

To pursue this option, follow one of our DIY guides.

❤️ Contributing

There are multiple ways to contribute: work directly on StartOS, package a service for the marketplace, or help with documentation and guides. To learn more about contributing, see here.

To report security issues, please email our security team - [email protected].

🌎 Marketplace

There are dozens of services available for StartOS, and new ones are being added all the time. Check out the full list of available services here. To read more about the Marketplace ecosystem, check out this blog post

🖥️ User Interface Screenshots

start-os's Issues

Unreliable Server Id's

Occasionally an Embassy will shed its original network id (start9-[xxxxxxxx]) and get a copycat id (start9-[xxxxxxxx]-[n]) in its stead. Causing it to be unreachable over the standard MDNS address.

Leading theory here is that the mdns Rmv events are not properly firing when a service is removed (by restart or expired DHCP lease).

We have not been able to reliably reproduce this as of yet.

Accept Pagination for logs endpoint

This is currently implemented with query params on the front end.

Web Sockets

Done: Web socket infrastructure in the front-end, consulate doesn't support websockets (so needs to be optional),

ETC

Implement a web socket API to allow ambassador-ui a better event driven architecture for state updates.

Make Synchronizers resilient to power failure

Done: Progress
Dependencies: None
Effort: 1 day (Keagan)

Automatic check for updates. Configurable.

Keep setting for autocheck for updates. Track dismissal per update. Do not force update.

Embassy Chime when backup action is complete

No audio feedback is provided for backup creation and restoration as of right now. This should change so that users have a better sense of whether or not these long-running actions are working properly and when they are complete.

Ensure Registration 209 returns necessary registration info

Currently Registration 209's return back the unit type. this is a problem because the FE cannot handle it. Return the same output that the registration endpoint would yield.

Consider system resources for packages

Resource requirements would need to be declared in the app manifest, and then analyzed by embassyd to determine whether something should be installed/started/etc.

Config rules should be definable as conditional upon various attributes of the system.

Example:

• 128 GB is insufficient for full archive node

• External Drives unlock archive support

• We want config rules to guide users towards correct configurations for both scenarios.

• Package needs to be able to query system for available resources

• TODO: scope the rest of this

App Config 'done' button inconsistency. Value's have 'done', but object, union, and list pages do not.

When dependencies are in transient state, Fix Dependencies on the dependent should be a different, transient state.

Has agent implications as well.

Remove expiration validation

We don't want clock skew to prevent setting up the device.

We could do monotonically increasing timestamps.

TBD: how to validate timestamp against reality

[Service UI] Properties Page Needs Warning when not running

UI Tweaks

-- Remove pull to refresh from AIL.
-- Maybe there should be a global 'refresh' in the menu, or by the menu. It would emphasize that you are refreshing your connection to the Embassy, not refreshing some particular data feed.
-- AIS, inner border of status should be fatter.
-- AIL the titles should be darker, or wider. Right now the contrast is too high for that font weight.
-- AIL experiment with matte background for each card, maybe w box shadow, instead of gradient.
-- Consider removing the card altogether
-- AIS We should add the lightbulb indicator
-- AIL Bulbs need to move a tiny bit left on mobile.
-- AIS Re-Add service name to top bar
-- AAS dependencies accordion button cut off.
-- AAS dependencies accordion rethink
-- AAS popovers with yellow background have weird border-radius mismatches

Take advantage of async

Add Web Manifest

https://developer.mozilla.org/en-US/docs/Web/Manifest

Password sometimes just doesn't work

Occasionally the password in the consulate just straight up doesn't work. Usually trying it a bunch of times fixes the issue but it's still painful.

It seems like it is also related to logging in after a long time of not using the application. Problem could be agent side as well. I'm cutting the ticket here though to track.

Launchable UIs (New Tab)

First iteration (0.2.8): launch UIs in a new tab.

• Backend add ui: boolean or ui: string | undefined to indicate presence of ui.
• Spinner disappears far earlier than iframe displays data
• .onion + Cups + Tor Browser : Error: No available storage method found.
• .onion + Cups + Tor Browser : Request to access cookie or storage on “http://qe6wucy3jw6mzvoo5n3mwp7z4tb2s4jtzidnq664muyettl2kvvxu7ad.onion/signin” was blocked because we are blocking all third-party storage access requests and content blocking is enabled.
• .onion + BAR + Tor Browser: ERROR Error: Uncaught (in promise): SecurityError: The operation is insecure.
• https .local + any + Chrome: Refuses to open at http. We actually need to disable this altogether over .local or open up stuff to .local
• .onion + any + Tor Browser + Logs in popover:

Error: No such container: null

Failed to Collect Logs from Docker

• any + RTL + any: password not copyable because not in properties
• .onion + Bitwarden + Tor Browser:

To protect your security, bowl7hqmhceuhtp32svusy6xtccobbf4p6xz4brfxj7af3trxjb5lwqd.onion will not allow Tor Browser to display the page if another site has embedded it. To see this page, you need to open it in a new window.

Bitwarden / has this response header causing the above problem: X-Frame-Options | SAMEORIGIN
See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy

Reconcile agent not depending on NTP when Tor does depend on NTP

This impacts the way that we handle the chime and how we specify systemd dependencies.

[Service UI] CSS selector for properties to make their way into the autofillable menu

If we are EVER in needs_config state, we should have a save button in config, just so we can get out of it.

Cross Compiler Support

Builds take too long and slow down development too much. We need a way to build the agent on a normal workstation while still targeting the RPi4. This could also theoretically unlock the ability to move past stack LTS-13.11 and GHC-8.6.3

Comprehensive treatment of transient states

We need to figure out all of the transient states we want and the asynchronous actions they imply.

Restyle the Marketplace

Done: Restyled
Info: Has categories, filters (needs tags), query parameters api,

Effort: 1 week

Dependency: (alongside) Categories and Tags

Refresh Leaf Certificates when they get close to expiration

Embassy Certificates expire after 365 days. They must be reissued before they expire. The system is capable of doing this automatically and should do so in the final 25% of the certificate's lifespan

All Services need passwords etc in properties

Upgrade to aarch64

Why?

• performance increase
• unlocks 64 bit applications
• GHC has official support for it which will improve build system workflows

Config property descriptions should support markdown rendering

Done:
Effort: 1 hr (Matt)
Dependency: None

Improve Internet Connectivity Check w/ way to inform user

We ripped out the internet connectivity startup check. We'd like to be able to diagnose connectivity issues independently of agent issues. We need a robust way to determine internet connectivity and a means of propagating that info to the user (probably sound)

Retain state of Services After Update (except if configuration is required)

Done: State of service is retained after update (if possible)
Effort: 2 days (Aiden)
Dependency: appmgrd

If a service is running when an update is requested it should be running after the update. This is impossible if it requires new config acceptance after the update, but should be possible in all other scenarios.

Fix appmgr verify

please

Registration sometimes takes unacceptably long time

Suspect is openssl random generation blocking.

Recovery Mode

When system fails to start up, make error server remains

AppVersion Sensitivity in Store App Response

GET /v0/apps/#AppId/store

needs to accept an optional query param version: full semantic version. If query param not present, give latest. If asked for package is not present 404

Periodically restart tor if agent cannot reach itself over tor

Tor seems to have weaknesses around network interface changes as well as circuits dying. The agent should be able to detect when it is unreachable over tor and either restart tor itself or delegate this action to appmgr

list of enums with subheadings in app-config

has appmgr implications

Update Compatibilty Matrix for Service version.

Done:
Effort: 3 days (Lucy)
Dependency: New Manifest Format

A service should be able to specify which versions it should be downgraded or upgraded too - and include the migrations to those services

Downgrading is an operation that is not necessarily supported in general by applications.

Service Worker File Caching

https://developers.google.com/web/ilt/pwa/caching-files-with-service-worker
https://developer.mozilla.org/en-US/docs/Web/API/Cache

• cache static assets on first load
• clear cache when update is clicked

use icons from appmgr

Add icons to app bundles and installations

Done: app needs to store the icon in the S9pk and Registry needs to return the icon in the S9pk
Effort: 1 day (Aiden)
Dependency: New Manifest Format

UX around getting to a Service UI

As a user, when I run a service and wish to engage with its UI, I need to (1) copy the tor address from AIS, (2) leave AmbUI to paste it into a tor browser somewhere, (3) return to AmbUI to get the password (from config, or properties, or either), (4) leave once more and enter it into the service UI. I must know TO do all of this in the first place (heavy potential drop off on tasks 1, 3). I hypothesize this is a massive loss point for less savvy or more S9 skeptical users.

Solutions...

1. Open the service UI from AmbUI (consulate only?). Could preload the password?

Change password

Complicated because it has implications on creating and restoring backups. Also disk encryption.

New versions of all services that include updated specs and instructions. Bitcoin --> 0.20.1

Cors headers not "*"

Serve cors headers that don't use the "*" directive.

Handle AppMgr's dead zone between download and install during app updates

better local state management

appmgr loses a lot of performance refetching state it already has in memory. the decisions were made as they were to optimize for code reuse instead of performance. However, with a trait for accessing state, we can probably get the best of both worlds.

Eject Drives

• Need an eject endpoint on the backend to safely eject a USB drive
• Need a list view within /embassy tab 'Drives (n)' with a list of drives, along with buttons to eject them. (Probably an alert "are you sure you want to eject?")
• On successful backup completion, a success modal (see 'complete' ocmponent in the wizard) reusing the above UI for a single drive with an eject button, allowing someone to eject the drive they just backed up to.

Cache basic metadata for services even when not installed.

Registry requests are one of the most expensive external calls we can make when being queried for a piece of data. Reducing dependence on the registry will make response times faster and more reliable. As a result, we should speculatively cache certain lightweight data onto the agent for apps that have not been installed.

release notes spinner when refreshing dependency info

masking takes a second to load

do not use index for showing whether or not a list element was edited

Effort: 2 day (Aiden, timebox)
Dependencies: None
[Backlog]