puppyone: an Electron folder for agents that is only shared once you move it to the cloud

The same folder can live on your disk or in puppyone Cloud

puppyone starts from one question: you have files on your computer, and you want the agent on your phone, your teammates' agents or an agent on another computer to edit them. The answer is a folder with two homes. You download the app from the project's site, open a folder and start. Your files stay on your computer and no account is needed.

The cloud step is optional. By default puppyone Cloud hosts the folder, so all your agents can reach the same one. You copy the folder's link into ChatGPT (Web), Grok Bot, Muse or Manus, or you invite teammates. Download buttons exist for macOS and Windows.

The consequence is that there are really two products behind one name. A local folder is private and needs nothing from anyone. A cloud folder is shared by every agent in your organization, which also means your files sit on the host you chose. Moving from one to the other is a decision about who can reach the data, not just a convenience toggle.

Five agents cannot reach a folder that exists only on your computer

The compatibility table has two columns, puppyone Local and puppyone Cloud. In the Local column, ChatGPT Web, Grok Bot, Manus, Muse and Viktor have a slash, meaning no support. Cloud agents cannot reach a folder that sits only on your computer. Claude, Codex, Cursor, Hermes, OpenCode, Pi and WorkBuddy work in both columns, either in their own app or inside puppyone.

The built-in agent works in puppyone in both cases. Two terms are used: in puppyone means the agent runs directly in the puppyone app, powered by that agent, while in app means the agent runs in its own app connected to your puppyone folder.

The practical rule is simple. If your daily agent is a web-hosted one, a local-only folder gives you nothing, and you have to put the folder in the cloud. If your agents are desktop tools, local works. For a mixed team, plan on the cloud folder, because a single web-based agent in the group decides the setup for everyone.

In the cloud, MCP, the CLI or SSH are the three ways in

For a folder in puppyone Cloud, any agent can reach it through MCP, the CLI or SSH. That is a wider door than the agent table suggests, since an agent not on the list can still connect if it speaks one of those three.

Self-hosting is possible. The README points to the puppyone-cloud repository and its self-host section for deploying puppyone Cloud yourself. The desktop app reads its endpoints from environment values in .env.example:

VITE_DESKTOP_CLOUD_API_URL=https://api.puppyone.ai/api/v1
VITE_DESKTOP_CLOUD_WEB_URL=https://try.puppyone.ai

A comment there says application code does not carry fallback URLs, so each environment must configure these. An optional third value, VITE_DESKTOP_CLOUD_GIT_ORIGIN, points at https://api.puppyone.ai and is only for localhost API development against a hosted Git endpoint. If you self-host and build the desktop app from source, you will need to set these yourself instead of inheriting defaults.

Local cloud mode defaults to external and spawns nothing

For contributors, the environment file defines PUPPYONE_LOCAL_CLOUD_MODE with three values. The default is external:

PUPPYONE_LOCAL_CLOUD_MODE=external

External uses the configured endpoints and spawns no Cloud processes. Preview explicitly manages a local API plus a built login Web, with no hot reload. Dev explicitly manages a local API plus Web with HMR, for when you are editing Web code. The comments add that endpoint configuration alone never starts Cloud, that the managed modes require loopback API and Web URLs and the sibling Cloud path, and that preview needs the frontend built first with npm run build:local-login.

npm run dev also requires PUPPYONE_DESKTOP_RENDERER_URL, set to http://127.0.0.1:5173 in the example. The limit here is that you cannot run a full local stack from this repository alone. The managed modes expect PUPPYONE_CLOUD_DEV_ROOT, set to ../puppyone-cloud, so a second checkout sitting beside this one is part of the setup.

Git revert is the undo story, and the auto-commit flag is switched off

When an agent breaks something, the answer is to revert. puppyone folders run on Git, so you can go back to any earlier version, and folders hosted on puppyone Cloud work the same way. That makes agent edits recoverable in a way a plain synced directory is not.

There is one detail to check. The package.json for version 0.4.0 has a puppyoneCapabilities block with externalViewerPacks set to false and gitAutoCommit set to false. The README does not say what gitAutoCommit controls, and the repository has a script named check-git-auto-commit among its boundary checks, so it is a tracked feature. Do not assume every agent edit becomes its own commit until you have made a change and looked at the history yourself.

The revert promise is also only as good as the history that exists. A folder with no commits around the bad edit gives you nothing to go back to, so confirm how versions are being created in your setup before you hand an agent write access to anything you care about.

Three formats get first-class treatment and ZIP is community supported

File support has three tiers. First-class support covers Markdown, CSV and HTML. Official support covers DOCX, DOC, ODT, RTF, XLSX, XLS, XLSM, ODS, PPTX, PPSX, ODP, PDF, PNG, JPG, SVG, WEBP, GIF, MP3, WAV, MP4, WEBM, TXT, JSON, JSONL, YAML, TOML, CSS, JS, TS and TSX. Community support covers GLB, ZIP and TAR.GZ.

The tiers tell you where to expect polish. Text-like formats that agents produce most often are in the first tier, and an archive or a 3D model is in the third, so expect to rely on the community there.

Office editing has a specific limit. The environment file says it is a PuppyOne-managed Cloud capability, and that the desktop intentionally has no Document Server URL, JWT, callback listener or Docker configuration. In other words, editing a DOCX or XLSX inside the app depends on the cloud side, and the local desktop will not be given a self-run office server. If you need to edit spreadsheets on a fully offline machine, this is the place it falls short.

A 0.x desktop app with a long list of architecture gates

The repository is an Electron and Vite project. package.json names it @puppyone/desktop, marks it private, sets the version to 0.4.0 and points main at electron/main.mjs. There are scripts for check:release, for generating a DMG background, interface styles and built-in sub-themes, and a check:boundaries script that chains many checks together. Those cover repository layout, test layout, brand assets, renderer asset architecture, test fixture privacy, local workspace architecture, cloud frontend architecture, desktop platform architecture and telemetry architecture, among others.

The recent tags show the pace: v0.3.26 on 2026-09-23, v0.3.27 on 2026-09-29 and v0.4.0 on 2026-10-28. The last push was 2026-11-02 and the repository is not archived. Still, the version is below 1.0, so interfaces may move between releases.

Three legal notes matter. The code is Apache-2.0, but the puppyone name, logos and brand assets are not licensed with it, so forks and redistributed builds need their own name and icon. And basic product analytics are sent unless you turn them off in Settings, then Privacy.

Editorial conclusion

puppyone suits people who already work with several agents and want one Git-backed folder they all read and write, and it fits best when you accept puppyone Cloud or are ready to self-host it. It is a poor fit if your main agent is ChatGPT Web, Grok Bot, Manus, Muse or Viktor and you want files to stay on your machine, because those only connect to the cloud folder. Check the agent table and the 0.x version number before depending on it.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. puppyone-ai/puppyone on GitHub
4. README
5. Releases