# Start here --- # Operate a Peios machine _Peios / Using Peios / Start here_ > Start with the task you need to do — install Peios, complete first boot, sign in, manage the machine or investigate a problem. Use this guide to get a Peios machine running and look after it. You can use the desktop in a browser or the command-line tools on the machine. Start with the task you have now; you do not need to read the kernel or protocol manuals first. ## Install and sign in 1. **Install Peios.** [Install on a PC](/peios/using-peios/installing-peios/on-a-pc.md) covers the live medium, connecting to the installer and choosing a destination disk. Read the disk-erasure warning before continuing. 2. **Complete first boot.** [First-boot setup](/peios/using-peios/disks-and-filesystems/first-boot-setup.md) sets the machine's identity, network and initial administrator account after an installation through the graphical or text installer. 3. **Open the desktop.** [Sign in from a browser](/peios/using-peios/signing-in-from-a-browser/open-the-desktop.md) explains how to reach the machine and check its certificate before entering credentials. For manual disk preparation and the legacy `peios-install` script, use [Installing to disk](/peios/using-peios/disks-and-filesystems/installing-to-disk.md). That route has different account and first-boot behavior; follow the instructions for the installer you actually used. For a local console or SSH session, see [Sign in](/peios/using-peios/signing-in/overview.md). ## Do everyday work - [Manage the machine](/peios/using-peios/operating-peios/manage-the-machine.md): accounts, software, services, networking, storage and configuration. - [Set up your desktop](/peios/using-peios/desktop-settings/overview.md): wallpaper, clock, dock, shortcuts and default applications. - [Troubleshoot a problem](/peios/using-peios/operating-peios/troubleshoot-a-problem.md): find the relevant state and records before changing anything. ## Understand permissions when you need them Peios tools act with the authority of the account running them. A desktop app does not grant extra rights simply because it offers a button. Machine-wide settings are commonly restricted to Administrators; the individual task guides say what access is needed. If an action is denied, start with the task's permissions section. Use [Security fundamentals](/peios/security-fundamentals.md) when you need to understand identities, privileges and access rules in more detail. ## Find technical documentation - [Peios technical reference](/peios/advanced-peios.md) contains technical reference manuals, specifications and implementation reference. - [Developing for Peios](/peios/developing-for-peios.md) covers building and shipping software, the SDK and developer tools. The event and command references remain available from Using Peios for looking up an event you have seen or a command you are about to run. --- # Manage the machine _Peios / Using Peios / Start here_ > Choose the desktop app or command-line guide for accounts, software, services, networking, storage and machine configuration. Choose the task below. The linked guides explain the controls, required permissions and how to check the result. Use the machine-wide settings only when you intend to affect everyone who uses the machine. ## Accounts and desktop settings [Manage local accounts and groups](/peios/using-peios/managing-local-principals/overview.md) collects the account tasks and access precautions in one place. - **Create an account or change local membership:** [Principals Manager](/peios/using-peios/managing-local-principals/principals-manager.md) on the desktop, or [Creating accounts](/peios/using-peios/managing-local-principals/creating-accounts.md) and the [`lps` reference](/peios/using-peios/managing-local-principals/lps-command.md) in a terminal. - **Sign in remotely from a terminal or manage SSH keys:** [Signing in over SSH](/peios/using-peios/signing-in/signing-in-over-ssh.md). - **Change your own password:** [The `passwd` command](/peios/using-peios/signing-in/the-passwd-command.md). - **Change your own desktop:** [Desktop Settings](/peios/using-peios/desktop-settings/overview.md). - **Set defaults for everyone or change how the desktop is served:** [Settings for all users](/peios/using-peios/desktop-settings/for-all-users.md). Changing the listen address can disconnect open desktops; an overlay prevents normal sign-in while it is set. ## Software - **Find, install or remove a package:** [Package Manager](/peios/using-peios/package-management/package-manager.md) on the desktop, or [Installing and removing packages](/peios/using-peios/package-management/installing-and-removing.md) in a terminal. Review the plan, including dependencies, before applying it. - **Update or undo a package change:** [Keeping a system current](/peios/using-peios/package-management/keeping-a-system-current.md). - **Set up or enable a feature delivered by a package:** [Feature Manager](/peios/using-peios/features/feature-manager.md). Installing a package puts files in place; feature setup is a separate action. [Remove a feature before its package](/peios/using-peios/features/overview.md#when-its-package-is-removed), while the scripts needed to undo its setup are still available. - **Handle an interrupted package operation:** [Transactions and recovery](/peios/using-peios/package-management/transactions-and-recovery.md). Feature operations have their own [interrupted-state guidance](/peios/using-peios/features/overview.md#interrupted). ## Services and running programs - **Inspect, start, stop or restart a service:** [Controlling services](/peios/using-peios/services-and-jobs/controlling-services.md). - **See running programs, resource use and jobs:** [Task Manager](/peios/using-peios/threads-and-processes/task-manager.md). - **Read a service's output:** [Event Viewer](/peios/using-peios/logs-and-events/event-viewer.md) or [Service output and logging](/peios/using-peios/services-and-jobs/output-and-logging.md). - **Shut down or reboot:** [Shutdown](/peios/using-peios/services-and-jobs/shutdown.md). ## Network, time and storage - **Inspect connections or change network settings:** [Network Manager](/peios/using-peios/networking/network-manager.md), or [The `net` command](/peios/using-peios/networking/the-net-command.md) to inspect state and [Configuring profiles](/peios/using-peios/networking/configuring-profiles.md) to change configuration. Read the confirmation and rollback behavior before changing the network through a remote desktop. - **Allow or block a network service:** [Check and change network policy safely](/peios/using-peios/networking/network-policy.md#check-and-change-policy-safely). - **Set the time zone or clock:** [Time zone and setting the clock](/peios/using-peios/time/time-zone-and-setting-the-clock.md). - **Find software, configuration or service data on disk:** [Where files live](/peios/using-peios/disks-and-filesystems/filesystem-layout.md). - **Inspect disks and filesystems:** [Disk Manager](/peios/using-peios/disks-and-filesystems/disk-manager.md) is read-only. For changes, follow [Managing mounts](/peios/using-peios/mount-policies/managing-mounts.md), [Partitioning](/peios/using-peios/disks-and-filesystems/partitioning.md) or [Formatting with security descriptors](/peios/using-peios/disks-and-filesystems/formatting-with-security-descriptors.md). Partitioning and formatting can destroy data; follow the warnings in those guides before making changes. ## Configuration beyond the settings apps Start with [Find where a setting lives](/peios/using-peios/registry-concepts/find-a-setting.md) to locate its documentation and the component that reads it. Use [Registry Editor](/peios/using-peios/registry-administration/registry-editor.md) or [`reg`](/peios/using-peios/registry-administration/reg.md) for settings that require a registry change. Consult [`regman`](/peios/using-peios/registry-administration/regman.md) first: it explains what a key means, accepted values and when changes apply. A value being stored does not by itself prove the service accepted it. Follow [Change a setting and verify it](/peios/using-peios/registry-concepts/configuration-and-meaning.md) for the complete workflow. For configuration backup and recovery, read [Backup and restore](/peios/using-peios/registry-administration/backup-and-restore.md) before changing the registry's stores or layers. --- # Troubleshoot a problem _Peios / Using Peios / Start here_ > Start with the symptom, inspect state and logs, and follow the recovery guide for the affected service, network, sign-in or package operation. Start with what failed and when. Keep the error text and the name of the service, package, account or interface involved. Read the current state and relevant records before restarting a service, changing permissions or repeating an operation that changes the machine. For a reviewable event capture, follow [Save incident event evidence](/peios/using-peios/logs-and-events/save-incident-evidence.md). ## The browser cannot reach the desktop 1. Check the address and port against [Sign in from a browser](/peios/using-peios/signing-in-from-a-browser/open-the-desktop.md). A machine configured to listen only on `127.0.0.1` is not reachable from another device. 2. If the browser shows a certificate warning, follow [The machine's certificate](/peios/using-peios/signing-in-from-a-browser/the-certificate.md). Do not enter credentials when the certificate fingerprint does not match. 3. At a console you can still reach, use [`net status`](/peios/using-peios/networking/the-net-command.md) to inspect the address, link and readiness. Check the GXWI service, `gxwid`, through [Controlling services](/peios/using-peios/services-and-jobs/controlling-services.md). 4. If this happened during installation or first boot, return to that installer's guide. Network changes, reboot and completion of setup can change the address or what the browser shows. ## Sign-in is refused An unknown account and a wrong credential intentionally produce the same sign-in failure. Check that you are using an account on this machine and follow [Creating accounts](/peios/using-peios/managing-local-principals/creating-accounts.md) for local-account administration. Do not infer that an account is missing from the sign-in error alone. For an administrator investigating the failure, the [sign-in audit trail](/peios/security-fundamentals/authentication/overview.md#what-the-audit-trail-records) explains the authority's and local account service's events. Those records are available only to accounts permitted to read them. ## A service will not start, stops, or keeps restarting Use [Service troubleshooting](/peios/using-peios/services-and-jobs/troubleshooting.md). It covers configuration, identity, dependency and crash-loop failures. Inspect the service's state and its latest output before retrying: a running process is not always a ready or healthy service. In Services Manager, select the service and choose **Logs…** to open [Event Viewer](/peios/using-peios/logs-and-events/event-viewer.md) on its output, including hooks and health checks. Widen the time range if the failure is older than the default last 24 hours. ## Networking is missing or changed unexpectedly Use [Network Manager](/peios/using-peios/networking/network-manager.md) or [`net status`](/peios/using-peios/networking/the-net-command.md) to check the interface's verdict, selected profile, address, gateway and warnings. - **Not managed / IGNORE:** check which profile rule applies. - **A rejected configuration:** the last working rules can remain active; read the rejection before assuming the new settings took effect. - **An address but no route:** distinguish local connectivity from a route out of the machine. - **Addresses work but names do not:** follow [Name resolution](/peios/using-peios/networking/name-resolution.md). Make lasting changes through the supported network settings or registry profiles. Manual changes to a managed interface can be reverted by netd. Network Manager labels some firewall displays **Example data**; do not use those displays as evidence of live traffic. For the next check for your symptom, follow [Network diagnostic tools](/peios/using-peios/networking/diagnostic-tools.md#start-with-the-symptom). ## The clock or displayed time is wrong Start with [Keeping the time](/peios/using-peios/time/overview.md): inspect the effective time zone, clock state and source failures before changing the clock. A wrong time zone and an unsynchronised clock need different corrections. ## A write fails or a filesystem is full Keep the exact error and affected path. [Find why a filesystem is full](/peios/using-peios/disks-and-filesystems/diagnose-storage-pressure.md) distinguishes block space, inode pressure and incomplete directory measurements before choosing a supported remedy. Do not turn a permission or I/O failure into a deletion task without evidence. ## A package or feature change was interrupted For a package operation, follow [Transactions and recovery](/peios/using-peios/package-management/transactions-and-recovery.md) before starting another transaction. For a feature, follow [Interrupted features](/peios/using-peios/features/overview.md#interrupted); their recovery uses the feature's own lifecycle, rather than package transaction recovery. ## An action is denied, or records seem to be missing For a refused operation, follow [Debugging a denial](/peios/using-peios/inspecting/debugging-a-denial.md). Collect the failing operation, identity and required access before changing permissions. The task guide explains the access needed for that operation. Event queries omit records you may not read. Event Viewer can show whether its read policy hides records, or whether it could not read that policy. An empty list is not proof that nothing happened. Also check the time range and filters, and remember that logs are best effort. Follow [Find missing records](/peios/using-peios/logs-and-events/find-missing-records.md) to distinguish filtering, access, retention and collection failures. [What the machine records](/peios/using-peios/logs-and-events/overview.md) explains logs, events and metrics; [Event Viewer](/peios/using-peios/logs-and-events/event-viewer.md) explains filtering, older records and access notices.