Repository navigation
Provide canonical dev setup #1876
Description
Setting up a local instance of the TinyPilot web server can be tricky, because the backend has specific requirements regarding the environment – e.g.:
- On device, it runs on Raspberry Pi OS, which is a specialized flavor of Debian
- Certain system packages need to be installed
- The application makes certain assumptions about the executing user or system paths
Without intimate knowledge of these requirements, it can be challenging to bootstrap a dev environment that is fully (mostly) working.
One idea here would be to provide a tailored Docker image, which mimics the device environment closely.
This may also simplify some of our development procedures, such as running the Playwright end-to-end tests.
Activity
jotaen4tinypilot commentedon Jan 20, 2026
I’ve set up an experimental, Docker-based dev env here: https://github.com/tiny-pilot/dev-env
Feel free to open issues over at that repo for things that are not working or could be improved upon. For general feedback on the setup, we can use this issue here.
cc @jdeanwallace @db39. Reminder: if you have existing
venv/ornode_modules/folders locally within yourtinypilot//tinypilot-pro/clones, either delete them or stash them away, and then reinstall everything from scratch from within the dev-env’s Docker container (only necessary on first usage).db39 commentedon Jan 21, 2026
Thanks for this! This is really cool and definitely makes it easier for me to work on the TinyPilot codebase - I've had a few awkward workaround for certain workflows like the user scripts.
Is it possible to run the web interface and the screen at the same time?
jotaen4tinypilot commentedon Jan 21, 2026
Yes, I’ve just altered the
start.shscript so that you can just call it again (without-por-c) to create additional shell sessions within the running container.I.e., after starting a Pro container with
./start.sh -p, you can do./start.shto jump into the existing dev env. You can create any number of additional shells in the container that way, and e.g. use them to start the front panel or run tests.jdeanwallace commentedon Mar 18, 2026
@jotaen4tinypilot - Oh I forgot to mention this issue in the recent dev meeting, but I've finally tried it myself and I'm happy to move forward with the approach proposed in https://github.com/tiny-pilot/dev-env, including the documentation changes need to point to this canonical dev setup.
jdeanwallace commentedon Mar 23, 2026
An issue that I've since experienced with using https://github.com/tiny-pilot/dev-env, is that now that the Python virtual environments are created from within the container (which seems to symlink
venv/bin/pythonto the real python interpreter installed elsewhere in the docker container), now Claude Code is unable to use the locally syncedvenvto run Python code.This forced me to delete the synced
venvdirectory and recreate it on my dev machine.jotaen4tinypilot commentedon Mar 24, 2026
Are you using Claude CLI or do you have an embedded IDE integration?
jdeanwallace commentedon Mar 25, 2026
Claude Code CLI.
jotaen4tinypilot commentedon Apr 24, 2026
@jdeanwallace see https://github.com/tiny-pilot/dev-env/pull/1 for some Claude capabilities 🎉
I’ve been using this for a while now already, and it seems to work well. (Except the currently repetitive login process.)
jdeanwallace commentedon Apr 30, 2026
@jotaen4tinypilot
Ah cool, thanks! I've been using a standalone docker container setup to run
claude --dangerously-skip-permissions"safely". To avoid the repetitive login issue, it bind-mounts a shared docker volume for claude config. For example, something like:--volume "${HOME}/.claude-dont-use-locally:/root/.claude:rw"Also checkout for inspiration: