Puppyone: a Git-native Context Drive with file-level permissions for AI agents

The problem: agent context lives in places agents cannot safely share

Most agent stacks assemble context ad hoc. A retrieval layer pulls chunks, a prompt template pastes them in, and the resulting text has no version, no owner and no permission boundary. When two agents need the same corpus, teams either duplicate it or give both agents the same broad credentials.

Puppyone's answer is to treat context as a file system rather than a retrieval index. The README describes a Context Drive as a cloud file system that any agent can browse like a local directory, with all connected data transformed into Markdown, JSON or raw files. The target user is a team running several agents against overlapping material, where one agent should see a customer folder and another should not.

The framing matters. This is not a vector database with metadata filters bolted on. It is a directory tree with version control and per-agent scoping, and the retrieval question is left to whatever the agent does with files it can read.

File Level Security is the load-bearing design choice

The README makes a specific claim about how permissions work: per-agent file permissions are enforced at the filesystem layer, and if an agent lacks access, the file physically does not exist in its environment. The comparison offered is Row Level Security, but for files.

That is a stronger statement than an application-level check. An application-level filter returns an error or an empty result; a filesystem-level boundary means the path is absent from the agent's view, so a prompt-injected instruction to read a forbidden file has nothing to resolve. The README does not explain the enforcement mechanism, and this is the single most important thing to verify before trusting the project with sensitive context. Whether it is a mount namespace, a FUSE layer, a per-agent overlay or something else is not stated in the supplied material.

Around that boundary sit the operational features: file-level version history with diff and rollback, folder-level snapshots for bulk recovery, audit logs recording every read and write with actor, file and timestamp, and a checkout/commit workflow with locking and conflict detection for concurrent agent edits. The commit model is the part that will feel unfamiliar to teams used to a retrieval pipeline. Agents do not just read here; they can write, and writes can collide.

One Context Drive, several Access Points

Puppyone separates the store from the ways in. The README calls the entry points Access Points and lists CLI, MCP, Git, bash/SSH and the web app as supported interaction methods, with a diagram captioned one shared Context Drive, multiple scoped Access Points for different agents and tools.

The MCP path is the one most teams will try first, because it plugs into existing clients. The documented command is:

puppyone access add mcp "My Context"

According to the README, this outputs an MCP endpoint URL and an API key, which you then give to an MCP client such as Cursor or Claude Desktop. The Git and SSH paths exist for agents or tools that already speak those protocols, which avoids writing a custom client.

Scoping is expressed when you add a source. The README's example for a web page is:

puppyone access add url https://example.com --scope /refs

The --scope flag maps the incoming content to a path in the Context Drive. That path is what FLS rules presumably key off, so the folder layout you choose at ingestion time becomes your permission model later. Getting that wrong is a migration, not a config tweak.

Self-hosting: one Compose file, and a Docker socket you should think about

The self-hosted path is deliberately short. Clone the repository, move into the docker directory, copy the environment template, and bring the stack up:

git clone https://github.com/puppyone-ai/puppyone.git cd puppyone/docker cp .env.example .env docker compose up -d

The README states this starts PostgreSQL, Auth, an API gateway, Redis, MinIO, backend and frontend in a single command, and that the database schema is applied automatically on first run. The four exposed endpoints are the frontend on port 3000, the backend API on 9090, the Supabase API on 8000 and the MinIO console on 9001. First startup is quoted at one to two minutes, with docker compose ps as the check when the web app is not reachable.

Two configuration notes are worth pulling out. Agent chat in a self-hosted stack requires adding ANTHROPIC_API_KEY to docker/.env and restarting. OAuth connectors for GitHub, Gmail and Google Drive require provider credentials in the backend environment, with backend/.env.example as the reference.

The security note in the README deserves attention rather than a skim. The local stack mounts the host Docker socket into the backend container so that agent bash and sandbox endpoints work without changing the backend's global temp directory behaviour. The README then says plainly that for remote or multi-tenant deployments you should prefer SANDBOX_TYPE=e2b with an E2B_API_KEY. A host Docker socket is effectively root on the host. The default is fine on a laptop and wrong on shared infrastructure, and the project says so.

The CLI keeps a session per target, which matters for mixed deployments

Installation is a global npm package, and the first run asks which backend to talk to:

npm install -g puppyone puppyone auth login

The prompt offers Cloud, Local or Custom URL, and for a self-hosted backend you either choose Local or pass the URL directly, for example -u http://localhost:9090. Sessions are stored per target, so the README states you can move between Cloud and self-hosted without re-entering credentials, using puppyone auth targets switch <url>.

Project setup is two commands:

puppyone project create "My Project" puppyone project use "My Project"

The first creates the project, the second makes it active. The README notes the same can be done from the web app. Nothing here is surprising, and that is the point: the CLI is a thin client over the same store, not a separate product with its own state.

Where Puppyone is the wrong tool

The version number is the first honest signal. v0.0.3 shipped on 2026-05-31 with the release note NewMu object durability hotfix, following v0.0.2 in April with MUT engine, unified CLI, and UI polish, and v0.0.1 in March. A durability hotfix at the third patch release means storage-layer correctness was still being fixed in May. There is no stated compatibility policy, no LTS branch and no deprecation window in the supplied material. If your agents depend on a stable interface, that is a real risk.

The second limitation is conceptual. Puppyone is a context store, not a retrieval engine. The README mentions rag as a topic but describes no chunking, embedding, ranking or hybrid search. If your problem is finding the three most relevant paragraphs in ten thousand documents, a file system with permissions does not solve it; you would still need a retrieval layer reading from the Drive. Conversely, if your problem is that agents cannot agree on which version of a document is current, or that one agent can read another team's folder, Puppyone addresses exactly that.

The third is the sandbox default already discussed. Running the Compose stack on a shared host without switching SANDBOX_TYPE to e2b hands the backend container control of the host Docker daemon.

The fourth is connector setup. GitHub, Gmail, Google Drive and the other OAuth sources need provider credentials before they work. The README lists built-in connectors for GitHub, Gmail, Google Drive, Google Docs, Google Sheets, Google Calendar, Google Search Console, web pages, local filesystem and Supabase, but a fresh self-hosted install will not have them configured.

Compared with a document store plus a permissions service

The closest conventional alternative is a document store or object bucket holding your context, a vector index over it, and an authorization service in front. The difference is where the boundary sits. In that stack, an agent asks the API for a document, the API checks a policy, and the document is returned or refused. The check is code you wrote, and the failure mode is a bug in that code returning something it should not.

Puppyone inverts this. The README's claim is that the file is physically absent from the agent's environment when access is denied, so there is no request to intercept and no response to filter. Whether that claim holds in practice depends on the enforcement mechanism, which the README does not describe.

The trade-off runs the other way too. A document store with a policy engine gives you query languages, indexes, transactions and mature backup tooling. Puppyone gives you directories, Git semantics and a checkout/commit workflow. If your agents need to run a query with a filter expression, a file tree is a worse interface. If they need to operate on files the way a developer does, with history and locking, it is a better one.

Licence, upgrade cost and what to check before you commit

Puppyone is Apache-2.0. That permits commercial use, modification and redistribution, and it includes a patent grant and a patent retaliation clause. It does not require you to publish modifications, and it does not grant trademark rights. This is a general description, not legal advice; if your organisation has policies about which licences are acceptable for a hosted service or a distributed product, run the actual text past whoever owns that decision.

Upgrade cost is hard to estimate from the supplied material. The releases are three patch versions across roughly three months, and the repository is not archived. The README documents no migration guide, no schema versioning story beyond automatic application on first run, and no statement about backward compatibility between releases. The Compose stack applies the database schema automatically on first run, which is convenient on a fresh volume and ambiguous on an existing one. Back up the PostgreSQL and MinIO volumes before pulling a new image tag.

If you are evaluating it, the order of checks is: confirm the FLS enforcement mechanism actually removes files from the agent's view rather than filtering responses, decide the folder layout for --scope paths before ingesting anything, and read backend/.env.example to size the connector configuration work. Nothing in the README answers the first question, and it is the one the whole design rests on.

Editorial conclusion

Adopt Puppyone if you already run agents that need to share a curated, versioned context store and you want permission boundaries that hold below the application layer. Do not adopt it if you need a stable API surface today: the project is at v0.0.3, the README does not document a compatibility policy, and the self-hosted Compose stack shares the host Docker daemon by default. Before committing, verify the FLS enforcement path yourself, confirm which connectors work without provider OAuth credentials, and read backend/.env.example to see how much configuration a self-hosted deployment actually requires.

Official sources

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