Private Provider on Nostr: ...

quoting nevent1q…89j9

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.