Puppyone: a Git-native context drive for AI agents

The problem Puppyone targets: agents that all read the same unmanaged pile of files

Most agent stacks assemble context at request time. A retrieval step pulls chunks, a prompt template glues them together, and nothing records which document version the agent actually saw. Puppyone takes the opposite position: context is a file system that lives outside the agent, and the agent browses it like a directory. The README describes the product as "context hosting for AI agents, with Git version control and file-level scoped permissions for every agent."

The audience is teams running more than one agent, or one agent with more than one job, against overlapping source material. If a single agent reads a single folder, the value is thin. The value appears when agent A should see customer records and agent B should not, and when someone later asks which files an agent read before it produced an answer. Puppyone answers both with the same primitive: a Context Drive, which the README calls "a cloud file system that any agent can browse like a local directory."

How the Context Drive, Access Points and File Level Security fit together

The architecture separates storage from access. One Context Drive holds the files. Around it sit Access Points, which the README describes as the way different agents and tools reach that drive: CLI, MCP, Git, and bash/SSH. The repository diagram caption states the intent plainly: "One shared Context Drive, multiple scoped Access Points for different agents and tools."

Connectors feed the drive. The README lists built-in sources for GitHub, Gmail, Google Drive, Google Docs, Google Sheets, Google Calendar, Google Search Console, web pages, a local filesystem, and Supabase databases. Incoming data is normalized into Markdown, JSON, or raw files before it lands in the drive.

The permission model is the part worth reading twice. File Level Security is enforced at the filesystem layer rather than in a query filter. The README's phrasing is that if an agent lacks access, "the file physically doesn't exist in its environment," and it draws the analogy to Row Level Security, but for files. That is a stronger claim than filtering results after a read, and it is the main reason to consider Puppyone over a plain object store with signed URLs. Around it the README adds version history with diff comparison and one-click rollback, folder-level snapshots, audit logs for every read and write, and a checkout/commit workflow with locking and conflict resolution for concurrent agent edits. The audit log records who did what, to which file, and when.

Installing Puppyone with Docker Compose and creating a first Context Drive

There are two deployment paths. The hosted option is an account at puppyone.ai. The self-hosted option runs the full stack locally and lists Docker as the only prerequisite. The README gives these four commands:

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

That single Compose invocation starts PostgreSQL, Auth, the API gateway, Redis, MinIO, the backend, and the frontend. The README states the database schema is applied automatically on first run and that first startup may take one to two minutes. If the web app is not reachable, the README suggests `docker compose ps` to check container state. The published service URLs are the frontend on `http://localhost:3000`, the backend API on `http://localhost:9090`, the Supabase API on `http://localhost:8000`, and the MinIO console on `http://localhost:9001`.

Agent chat in a self-hosted stack needs an Anthropic key. The README says to add `ANTHROPIC_API_KEY` to `docker/.env` and restart with `docker compose up -d`. OAuth connectors such as GitHub, Gmail, and Google Drive need provider credentials in the backend environment instead, and the README points at `backend/.env.example` for the current variable names.

For CLI-driven work, install the global package and sign in:

npm install -g puppyone
puppyone auth login          # first run asks: Cloud / Local / Custom URL

The login prompt offers Cloud, Local, or a custom URL. Self-hosted users pick Local, or pass `-u http://localhost:9090`. The CLI keeps sessions per target, so switching between a cloud account and a local stack does not require re-entering credentials: `puppyone auth targets switch <url>`.

Then create the drive and put something in it:

puppyone project create "My Project"
puppyone project use "My Project"
puppyone access add url https://example.com --scope /refs

The first two commands create a project and mark it active. The third adds a web page as a source and scopes it under `/refs`. Files and folders go in through the web app rather than the CLI, and the README notes that target folders let you place uploaded or synced content at any path in the drive.

When an MCP client such as Cursor or Claude Desktop should read the drive, the README's command is `puppyone access add mcp "My Context"`, which prints an MCP endpoint URL and an API key. The documentation site at puppyone.ai/doc is where the README sends readers for the supported source list and advanced setup.

Where Puppyone is the wrong tool

The security note in the README is the clearest limitation, and it is self-declared. The local Docker stack enables Docker-backed sandboxes by sharing the host Docker daemon with the backend container. The README calls this convenient for local self-hosting and then says that for remote or multi-tenant deployments you should prefer `SANDBOX_TYPE=e2b` with an `E2B_API_KEY`. Anyone planning to expose a self-hosted instance to other people needs to act on that line, not skip it.

The heavier constraint is that self-hosting is not a single binary. The root `docker-compose.yml` in the repository defines Redis and MinIO with their own volumes, plus a `minio-init` job that creates a bucket named `contextbase`. The README's own list adds PostgreSQL, Auth, an API gateway, the backend, and the frontend on top. That is a real operational surface for a tool whose job is storing files for agents.

There is also a scope mismatch. Puppyone organizes context as files with permissions, not as embeddings. If your only need is similarity search over a few hundred documents, a vector store plus your existing prompt assembly is less machinery. Puppyone earns its keep when provenance, per-agent scoping, and rollback matter more than nearest-neighbor retrieval.

Finally, the release history is short. The three releases on record are v0.0.1 (Initial Public Release), v0.0.2 (MUT engine, unified CLI, and UI polish), and v0.0.3 (NewMu object durability hotfix) on 2026-05-31. A durability hotfix in a 0.0.x line is normal for early software, but it is a signal that the storage layer is still settling. The last push to the repository was on 2026-08-02.

How Puppyone differs from a RAG pipeline or a plain object store

The obvious comparison is a RAG stack: chunk documents, embed them, store vectors, retrieve top-k at query time. The difference is what persists. A RAG pipeline keeps a derived index; the source of truth is whatever you fed it, and the index tells you nothing about which agent was allowed to see which chunk. Puppyone keeps the files themselves and puts the access decision at the filesystem layer, with the README's claim that an unauthorized file does not exist in the agent's environment. Retrieval becomes browsing a directory, and the audit log records reads and writes rather than similarity scores.

The second comparison is a plain object store such as S3 or MinIO with signed URLs. Puppyone actually uses MinIO underneath, so the distinction is not storage. It is the layer above: version history with diff and rollback, folder snapshots, checkout and commit with locking, and per-agent credentials issued through Access Points. With raw object storage you build all of that yourself. With Puppyone you inherit its opinions about how it should work, including the checkout model, which is a real commitment if your agents write concurrently.

Maintenance cost, release cadence and the Apache-2.0 licence

Puppyone ships under Apache-2.0, with a `LICENSE` and a `NOTICE` file at the repository root. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, which matters if you embed the code in a product. The `NOTICE` file exists to carry attribution, so if you redistribute a modified version, read it rather than assuming the licence text alone covers your obligations. This is a description of the licence, not legal advice.

Upgrade cost depends on which path you took. Hosted users get whatever the service runs. Self-hosters own the Compose stack, and the repository's root `docker-compose.yml` pins Redis to `redis:7-alpine` while MinIO uses `minio/minio:latest`, an unpinned tag. Pulling a new MinIO image is therefore an uncontrolled variable in an otherwise pinned stack. The README does not document a rollback procedure for a failed stack upgrade, and the file-level rollback it describes applies to Context Drive content, not to the deployment.

The release cadence visible in the repository is three releases across roughly three months, from v0.0.1 on 2026-03-08 to v0.0.3 on 2026-05-31. For a 0.0.x project, budget for reading release notes before each bump rather than upgrading blindly.

Editorial conclusion

Puppyone fits teams that already run agents against a shared corpus and need per-agent scoping plus an audit trail, and it is a reasonable fit for self-hosters willing to run the full Compose stack. Skip it if you only need a vector index over a few documents, or if you cannot give the backend container access to a Docker daemon, since the local sandbox path depends on that. Before adopting, check backend/.env.example for the current OAuth variables and confirm whether your deployment should use SANDBOX_TYPE=e2b with E2B_API_KEY instead of the host socket.

Frequently asked questions

Official sources

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