# Setting up kody-os kody-os is a minimal private OS shell shared by humans and agents: one package, one shell, apps as JSON definitions in package storage. This guide is for the fork owner and their agent. It takes you, in order, from a copy of the package to a working OS with a first app installed. Each step has a check; do not skip the checks, because several failure modes look like a working setup until the check. The guide links to [Adding an app](../.agents/skills/adding-an-app/SKILL.md) for the app definition contract. It does not duplicate that contract. ## Before you start: visibility A private package has no listing and cannot be forked. For anyone to fork your package, it must first be made public by its publisher (the listing step in Kody), with a non-empty root `README.md` and `AGENTS.md`. If you are setting up a fork and cannot find a listing, the package is still private: that is a publisher-side step, not something the fork owner can do from their account. ## How sharing works in Kody's terms Use these words the way Kody uses them; they collide easily. - **Fork.** A copy of the package source into the adopter's own account, under the adopter's scope. A fork copies source only: no installed apps, no app state, no saved package settings travel with it. The new fork starts with empty storage. Updates from the original do not flow into a fork automatically. - **Install (one-click).** The human path in the Kody UI. Install forks the listing into your account and publishes it when the checks pass. If the checks fail, you get an inert fork instead (see below) and must publish it yourself. - **Agent lane.** An agent forks with `communityFork`, which copies the published source as an inert copy: nothing runs, and there is no saved package yet. A read-only safety review and a publish through a repo session follow before anything runs. - **Publish.** The step that turns a fork (inert source) into a running package in your account. Until the fork is published, the app does not run. - **Adopt.** A separate, owner-only step on the Settings page (`communityForkAdopt`) that gives a fork the owner's own access rights. Adopting installs nothing and is not the install. You do not need to adopt to set up kody-os; most fork owners never do. - **Clone.** A read-only git copy of the source onto a machine. A clone installs nothing into a Kody account. - **Use access.** Being granted Use access to someone else's package lets you use their running app. It is not owning a fork, and none of the setup steps below apply to it. ## Setup sequence Follow the steps in order. "Your agent" below means an agent connected to your Kody account with access to the fork. ### 1. Confirm the fork is published If you installed with one click, confirm the package is published in your account and the hosted app loads. If the fork is inert (source only, nothing runs), publish it through a repo session first; your agent can do the publish, but any approval Kody asks for in its UI is yours to give — never ask the agent to approve on your behalf. Check: the hosted app loads in a browser (even the 404 "Not found." page counts as loading — it proves the shell is serving). If it does not load at all, the fork is not published yet. ### 2. Confirm the registry is empty A fresh fork starts with empty storage: nothing is seeded, including no App Store. Ask your agent to run the package's `list_apps` export against the fork. Expect no installed apps. Check: `list_apps` returns no apps. If apps are already listed, you are looking at the wrong package (for example the original instead of your fork), or the fork is not fresh. Stop and sort out which package you are in before continuing. In the browser, the Apps page shows help instead of a list: two copy-paste prompts — one to install the App Store (ask your agent to run `install_from_catalog` for `app-store` with the catalog base `https://raw.githubusercontent.com/Hypercubed/kody-os/main/catalog/`), one to add your own apps — and Home shows the same help until something is installed. Once apps exist but none are on Home, Home prompts you to add some from Apps Edit's Add to home control instead. ### 3. Sign in to Kody and grant access Login works one way: Kody login. The shell performs no access check of its own — access is granted and revoked in Kody itself, and there is no setup step for login: no credential to create, no value to configure. - **To let someone in:** grant them Use / `app:execute` on the app in Kody. The owner is always admitted; a grantee is served the same as the owner. - **To end access:** revoke the grant, or have the visitor sign out of Kody. A revoked grantee is denied by the platform before shell code runs — the shell renders no denial page, because it never sees the request. - **Warning:** package visibility and `internet_visible` are independent toggles. With no shell gate left, turning `internet_visible` on exposes the app to anyone on the internet. Do not turn it on for a private shell. On the device, open the app signed in to Kody. On a limited browser that cannot sign in directly (for example the Kindle Scribe stock browser), use Kody's package-app sign-in route (`/-/auth/login`), not a path under the app — the platform sign-in also offers a "sign in on another device" code flow for limited browsers. This is a platform path, not a kody-os path: there is no sign-in button inside kody-os itself. There are no sessions to manage: Kody login is verified per request, so signing out of Kody itself ends access. No device holds a session, and no Logout link is needed. Check: opening the app signed in to Kody loads the shell. Confirm a grantee is served, then revoke the grant and confirm they are denied — that round trip proves access is decided by Kody's permission system. ### 4. Install the first app Add your first app through your agent with the package's `add_app` export, using one of the example definitions in `catalog/` (for example `counter`). The agent validates the definition before writing, and the app appears on the Apps page with no republish. See [Adding an app](../.agents/skills/adding-an-app/SKILL.md) for the definition contract, verification, homepage placement, export, and removal. Check: `list_apps` shows the app, `get_app_state` shows its initial state, the Apps page shows its tile, and acting on it from its app page changes its state. That round trip — add, open, act, state changes — is the proof the setup worked. The App Store (a catalog app for installing catalog apps from the browser, without an agent) is available once it is installed: install it with the App Store prompt on the empty Apps page, or ask your agent to install it with `install_from_catalog` (id `app-store`, catalog base `https://raw.githubusercontent.com/Hypercubed/kody-os/main/catalog/`). Until it is installed, adding apps goes through your agent exactly as above. ### 5. Add further apps the same way Further apps are added the same way: your agent calls `add_app` with a validated definition, or the App Store, once it is installed. Adding an app never needs a republish, and the two stores — hosted and local preview — are separate, so add an app to each target where you want it. ## Catalog and trust The example definitions in `catalog/` are the catalog today. Installing an app means trusting its code: bundle scripts run same-origin with the visitor's full authority, so review third-party definitions before importing them. The trust rule and the full contract live in [Adding an app](../.agents/skills/adding-an-app/SKILL.md). ## Local development Local preview runs the real shell against a separate mock store, so nothing you do locally touches the hosted OS. ```sh cd pkg # proxy bypass required on this host export NO_PROXY='*' no_proxy='*' unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy ALL_PROXY kody dev --target mock # → App ready at http://127.0.0.1:4302/ ``` The mock target is login-free: under `kody dev --target mock` there is no gate at all, so no credential step is needed. Add the `counter` fixture with the registry script, following the `kody execute --target mock` pattern in `pkg/README.md`: ```sh cd pkg python3 -c "import json; d=json.load(open('catalog/counter/definition.json')); json.dump({'op':'add','definition':d}, open('/tmp/add.json','w'))" kody execute --target mock --file scripts/registry.ts --params "$(cat /tmp/add.json)" ``` Check: the Apps page lists `counter`, `GET /apps/counter` returns 200, and acting on it changes its state. Useful checks: `kody dev check --target mock --offline` and `curl http://127.0.0.1:4302/__kody/dev/status`. ## Troubleshooting - **The listing does not exist.** The package is still private. See "Before you start: visibility" above. - **The fork does nothing / the app does not load.** The fork is inert (source only). Publish it through a repo session, then re-check step 1. - **Apps are already installed in a "fresh" fork.** A fresh fork starts empty — nothing is seeded, including no App Store — so anything listed was added after the fork, or you are in the wrong package. Check the package scope and the `list_apps` result before adding anything. - **A request you expected to work is denied.** The platform did not admit it: sign in to Kody and reload, and confirm the visitor holds Use / `app:execute` on the app. A denial happens before shell code runs, so the shell renders no denial page of its own. - **An action fails after a fresh publish.** Confirm the fork is the published one and the app was added to the same target (hosted vs. local preview stores are separate). ## Verification checklist Before calling the setup done, confirm all of these: - [ ] The fork is published and the hosted app loads. - [ ] `list_apps` was empty before the first app was added. - [ ] Kody login loads the shell; a grantee is served while holding the grant and denied by the platform once it is revoked. - [ ] The first app was added via `add_app`, appears on the Apps page, and an action changes its state. - [ ] No credential, code, or live value appears anywhere in your notes from setup: signing in happened in Kody itself, and nothing was typed into the shell. ## Setup prompt for your agent Copy this to a Kody-connected agent, fill in the bracketed part, and let it follow this guide: > Set up my fork of kody-os. First open the setup guide with Kody > search entity `package:/kody-os#docs/setup.md` (replace > `` with my account scope) and read it start to finish, > then follow its setup sequence in order, verifying each step > as the guide describes. If the fork is still inert, publish it > through a repo session. Sign in to Kody as the > guide describes, add the first app with `add_app` from the > example apps, and verify the add/open/act round trip. Do > not publish or change the package source beyond the publish > step, and ask me before approving anything in the Kody UI. > Report each verification result; stop and ask if any check > fails.