Will be updating to offer TEE today 🔥🔥🔥

Foundation KeyOS Dev Container Setup Guide This guide explains how to build a reusable development environment for Foundation Passport Prime KeyOS apps using Docker. When you finish, you will be able to build KeyOS, run the KeyOS simulator in a web browser, and (optionally) run an AI coding agent inside the same environment. It is written for beginners. You can share it with friends. Adjust file paths to match your own computer. What you will end up with • A Docker image containing the KeyOS build toolchain (Rust, just, ARM tools). • The KeyOS simulator running on a virtual screen, viewable in a browser. • A persistent build cache so you do not re-download everything each run. • An optional way to run an AI coding agent inside the container. Important notes before you start • You do NOT need Nix. This setup uses Docker instead. • You do NOT need a GitHub account to build or run the simulator. • Never share secrets: no private keys, no nsec values, no passwords, no tokens. • The first build and first simulator run are slow. Later runs are much faster. Part 1 - Host prerequisites On your normal computer (the "host"), you need: • A Linux system (these instructions assume Linux). • Docker Engine and the Docker Compose plugin. • git. • Optional: your own AI agent CLI if you want an agent inside the container. Check that Docker works in a normal terminal: docker --version docker compose version git --version If Docker is not installed, install Docker Engine and the Compose plugin for your Linux distribution first, then continue. Part 2 - Get the project files This setup lives in a project folder. That folder contains a devcontainer directory with the Docker files, plus a clone of the KeyOS source. Step 2.1 - Create a project folder mkdir -p ~/foundation cd ~/foundation Step 2.2 - Add the devcontainer files Copy the devcontainer folder from this project into your ~/foundation folder. It should contain these files: devcontainer/Dockerfile devcontainer/docker-compose.yml devcontainer/entrypoint.sh devcontainer/keyos-screenshot.sh devcontainer/write-env.sh devcontainer/.env.example devcontainer/README.md If you received this guide from a friend, ask them to also share that devcontainer folder, since these files define the environment. Step 2.3 - Clone the KeyOS source From inside ~/foundation, clone Foundation's KeyOS repository so it sits at ~/foundation/KeyOS: cd ~/foundation git clone https://github.com/Foundation-Devices/KeyOS.git KeyOS The Docker build reads scripts from this KeyOS folder, so the clone must be present before building. Part 3 - Configure your local settings The container should run as your user so files it creates are owned by you, not root. A helper script writes a small local settings file for this. cd ~/foundation ./devcontainer/write-env.sh This creates devcontainer/.env with your user id, group id, and a default virtual screen size. This file is machine-specific and should not be shared or committed. If you want to change the simulator screen size, edit devcontainer/.env and set one of these values: VNC_RESOLUTION=800x1280x24 VNC_RESOLUTION=1024x768x24 VNC_RESOLUTION=900x700x24 VNC_RESOLUTION=800x600x24 Part 4 - Build the container image This builds the KeyOS toolchain image. It downloads and compiles a lot the first time, so it can take a long time. cd ~/foundation/devcontainer docker compose build When it finishes, you should see a message that the image was built. Part 5 - Start the container cd ~/foundation/devcontainer docker compose run --rm --service-ports keyos-dev Plain English: • This starts the KeyOS development container and drops you into a shell inside it. • --rm removes the temporary container when you exit. Your files stay safe on the host because the project folder is mounted into the container. • --service-ports exposes the browser viewer port. Inside the container you should land in /workspace/KeyOS. Verify the tools: cargo --version just --version Part 6 - Create the local developer signing key KeyOS signs apps even in the simulator, so you need a local developer signing key the first time. Inside the container: cd /workspace/KeyOS test -f cosign2.toml || ./scripts/generate-cosign2-dev-key.sh Important: this creates a private key file named cosign2-priv.pem. Treat it like a password. • Never share it. • Never commit it. • Never paste its contents anywhere. Part 7 - Run the simulator Inside the container: cd /workspace/KeyOS just sim The first run compiles a large amount of code, so it can take many minutes. The terminal will look busy or "stuck" while the simulator runs. That is normal. Step 7.1 - View the simulator in a browser On your host machine, open: http://localhost:6080/vnc.html Click the connect button if prompted. You should see the simulated device screen. Step 7.2 - If the screen is clipped In the browser viewer, open the side menu, open settings, and set the scaling mode to "Local Scaling". If needed, turn off "Clip to Window". If it is still wrong, stop the simulator, change VNC_RESOLUTION in devcontainer/.env, and restart the container. Step 7.3 - Take a screenshot Do not restart the simulator to take a screenshot. Instead, open a second shell into the same container and run: keyos-screenshot /workspace/keyos-sim.png The image will appear on the host under your project folder. Part 8 - Optional: run an AI agent inside the container This step is optional. It lets an AI coding agent run inside the same environment as the KeyOS tools, so it can build, run the simulator, read errors, and help fix code. This requires that you already have your own agent CLI installed on the host and that the docker-compose file mounts it into the container. Details depend on which agent you use. Security notes: • Mounting your agent's home folder can expose your login/config to the container. Only do this on a machine and project you trust. • Never bake secrets, tokens, or private keys into the Docker image or compose file. • If the agent complains it cannot create a sandbox namespace inside the container, that is expected in some Docker setups. Because the container is already an isolation boundary, you can run the agent with a "full access inside the container" flag so it stops asking. Understand this gives the agent full access within the container. Typical pattern, run from a second host terminal: docker ps docker exec -it bash cd /workspace Then start your agent from /workspace so it can see the whole project. Part 9 - Everyday use Start cd ~/foundation/devcontainer docker compose run --rm --service-ports keyos-dev cd /workspace/KeyOS just sim Then open http://localhost:6080/vnc.html in a browser. Two terminals at once Terminal 1 runs the simulator with just sim. To do other work at the same time, open a second host terminal and enter the same running container: docker ps docker exec -it bash Stop In the simulator terminal press Ctrl+C, then type: exit Because the container was started with --rm, it is removed automatically. Your files, KeyOS source, and caches remain on the host. Part 10 - Troubleshooting The build fails on an optional editor tool The Dockerfile in this setup already skips an optional Slint editor tool that can fail to install. If you rebuild your own Dockerfile from scratch and hit that error, remove the optional editor tool from the install list; it is not needed to build or run the simulator. The first simulator run takes a long time This is normal. KeyOS is a full operating system, so the first compile is large. Later runs are much faster. It keeps re-downloading dependencies This setup stores the build cache under the project folder so it persists across container runs. Make sure that cache folder is not deleted between sessions. The browser viewer is blank Confirm the simulator is still running in its terminal. If needed, check the log files inside the container under the temporary dev log folder. Files are owned by root on the host Make sure you created devcontainer/.env with the write-env helper before starting the container, so it runs as your user. Unfamiliar files in git status Inside the KeyOS clone, some Windows script files may appear modified due to line-ending differences. Leave them untouched. A file named core is a crash dump and can be safely deleted. What this setup does and does not do This setup gives you a working KeyOS development and simulator environment, and optionally an AI agent inside it. It does not automatically: • publish your app anywhere, • submit your app to any official app catalog, • install your app on real hardware, • prove that a retail device will accept a self-signed app. Those are separate steps handled outside this environment. Safety reminders • Never share or commit private keys, nsec values, passwords, or tokens. • The developer signing key cosign2-priv.pem is secret. • Machine-specific settings files like .env should not be shared. • Build outputs and caches do not need to be shared; friends can rebuild them.

On a retail Passport Prime running KeyOS v1.2.1, can a user sideload an app signed with a self-generated cosign2 developer key over USB, or does the device only run Foundation-signed apps / require a developer unit or developer mode?

It is just a calculator...

Hello !

## Project Intake Form A short, plain-English worksheet to get your app idea out of your head before you start building with Fugu. This form only asks about things that YOU know: what you want and why. The technical decisions (tools, commands, safety rules) are figured out later with Fugu and captured in the project AGENTS.md after the project is scaffolded — so you do not need to answer any technical questions here. How to use this form • Fill this out first, in plain language. Short answers are fine. • Focus on the first useful version, not the whole dream app. • When you are done, send the kickoff prompt at the bottom to Fugu, then follow the walkthrough (Starting From Only an App Idea) for the rest. • If you are unsure about anything, just write what you are thinking — Fugu can help refine it. 1. One-sentence description Formula: This is a [kind of app] for [who] that helps them [main outcome]. Example: This is a habit tracker for me that helps me check off daily habits. Answer: 2. Who is it for? Who will use it? If it is just for you at first, say that. Answer: 3. What problem does it solve? What is annoying or hard today, and what should feel better once the app works? Answer: 4. The first version Describe the smallest version that would still be useful. Keep it small — you can always add more later. Answer: 5. The main thing a user does Describe the most important flow in simple steps, from what they do first to what they see at the end. Example: Add a habit, check it off today, see today’s habits, see the current streak. Answer: 6. What "done" looks like How will you know the first version works? Describe it in plain terms. Example: I can add habits, check them off, my data is still there after I refresh, and I can start the app with one command. Answer: 7. What to leave out for now List anything you do NOT want in the first version. This keeps the project small and focused. Examples: accounts and logins, payments, a mobile app, sharing with others, fancy settings. Answer: 8. Anything else Fugu should know Likes, dislikes, inspirations, must-haves, or things to avoid. Anything that helps Fugu understand your taste. Answer: Kickoff: hand this to Fugu When the form is filled in, start your session and send this. Replace the bracket with your answers above. Kickoff prompt to send Fugu: " I'm brand new and have no coding experience. I have an idea for an app. Please guide me step by step, explain things in plain English, and don't build anything until I approve a plan. Here is my filled intake: [paste your answers to the questions above]. Based on this, help me confirm a small first version, then recommend a simple stack and a plan — and wait for my approval before building. " After that, follow the walkthrough document (Starting From Only an App Idea) for choosing tools, scaffolding, saving, and building one small slice at a time.

## Starting From Only an App Idea - What to Say to Fugu A friendly, conversational walkthrough for someone with no coding experience who has an app idea only in their head. Each phase includes a copy-paste prompt you can send to Fugu. Go one phase at a time, and let Fugu explain anything you don't understand. Before you begin - the mindset • You do not need to know how to code. Your job is to describe what you want and review what comes back. • Go slowly. Build in small steps. Save often so you can always undo. • If anything is unclear, ask Fugu to explain it in plain English. Phase 1 - Introduce yourself and your idea Start the session by setting the tone. Fill the brackets with your own idea, then send this: Prompt to send: I'm brand new and have no coding experience. I have an idea for an app. Please guide me step by step, explain things in plain English, and don't build anything until I approve a plan. Here's my idea: [describe your idea in a few sentences: what it is, who it's for, and the main thing it should let someone do]. Phase 2 - Let Fugu sharpen the idea Let Fugu ask you questions to fill the gaps. Then ask it to define a small first version: Prompt to send: Based on my idea, help me define the simplest first version that is still useful. Tell me what the first version should include, and just as importantly, what to leave out for now so I don't overbuild. Phase 3 - Choose the tools You don't need to know the tools. Ask Fugu to recommend a sensible default and explain it: Prompt to send: Recommend a simple, boring, well-supported way to build this. Explain in plain English why you chose it and what I'll be able to do with it. Then wait for my approval before doing anything. Phase 4 - Scaffold the running skeleton Once you approve the tools, have Fugu create and run the starting point: Prompt to send: Please scaffold the project using the standard setup for that stack, then run it so I can see a basic version working. Show me the real commands to run, test, and build it. Phase 5 - Save your first checkpoint Before adding features, lock in a safe save point: Prompt to send: Set up version tracking (git) if it isn't already, and save this working baseline with a clear message. Explain what you did in plain English. Phase 6 - Create the project instructions file Give future sessions a short operating manual based on the real project: Prompt to send: Now create a short AGENTS.md for this project using the real commands and folder structure. Keep it to one page: what it is, the current goal and what 'done' looks like, the commands, and any safety boundaries. Then save it. Phase 7 - Build one small slice at a time This is the main loop. Repeat it for each small feature. Start each slice like this: Prompt to send: Let's add just one small thing: [describe one visible feature, for example: let me add an item to the list]. Propose a short plan first and wait for my approval before building. After Fugu builds each slice, always send these two review prompts: Prompt to send: In plain English, what exactly changed? Prompt to send: Did you run and test it? What was the actual result? Then decide: • If it works: say - Save this working state with a clear message. • If it's broken: say - Please fix it, or roll back to the last working save. • Then move on to the next small slice. Phase 8 - Finish the first version When the core feature works, wrap up cleanly: Prompt to send: Compare what we've built to the 'done' definition from earlier. Then write a short README so I can run this again later, and do a final save. Handy prompts to keep nearby • Explain that to me like I have no coding experience. • What are my options here, and which do you recommend and why? • Is this a risky change? If so, save first, then explain what could go wrong. • Show me what changed and how you verified it works. • Save this working state with a clear message. • Roll back to the last working save. How to get engineer-quality results You can get close to what a professional would build, especially for simple, personal apps. The trick is HOW you ask. Follow these habits. • Delegate the decision, but demand the reasoning. Don't say 'you decide' and walk away, and don't dictate technical choices you don't understand yet. Ask Fugu to recommend, explain, and warn you - then you approve. • Avoid the two traps: blind delegation (you can't tell if the result fits your needs) and confident dictating (forcing a choice based on a guess is worse than letting Fugu choose). • Verify, don't assume. Fugu will always sound confident, even when it's wrong. Make it run it, test it, and show you it actually works - every time. • Slow down when the stakes are real. Real users, personal data, money/payments, passwords, or code you'll rely on long-term deserve extra care - ask Fugu to point out risks, and consider a human review for those parts. • Learn as you go. Each time Fugu explains a tradeoff, you get a little better at asking the right question next time. That's how a beginner grows into getting expert results. Copy-paste prompt that captures all of this: Prompt to send: For this decision, recommend the best option for my situation, explain the tradeoffs in plain English, tell me what could go wrong, and wait for my approval. After you build it, run and test it and show me it actually works. Prompt to send: Are there any risks here I should worry about - security, privacy, data loss, or things that get harder later? Explain simply. The three habits that carry a beginner • Small steps - one slice at a time, never 'build it all.' • Always review - ask what changed and whether it was actually tested. • Save constantly - after anything that works, and before anything risky. One-line reminder: Get the idea out of your head, let Fugu sharpen it, approve simple tools, scaffold and save, then build one small reviewed slice at a time - saving after each one that works.

## How to Build a Project using Fugu + Codex A plain-language, step-by-step checklist for building software with an AI coding agent, written for someone with no prior software experience. Work top to bottom. Do one step at a time. Key idea Build in small, saved steps. First create a running skeleton (scaffold), save it, then add one small feature at a time and save after each one that works. Saves are called commits, and you can always roll back to a previous commit if something breaks. Step 0 - Before you start • You do not need to know the tools. You describe what you want; Fugu recommends and runs the technical steps. • Ask Fugu to explain anything in plain English and to show you what changed after each step. • Golden rule: if something works, save it (commit). Before trying something risky, save first. Step 1 - Conceive: fill the intake form • Open the Project Intake Form and fill it in. • Be clear on: what the app is, who it is for, the single most important thing it must do, and what a first working version (done) looks like. • Keep the first version small. You can add more later. Step 2 - Set up the project folder • Create or choose an empty folder for the project. • Copy your filled intake form into that folder so Fugu can read your intentions. Step 3 - Choose the tools (stack) • Ask Fugu: Given my intake form, recommend a simple, boring, well-supported stack and the standard way to scaffold it. • Ask why it chose those tools. Approve the choice before continuing. Step 4 - Scaffold: create the running skeleton • Ask Fugu to scaffold the project using the standard generator for the chosen stack. • This creates the folder layout, config files, the real commands (install, run, test, build), and a working hello-world starting point. • Ask Fugu to run it so you can confirm the baseline actually works. Step 5 - First save point (first commit) • Ask Fugu to set up version tracking (git) if it is not already, and commit this clean, working baseline. • Ask for a clear commit message, for example: initial scaffold, running baseline. • This is your first safe point you can always return to. Step 6 - Write the project AGENTS.md • Now fill the lean AGENTS.md template using the real commands and folder structure from the scaffold. • Include: what it is, current milestone and definition of done, real commands, safety boundaries, and stack plus key decisions. • Do not repeat your global rules (tone, security, workflow) - those live in your global AGENTS.md. • Commit the new AGENTS.md. Step 7 - Build in slices (the main loop) Repeat this loop for each small feature until the first version is done: • Pick one small slice - a single visible thing, for example: let the user add an item. Not the whole app. • Ask Fugu to propose a short plan for that slice, and approve it. • Let Fugu build it. • Review: ask What changed, in plain English? and Did you run and test it, and what was the actual result? • Run it yourself if you can, and confirm it does what you expected. • If it works: commit with a clear message. If it does not: ask Fugu to fix it, or roll back to the last good commit. • Move to the next slice. Step 8 - Finish the first version • Check your work against the definition of done from your intake form. • Make sure setup and usage are written down (a short README) so you can run it again later. • Do a final commit for the completed first version. Commit cheat sheet (your undo button) • Commit = a labeled snapshot of the whole project at a moment in time. • Commit every time something works, and before anything risky. • You can ask Fugu: commit this working state with a clear message. • If a change breaks things, ask Fugu to roll back to the last working commit - nothing before it is lost. Good habits that keep you in control • Keep slices small - easy to review, easy to undo. • Always ask what changed and whether it was actually tested. • Never store passwords or secret keys in the project files; use the placeholders and environment variables Fugu sets up. • Update your AGENTS.md when commands or decisions change; keep it short and accurate. One-line mental model Intake (what I want) -> choose tools -> scaffold (running skeleton) -> first commit -> write AGENTS.md -> loop: plan, build, review, run, commit.

Given that the client is probably routstrd + Pi Agent, I would treat this as a client/ daemon streaming compatibility problem, not necessarily a bad Fugu provider setup. ## Simple diagnosis The error: Unexpected token 'd', "data: {"id"... is not valid JSON means something received this kind of response: data: {"id":"..."} data: {"id":"..."} data: [DONE] …but tried to read it as normal JSON. That data: format is Server-Sent Events streaming, which Routstr documents as the expected format when stream: true is used. Routstr’s non-streaming default is stream: false; when stream: true, responses are sent as data: ... lines ending with data: [DONE]. (docs.routstr.com (https://docs.routstr.com/api/endpoints/)) So the likely chain is: Pi Agent → routstrd → your Routstr node → Sakana Fugu → returns streaming data Then either Pi Agent or routstrd tries to parse the whole streaming response as one JSON object and crashes. ## Why routstrd is suspicious here Routstrd is meant to sit locally between agents like Pi Agent and Routstr providers. Routstr’s own page says routstrd can onboard Pi Agent, discover Routstr nodes, and auto-route to providers. (routstr.com (https://routstr.com/routstrd)) The routstrd README says its daemon API accepts a body with: { "model": "model-id", "messages": [], "stream": false } and shows a normal JSON response, not an SSE stream. (github.com (https://github.com/Routstr/routstrd)) That does not prove routstrd cannot stream, but it supports the practical guess: routstrd/Pi may be taking a streaming response and handling it as non-streaming JSON. ## Most likely cause Most likely: > Pi Agent is requesting streaming, or routstrd is forwarding a streaming request, but routstrd/Pi is not correctly consuming the streaming response from your Fugu-backed Routstr node. Your Routstr node may be doing the right thing by returning data: {...} lines if the request included stream: true.

## Reading tips won't make you good — reps with reflection will. Here's the practice loop: 1. Do it a lot, on real tasks. Volume matters. Every task is a rep. 2. Notice the failure, then diagnose the prompt, not just the output. When you get a bad result, ask: "What did I leave ambiguous? What context did I assume it had?" The bug is usually in the prompt, not the model. 3. Keep a "prompt journal." Save prompts that worked well (you're literally already doing this — tasty fugu, your shine prompt). Reuse and refine them into templates. 4. Compare variations. Ask the same thing two ways and see what changes. You learn what levers actually move the output. 5. Steal structure from good prompts. Your shine prompt (Goal / Guardrails / Workflow) is a reusable skeleton. Collect skeletons like that. 6. Make the model teach you. Ask: "How could I have prompted this better?" or "What was ambiguous in what I asked?" — turn it into a feedback partner. 7. Learn the domain a little. The more you understand what you're asking for, the better you can specify it. Prompting well and knowing your subject reinforce each other. ## Common beginner mistakes (and the fix) Too vague → add goal + constraints + done-when Assuming it knows → give context / point it at files One giant prompt → break into steps, iterate Over-explaining "how" → state intent, let it find the route Trusting first output → verify, then refine No examples → show one example of what you want ## The honest truth about the field - It's a real skill, but not a mystical one. It's mostly clear thinking + clear communication + iteration. - It's getting easier, not harder. Newer models need less hand-holding, so heavy "trick" prompting matters less over time. The durable skills — clarity, context, constraints, verification — are exactly the ones you've been building. - The best prompt engineers aren't collecting magic phrases. They're good at decomposing problems and communicating precisely. ## The tasty-fugu takeaway 🐡 Prompt engineering = designing clear input to get the output you want. Get good by: do reps → diagnose the prompt when it fails → save what works → reuse structures → verify → ask the model how to prompt better. And the reassuring part: your AGENTS.md, your shine prompt, your "verify, don't assume" reflex — that is applied prompt engineering. You're not starting from zero; you're already practicing the real thing. Now it's just reps.