First-party apps run as web projections in the browser's opaque sandboxed frames. Runtime checks each app's signed launch token and actor before it performs an effect. Home can currently obtain every app's capability, so a compromised Home can reach those apps' authority. The target limits Home to delegation and gives each app a separate, revocable capability. The WASM Component authoring path runs in Wasmtime with memory and fuel limits and Runtime Bus hostcalls.
Providers run as native operating-system processes with the Runtime user's rights. Only the model provider is partly confined. The trusted shell helper also runs as a native host process. The web Terminal is disabled by default; host developer mode and closed guest registration are required to enable it. An enabled Terminal runs commands with the host user's rights.
The data, keys and backups section explains current host access and the protection target for hosted and locked self-hosted Homes.
The isolation plan records the remaining gates. Source checks describe this source tree. Accepted installed proof binds the exact Runtime, components and app assets to the journeys tested on that device.
The installer looks up signed releases for Linux x86_64/aarch64 and macOS Apple silicon. Intel Mac and other OS families fail closed. The signed release determines which binaries exist for a given platform.
This checkout's installer combines installation, Home setup, and launch into one command:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bashDevelopers can use the Mac source guide for source-home staging and Browser VM work.
The installer needs curl and a working python3. On a Mac without Apple's
Command Line Tools, the installer opens Apple's installer for them. Click
Install in Apple's window; the ElastOS installer continues by itself when the
tools are installed. It waits up to 20 minutes, and Ctrl+C stops it. If it
stops, or there is no terminal, run xcode-select --install, wait for it to
finish, then run the install command again.
Setup and updates need outgoing UDP to port 4433 for Carrier.
Carrier uses mDNS by default to find other Homes on the same local network. It announces the Carrier node ID and local addresses. People Discovery controls signed Profile advertisements separately. Runtime checks Profile and message authority before it accepts Chat messages. Chat uses an encrypted Carrier connection.
To turn mDNS off, set ELASTOS_CARRIER_MDNS=0 in Runtime's environment before
starting it. Restart Runtime after changing this setting. Keep mDNS on for
automatic direct reconnection after a restart or local address change. Carrier
owns peer address resolution. See
Community availability for
the bootstrap and connection contract.
The installer detects the platform (Linux x86_64/aarch64 or
macOS Apple silicon), verifies the signed release, installs Runtime, and
fetches the Home profile from the trusted publisher. It
starts Home at http://localhost:8090/home/ and opens your browser. Keep the
terminal open while you use Home; Ctrl+C stops it. With no interactive terminal,
setup completes and prints the full command for opening Home later. On a Linux
computer with no desktop, such as a Jetson used over SSH, it prints the SSH
tunnel command for opening Home from another computer.
So that elastos is found in new terminals and after a restart, the installer
adds one line ending in # Added by the ElastOS installer to your login profile
(~/.zprofile for zsh, the default on macOS; ~/.profile for bash, the default
on Ubuntu, or ~/.bash_profile if you have one). It does this only when the
install folder is not already on PATH and the line is not there yet, and it
prints the file it changed. Set ELASTOS_NO_MODIFY_PATH=1 to skip it. To undo,
delete that line; --uninstall removes it too.
For automated provisioning, use --install-only:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bash -s -- --install-onlyELASTOS_INSTALL_ONLY=1 also selects bootstrap only. Test scripts use this
setting to own setup, launch, and cleanup; older installers ignore it and already
stop after bootstrap.
The current default Home exposes Assistant, Chat (Community), System, People,
Wallet, Documents, Library, Marketplace, and Inbox. On Apple Silicon
Macs it also exposes Browser. On supported Linux ARM64 computers with KVM,
Browser is optional; see Jetson for elastos setup --browser.
People is installed as a
separate app capsule; Home presents it but does not own its state or authority.
Native Windows is not an accepted install target today. The current product direction is a local Linux Runtime inside WSL2 with a small Windows launcher. See WINDOWS.md for the current Windows strategy and the later native-adapter boundary.
The installer URL bootstraps trust once. Later first-party setup and update operations use the trusted Carrier source by default. Users do not manage a release-head CID or gateway on the normal path.
elastos setup installs Home: the Runtime, its providers and the Home Apps.
Components that only some people need, such as the local model engine, arrive
on demand from the same signed release. The same install also provides the
separate operator runtime used by serve, remote node control, WASM or
microVM run, and non-interactive capsule work.
Data run needs no Runtime, and interactive packaged capsules use managed Home.
Only one live host may own an ElastOS data home at a time. Do not run Home and
the operator runtime against the same home at the same time. See the
command matrix for each command lane.
A clone contains source code and components.json. It does not create a
trusted source relationship. A binary built from the checkout can read it, but
it still needs a trusted source before fetching published components.
See Getting started
for an explicit source add example. Use the public installer when testing the
published install path.
The Home profile in this checkout includes Documents, Library, Kubo and the IPFS provider. Running an additional setup command for those components repeats the default selection. A published release uses its own signed manifest.
Add site-serving tools when operating a website:
# Local site preview
elastos setup --with site-provider
# Ephemeral public site edge
elastos setup --with site-provider --with tunnel-provider --with cloudflaredThe current elastos share and CID-backed site commands use the Runtime
content provider with a local IPFS backend. Kubo and the IPFS provider remain
dependencies of that CLI path. A reduced installation needs those components;
opening a shared document also needs Documents.
The release plan's Content/Carrier journey has separate acceptance checks. Installing the CLI backend establishes its prerequisites; cross-Runtime content delivery needs target proof. See Sites for the site commands and Content capsule distribution for the content contract.
elastos setup is an operator/bootstrap path for installing the selected
Runtime profile from a trusted release. It is not the product contract for a
Home content catalog.
Models already use Home Get. Open Marketplace → Models and choose Get: Runtime
checks the model against its signed catalog entry, downloads it and keeps it on
this device. Then open it in Assistant. Retry and Stop work on the same
row, and an interrupted download resumes by itself a few times first.
Getting other apps, games and data this way is not available yet. Until it is,
raw url entries and setup-only downloads remain operator provisioning
details, not Home catalog items. See
Content capsule distribution.
The installer detects Linux aarch64:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bashHome and chat use the ordinary user account. Browser uses the local Engine's
virtual machine on Apple Silicon Macs and supported Linux ARM64 hosts with KVM.
On Linux, Marketplace lists Browser with its setup command. To turn it on, run
elastos setup --browser in a terminal as the user who installed Home. The
command installs the signed Browser helpers, shows the host access changes and
asks for administrator approval. It then downloads and verifies the image with
progress. Close Home and start it again with elastos home --browser.
The Linux installer and ordinary elastos setup leave Browser preparation to
your choice until you enable it. Home lists Browser on supported Linux ARM64
computers; opening it before setup explains the command and restart. After you
enable Browser, ordinary setup refreshes its signed helpers and image during
updates. A later open repairs missing or changed helpers and prepares a missing
image on demand. Apple Silicon setup continues to prepare its helpers and image
before Home starts. The image
streams to disk with progress; a transfer stops after 30 seconds without data.
Runtime keeps the committed Browser profile separate from the image during
reopen and updates. Linux x86-64 keeps Browser hidden and retires helpers and
images from unsupported releases while preserving Browser profiles.
To remove Browser host access, close Browser and run this before uninstalling:
sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)"The Browser VM target documents the target contract and maintenance boundary. Scripts maps the executable proof commands.
Browser VM target maintenance is an operator path.
Refresh-only is not sufficient for package/dependency changes: rebuild the target and run
scripts/browser-vm-artifact-preflight.sh, including the complete
PipeWire/WirePlumber/GStreamer dependency set, before installation.
Home is created with a passkey, and the board needs none of its own. From a Mac or Windows computer, open an SSH tunnel to the board and keep it open:
ssh -L 8090:localhost:8090 user@boardOpen http://localhost:8090/home/ on that computer and create the passkey there
(Touch ID or Windows Hello), or on a phone or security key. The passkey belongs
to this Home at localhost, so sign in later through a tunnel the same way;
using the same tunnel and address, http://localhost:8090/home/, is simplest.
To use Home in the board's own browser, add a security key (USB) to your
account. It must be a FIDO2 key with a PIN or fingerprint. On the computer,
sign in through the tunnel, open System, choose Accounts and select Add passkey
(admins only). Confirm with your current passkey, then create the new passkey
on the security key. Then plug the key into the board, open
http://localhost:8090/home/ in the board's browser and select Use passkey.
Use localhost there too: the key does not work at 127.0.0.1 or at the
board's network address.
Updates are pull only. Nothing is pushed to your Home. The publisher's seed keeps the signed release, and your Home asks for it.
When Home checks. Home checks only while its System page is open. System asks every 5 seconds while it is visible (every 2 seconds while Home restarts) and every 30 seconds while it is hidden, and the Runtime reuses a check that is less than 30 seconds old. Home does not check when the Runtime starts, on a timer or when System is closed. Home itself shows no update badge yet; open System to see an update.
What a check does. The Runtime opens one Carrier connection to the trusted
source saved in sources.json during install. It asks for the latest signed
release head, fetches the head and the release by CID (a source that gives no
separate head CID sends the head file by name), and checks both signatures, the
release hash, the channel and the version order. An older
release is refused. The discovery_uri and ipns_name fields in
sources.json are shown but not used to find updates. If the Carrier
connection fails, the check fails.
What System shows. System shows the new version and its release notes.
Approve and restart. You approve the update with your passkey for that
exact release. The Runtime always downloads the new Runtime binary and
components.json by CID over Carrier. A capsule is downloaded only when its
signed record changed: the release lists one record per capsule archive
(name, capsule version, SHA-256, size, CID, signer), each signed on its own by
the publisher. Before any download the Runtime checks each record's signature
against the publisher DIDs in sources.json and that it matches the
capsule's entry in components.json; downloaded bytes must match the same
SHA-256 and size. The Runtime stages everything beside the running Home and
restarts Home. A download fails only after 30 seconds without data.
If it fails. If the new release does not start, the previous release is restored.
Terminal. From a terminal, check or install in place:
elastos update --check
elastos updateA terminal update or Undo leaves Home stopped, even if it was running before.
Start it again with elastos home --browser. An update from System restarts
Home by itself.
After install, the web is used only to look up the publisher's current Carrier
address from the gateways in sources.json; that answer is accepted only when
it matches the trusted source. Releases and components come over Carrier and are
verified by signature and hash.
Runtime keeps the verified signed pair in installation/release-head.json
and installation/release.json within its data directory. Publisher owns its
separate publication files. For an older installation, Runtime migrates the
signed pair after it verifies the trusted source, binary, components and installed
support under the installation lock. An interrupted transaction completes its
original recovery before that migration. If the saved pair requires repair,
keep the files in place and follow Runtime's operator repair step.
Running install.sh again uses the same installation lock and journal. Before it
stops Runtime, it restores an interrupted install and refuses an older release,
a channel a stable or canary Home does not follow (for example canary on a
stable Home), a pending Home update, a second writer and an installed Runtime
without a readable sources.json. A Home on another channel, such as the
retired jetson-test, can install a stable or canary release and then follows
that channel. Until an interrupted install is restored,
Home does not start and asks you to run install.sh again.
How releases get to the seed is in VERSIONING.md.
Use Undo if an update causes a problem and you need the previous release. Undo
is in the terminal only. Before an update, run elastos source show and save
the full Head CID: value. That command shows the current head; after the
update, it shows the new head. If it shows unknown, get the previous signed
head CID from the publisher.
To restore the previous release, run:
elastos update --rollback-to <previous head CID>Replace <previous head CID> with the saved CID. A plain update to an older
release is refused. Undo needs the network: it fetches the changed parts of the
previous release again by CID from the trusted source, so the source must be
reachable. Undo keeps your identity, accounts, and user data, including data
written after the update. A Home that joined the release Community
network stays joined, with its accepted revision, contacts, and messages. An
older release with no network pin, or with an older pin for the same network,
keeps the joined configuration in place. Leaving Community is a separate
action. To keep a Home out of Community, choose that before its first start
with elastos setup --isolated.
For a legacy Home, the first update to a new publisher key uses the installer's re-trust step. After that step, Undo accepts only heads signed by the current trusted key. A head signed by the former key is refused and the installation stays unchanged. Ask the publisher for a previous release signed by the current key if you need to recover across that first update.
On 2.0.0 and its test releases from 0.8.0-alpha.25, an update that stops partway keeps Home closed until it is recovered. Keep the installation files and data in place, and stay connected to the network Home updates over.
- Run
elastos home --browser. It finishes recovery of a System update. If it says to runelastos updateagain, the update was started withelastos update: runelastos update, thenelastos home --browser. Use this order also when System and a Home start name different commands; each command names the other when the recovery is not its own. - After a failed
elastos update, the nextelastos updateor Home start repairs this release's apps and providers from the publisher's seed. Without a connection to it, Home may not start until the connection is back. - Two cases are not repaired this way: an
elastos updatethat stopped while it was finishing, and a System update that stopped while it was replacing an app. The command a message names then stops with the same message every time. Do not delete or move any files. Ask for help in GitHub issues and include the output ofelastos --versionand the exact message. We are fixing this in a later update (#108).
A Home with an installed update controller keeps its controller Runtime and private receipt in the data directory. The controller of the version that runs the update owns its restart and recovery, so the steps below depend on that version.
From 2.0.0 (and its test releases from 0.8.0-alpha.18), if a Home restart was
interrupted, run elastos home --browser. It
hands recovery to that retained controller, which verifies its signed Runtime,
retained launch settings and saved release before it starts Home. When the
start of the restored previous release failed, the controller starts that
release again, at most twice per run, and clears the recovery files once Home
is ready. It never starts the failed new release again. Keep this terminal
open. Every Home start, with or without --browser, first or after an update,
gives its newly started Runtime up to 120 seconds to become ready. Each start
through the update controller appends its output under a header to the private
update-controller/runtime.log file, so a failed update start stays readable
after the rollback; a startup failure names that file.
On 0.8.0-alpha.16 and 0.8.0-alpha.17 (including an update from one of them to
2.0.0), an update or rollback start has a 30-second limit, each start replaces
update-controller/runtime.log, and elastos home --browser refuses a pending
restart. Set ELASTOS_RECOVERY_DATA to the data directory shown in the local
message and run the retained controller:
"${ELASTOS_RECOVERY_DATA}/update-controller/runtime" __update-controller \
--receipt "${ELASTOS_RECOVERY_DATA}/update-controller/receipt.json"If it reports that the previous Home start was already attempted, the previous
release is already back in place. Stop every elastos process of this Home and
move these files out of the way. Several have the same name, so make a folder
of your own with the subfolders bin, data and installation, and move each
file into the subfolder named below (keep them; do not delete them):
bin: from next to the installedelastosbinary,.elastos.update-journal.json,.elastos.update-stageand.elastos.update-rollbackdata: from the data directory,.elastos.update-stage,.elastos.update-rollback,.elastos.update-supportandupdate-controller/active-request.jsoninstallation: from the data directory'sinstallationfolder,.elastos.update-stageand.elastos.update-rollback
Then run the install command as the same user, with the same HOME (and on
Linux the same XDG_DATA_HOME) as this Home, and add
-s -- --install-dir <folder> when the elastos binary is not in
~/.local/bin:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bash. The installer
finds the data directory from HOME and XDG_DATA_HOME (it ignores
ELASTOS_RECOVERY_DATA). It installs the current release and runs
elastos setup, and keeps that data directory and its identity. Start Home
with elastos home --browser.
The receipt keeps Home paths, locale, desktop opener settings and Runtime launch bindings. It also retains the configured Wallet price API key, which Wallet reads from the environment. Other provider and Browser settings stay in their installed private configuration files. Keep the receipt's owner-only permissions and share only a safe error summary.
Home reuses a verified controller when its signed Runtime already matches. If a new controller cannot fit, ordinary Home can open with Home update controls unavailable. Free disk space before updating. An interrupted update or uncertain controller ownership keeps its recovery step.
Operators can install one known signed release head with
elastos update --head-cid CID.
The maintainer release DID is
did:key:z6MkgwHd2BCWe1jHMXPiR6H1q1RFPcv1YzhMbK5G1kBarbfe. Compare the
installer's Maintainer DID: line with the complete DID in the repository
README.
An existing Home with the old source pin refuses a release signed by the new
maintainer. On the Runtimes that still trust the old key, elastos update
reports one line:
Error: Signer DID mismatch: trusted set = ["<old DID>"], got did:key:z6MkgwHd2BCWe1jHMXPiR6H1q1RFPcv1YzhMbK5G1kBarbfe
Newer Runtimes add a second line: This release is signed by a new publisher key. Run the publisher's install.sh to trust it; this installation was not changed.
The trusted set shows your Home's current DID. To re-trust once, run the publisher's installer over the existing installation, using the same command as a fresh install:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bashThe installer trusts the new DID, installs the release and keeps your existing identity, accounts and user files. Later updates accept release signatures from the new DID and refuse signatures from the former DID. Homes that already trust this DID can use normal updates. Until you re-trust, Home still trusts the old key and remains exposed if a copy of that key exists.
| What | macOS | Linux |
|---|---|---|
| Runtime binary | ~/.local/bin/elastos |
~/.local/bin/elastos |
| Data directory | ~/Library/Application Support/elastos |
~/.local/share/elastos, or $XDG_DATA_HOME/elastos when set |
| Components | bin/, capsules/, tools/, libexec/, scripts/, browser-vm/image-set/, components.json, model-catalog.json and update-controller/ in the data directory |
same |
| Trusted sources and verified release | sources.json and installation/ in the data directory |
same |
--install-dir moves only the binary. Everything else in the data directory is
yours: identity keys, wallets, recovery material and user files. ElastOS adds
no login items, launch agents or desktop entries.
The installer adds one line to your login profile so new terminals find
elastos: ~/.zprofile for zsh; for bash, the first of ~/.bash_profile,
~/.bash_login or ~/.profile that exists, else ~/.profile; for other
shells, ~/.zprofile on macOS and ~/.profile on Linux. The line ends with
# Added by the ElastOS installer, and the installer prints which file it
changed. It adds nothing when the install folder is already on PATH or the line
is already there. To skip it, set ELASTOS_NO_MODIFY_PATH=1 when you run the
install command. A profile that is a link, has a second hard link or is not
your own file stays unchanged, and the installer prints the line for you to
add yourself. Uninstall does not change your profile: it prints the line to
delete and the file that holds it.
The publisher's signed manifest controls what elastos setup installs. Run
elastos setup --list to inspect the selected manifest's current profiles and
components before installation. The installed components.json records what
the selected profile installed. Do not infer parity with this development tree
from the version label or a successful setup. Install/update acceptance
owns exact public-manifest parity evidence.
curl -fsSL https://elastos.elacitylabs.com/install.sh | bash -s -- --uninstallThe installer stops this installation's Runtime the same way an install does:
it stops only processes whose ownership records and command match this
installation, and removes nothing if another process holds them. It then
removes the binary, the components (including the release scripts and the
Browser image), the trusted sources, the verified release and the PATH line the
installer added to your login profile. Your data
directory stays, including Browser profiles, so installing again continues with
the same identity. Pass the same --install-dir you installed with. An install
or update that is running or was interrupted stops the removal; finish it first.
On Linux, the administrator helper owns Browser host access. If you enabled it, close Browser and remove that access before uninstalling:
sudo /usr/bin/python3 -I /usr/local/lib/elastos/browser-vm-linux-network.py remove --user "$(id -un)"To delete your data as well, add --remove-data:
curl -fsSL https://elastos.elacitylabs.com/install.sh | bash -s -- --uninstall --remove-dataThis deletes your identity, wallets and recovery material on this computer. Keep your Recovery Kit first: it is the only way to restore that identity.
Runtime stores keys next to the data they protect in its data home. A full backup of that home contains all keys, including wallet keys. Protect the backup with the same care as the running Home. A Recovery Kit is sensitive recovery material; keep it under your own control.
Use hosted accounts only for public demos. Keep wallets, private data and recovery material on your own device until hosted protection passes its acceptance gate. The seed operator can read hosted data, wallet keys and recovery phrases stored on the seed. Host-side encryption with keys stored beside the data leaves those secrets accessible to that operator.
Passkeys control sign-in. Locking Home stops UI use; the Runtime account and root retain access to stored data and keys. The protection target covers hosted operators and root, and other software or OS users while a self-hosted Home is locked. An unlocked self-hosted Home trusts its owner and their host software. A stolen device or profile key requires a new identity.
Lost every passkey? Your Recovery Kit brings your account back on the same Home, even when guest accounts are off:
- On the computer that runs Home, as the user who installed it, run
the command shown on the sign-in screen, for example
elastos identity arm-owner-recovery --origin http://localhost:8090 --rp-id localhostfor the installed Home. It prints a code that works once and expires in 10 minutes. - On the Home sign-in screen, choose Recover this Home with your Recovery Kit. Enter the code, choose your Recovery Kit (and its password, if it has one), then create a new passkey.
- Home accepts only the Recovery Kit this Home saved for its admin. The new passkey becomes the admin and the old passkey stops working. Any other Kit, an expired code or a used code changes nothing. After five wrong codes the code stops working; run the command again for a new one.
Runtime validates and enforces capability tokens. The built-in shell evaluates the local approval policy for interactive and operator flows:
- In
climode, the terminal asks the operator to approve or deny each request. - In
agentmode, the shell grants only what the policy file'sallowlist matches. A missing, unreadable or malformed policy file denies every request.
The default policy file is
~/.local/share/elastos/policy.json. Set ELASTOS_POLICY_FILE to use a
different operator-managed file. With neither ELASTOS_POLICY_FILE nor HOME
set, agent mode denies every request.
elastos serve, and elastos run or elastos open for a data capsule, start
the shell in agent mode unless ELASTOS_SHELL_MODE is set (cli gives the
shell the terminal). ELASTOS_SHELL_MODE=auto grants every request; use it
only for local development.
The installer verifies:
- the
release-head.jsonsignature against the maintainer DID - the
release.jsonsignature against the same DID - the binary's SHA-256 checksum
Runtime setup then verifies components.json and each component. The web and
Carrier only carry bytes; signatures, hashes and the maintainer DID establish
trust.
For release and target handoff commands, see the runtime user story checklist and scripts index. Those commands are outside the normal install path.