---

What is Puppyone?

Puppyone provides context hosting for AI agents, with Git version control and file-level scoped permissions for every agent.

It supports CLI, MCP, Git, bash/SSH, and web app interactions through Access Points for different AI agents.

One shared Context Drive, multiple scoped Access Points for different agents and tools.

---

Get Started

1. Install / Deploy

Option A: Cloud (Hosted)

The fastest way — no infrastructure to manage.

Create an account at puppyone.ai.

Option B: Self-Hosted (Docker)

Run the full stack locally with Docker. The only prerequisite is Docker.

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

This starts everything — PostgreSQL, Auth, API gateway, Redis, MinIO, backend, and frontend — in a single command. The database schema is applied automatically on first run.

The Docker defaults already separate browser-facing URLs (localhost) from container-internal service URLs (api, kong), so the same setup works for both client-side and Next.js server-side requests.

The backend container also mounts the host Docker socket and a dedicated sandbox temp directory, so agent bash and sandbox endpoints work out of the box in the local Compose stack without changing the backend's global temp directory behavior.

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:9090
Supabase API	http://localhost:8000
MinIO Console	http://localhost:9001

Security note: The local Docker stack enables Docker-backed sandboxes by sharing the host Docker daemon with the backend container. This is convenient for local self-hosting, but for remote or multi-tenant deployments you should prefer SANDBOX_TYPE=e2b with an E2B_API_KEY.

The first startup may take 1-2 minutes. Then open http://localhost:3000. If the web app is not reachable yet, run docker compose ps.

Optional: to enable agent chat in the self-hosted stack, add your ANTHROPIC_API_KEY to docker/.env and restart:

cd docker
docker compose up -d

Optional: OAuth connectors such as GitHub, Gmail, and Google Drive require provider credentials in the backend environment. See backend/.env.example for the current variables.

2. First Run (for both cloud and self-host)

The product flow is the same for Cloud and self-hosted once the stack is running. Start by opening the web app and signing in:

• Cloud: puppyone.ai
• Self-Hosted: http://localhost:3000

If you want to manage your workspace from the CLI, install it and sign in:

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

For self-hosted, choose Local at the prompt or pass -u http://localhost:9090.

The CLI stores sessions per target, so you can switch between Cloud and self-hosted without re-entering credentials (puppyone auth targets switch <url>).

1. Create your first Context Drive

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

This creates a project and sets it as active. You can also create your first project directly from the web app.

2. Add your first content

Start with something that works immediately in both Cloud and self-hosted:

Source	Action
Webpage	puppyone access add url https://example.com --scope /refs
Files or folders	Upload directly from the web app

Use target folders to organize uploaded or synced content into any path in your Context Drive.

3. Optional: Enable More Features

• Agent chat — In self-hosted deployments, add ANTHROPIC_API_KEY to docker/.env and restart the stack.
• OAuth connectors — In self-hosted deployments, configure provider credentials in the backend environment before using GitHub, Gmail, Google Drive, and other OAuth-based sources.
• Distribute via MCP — Create an MCP endpoint when you want agents in Cursor, Claude Desktop, or other MCP clients to read your Context Drive:

puppyone access add mcp "My Context"
# → outputs MCP endpoint URL and API key

See the documentation for supported sources and advanced setup details.

---

Features

Connected

Connect context from SaaS tools, databases, and the web into agent-friendly files.

Puppyone provides built-in source connectors for GitHub, Gmail, Google Drive, Google Docs, Google Sheets, Google Calendar, Google Search Console, web pages, local filesystem access, and Supabase databases.

All data is transformed into agent-friendly formats (Markdown, JSON, raw files) and stored in your Context Drive — a cloud file system that any agent can browse like a local directory.

Collaborative

Agent-level auth, versioning, audit, and collaboration — built for agents, not humans.

• File Level Security (FLS) — Per-agent file permissions enforced at the filesystem layer. If an agent doesn't have access, the file physically doesn't exist in its environment. Think Row Level Security (RLS), but for files.
• Version history & rollback — File-level versioning with diff comparison and one-click rollback. Folder-level snapshots for bulk recovery.
• Audit logs — Every read and write operation is recorded: who did what, to which file, and when.
• Checkout / commit workflow — Locking, conflict detection, and resolution for concurrent agent edits.

Accessible

One Context Drive, many ways in. Your agents access it however they work best:

• MCP (Model Context Protocol) — Auto-generated MCP endpoints for each agent. Connect Cursor, Claude Desktop, Windsurf, Cline, or any MCP-compatible client in seconds.
• Sandbox — Isolated Docker/E2B containers with only the authorized files mounted. Agents execute code securely without seeing anything they shouldn't.
• REST API — Full programmatic access. Read, write, query, and manage everything.
• CLI — Every operation available via puppyone command line, so AI coding tools like Claude Code can drive the platform directly.
• Local folder sync — Real-time bidirectional sync between local directories and the cloud Context Drive via the OpenClaw protocol.

---

Tech Stack

Layer	Technology
Backend	Python 3.12+ / FastAPI
Frontend	Next.js 15 / React 18 / TypeScript / Tailwind CSS
CLI	Node.js / Commander.js
Database	Supabase (PostgreSQL)
Auth	Supabase Auth (JWT + Access Key)
Storage	AWS S3 / MinIO / LocalStack
Task Queue	ARQ (Redis)
Sandbox	Docker / E2B

---

Contributing

We welcome issues, feature requests, and pull requests.

• For small fixes, open a PR directly.
• For larger changes, file an issue first to discuss the design.

See CONTRIBUTING.md for development setup and guidelines.

---

License

Puppyone is open source under the Apache License 2.0.

You can use, modify, and distribute Puppyone freely — for personal projects, internal company tools, self-hosted deployments (single- or multi-tenant), commercial products, and managed services — subject to the standard Apache 2.0 terms (preserve copyright and NOTICE, document significant modifications, and note that no trademark rights are granted).

See LICENSE for the full license text and NOTICE for attribution of bundled third-party components.

Trademarks. "Puppyone", "PuppyOne", and the Puppyone logo are trademarks of PuppyOne authors and are not licensed under Apache 2.0. If you fork or redistribute, please use a different name and logo for your distribution.

Hosted service. puppyone.ai is the official managed offering operated by the PuppyOne team. The hosted service is governed by its own Terms of Service.