# Hamster OSS

> Hamster OSS is a shared workspace for product teams and their coding agents. People and agents work from the same threads and knowledge graph, and the team's delivery and releases run in the same place. Each team gets a hosted instance at https://<your-team>.tryhamster.dev with its own MCP server at /mcp (OAuth, scope system:access). The `system` CLI installs and runs Hamster OSS on macOS (Apple silicon) and Linux (x86-64).

To set a person up, read https://tryhamster.dev/SKILL.md and follow it. It is an Agent Skill (https://agentskills.io) written to you, the agent, and goes from sign-up to a connected instance.

Who it's for: product teams that build software with coding agents (Claude, ChatGPT, Cursor and other MCP clients) and want those agents working from the team's real context.

What you get: a hosted instance with Studio (threads, documents, permissions, review decisions), a knowledge graph of the team's Markdown documents, an MCP server with six tools, and the `system` CLI.

How access works: creating an account, organization and agent OAuth connection is free. Sign up at https://tryhamster.dev/signup, create an organization, and save and verify an eligible first card to receive $15 without a payment. Micro instances start from $9 a month. Someone invited by Hamster claims a single-use code at https://tryhamster.dev/claim and needs no card. Design Partner credit defaults to $150 and stacks with the $15 starter credit. Every step: https://tryhamster.dev/get-access.

Credits pay for instance time, inference and storage from one balance. At exhaustion, compute pauses and data is preserved; add funds or opt into automatic top-up to continue. Saving a card never enables automatic top-up. Downloading and running Hamster OSS locally or on your own cloud VM has no Hamster fee; your cloud provider may charge for its resources.

Account tokens come from tryhamster.dev's OAuth server and act for one person within the approved scopes; instance tokens belong to one instance and one project. The default account MCP flow never moves money or handles card details; the person completes Stripe-hosted pages. The REST-only MPP top-up endpoint accepts Stripe Shared Payment Tokens after explicit billing:pay OAuth consent; see https://tryhamster.dev/developers. Hamster Studio at tryhamster.com is a separate product from the same company, Wheel Go Fast, Inc.

When to use Hamster:
- A person gave you their team's instance address (https://<your-team>.tryhamster.dev) and wants you to read and add to the team's threads and documents, or search its knowledge.
- You need to ask the team's Discovery agent a question, or follow and steer a delivery thread.
- A user asks how to sign up, what an instance costs, or how to connect an agent to Hamster OSS. With the person's approval you can create an instance for them through https://tryhamster.dev/mcp.
- A user asks how to install, start, stop or update Hamster OSS on their own macOS (Apple silicon) or Linux (x86-64) machine.

Not a fit:
- Anonymous use of a team's data: hosted instances need an account, available credit or prepaid funds and the person's approval.
- General-purpose hosting, code execution or file storage outside a Hamster project.
- Windows, Intel Mac or ARM Linux installs: release tracks have builds only for darwin-arm64 (macOS on Apple silicon) and linux-amd64 (Linux on x86-64).
- Hamster Studio at tryhamster.com is a separate product with its own MCP server at https://tryhamster.com/mcp. Don't mix its tokens or URLs with tryhamster.dev.
- The tryhamster.dev dashboard API under /api/v1 (outside /api/v1/agent) is for signed-in people in a browser and never accepts agent tokens.

How agents should call Hamster:
1. To read these docs, check prices, or set a person up, use the Hamster OSS account MCP server at https://tryhamster.dev/mcp (Streamable HTTP). `get_pricing`, `search_docs`, `fetch_doc` and `get_install_command` need no token. `status`, `create_instance`, `get_instance`, `add_payment_method`, `add_funds` and `redeem_code` need an OAuth token from tryhamster.dev itself: the first call without one answers 401 with `WWW-Authenticate: Bearer resource_metadata="https://tryhamster.dev/.well-known/oauth-protected-resource/mcp", scope="account:read account:write instances:write billing:write"`. Access is self-serve, with no API key to request: register your own client with `POST https://tryhamster.dev/oauth/register` (RFC 7591 dynamic client registration, public client, no secret; it answers 201 with a `client_id`) or use a Client ID Metadata Document URL as `client_id`, then run the authorization code flow with S256 PKCE while the person approves you in the browser. There is no sandbox or test environment; the $15 starter credit is how a person tries it. The REST twin is `https://tryhamster.dev/api/v1/agent/*`.
2. To work in a team, use the instance's MCP server: `POST https://<your-team>.tryhamster.dev/mcp` (Streamable HTTP, JSON-RPC 2.0, JSON responses, no server sessions).
3. Without a token it answers 401 with `WWW-Authenticate: Bearer resource_metadata="https://<your-team>.tryhamster.dev/.well-known/oauth-protected-resource/mcp", scope="system:access"`.
4. Read that protected resource metadata (RFC 9728), then `/.well-known/oauth-authorization-server` (RFC 8414) on the same host.
5. Register with `POST /oauth/register` (RFC 7591, public client, no secret), then run the authorization code flow with S256 PKCE and scope `system:access`. A team member signs in and picks the project. There are no refresh tokens; reconnect when the token expires.
6. Send `Authorization: Bearer <token>` on every request. Call `tools/list`; the tools are create, read, update, delete, search and message. Start with `read /`.
7. To install the CLI, run `curl -fsSL https://dl.tryhamster.dev/install.sh | sh`. It checks the catalog signature and the build checksum before installing `~/.local/bin/system`. Choose a release track with `SYSTEM_TRACK` or `--track` and the install directory with `SYSTEM_PREFIX` or `--prefix`.

## Docs

- [Set up Hamster OSS](https://tryhamster.dev/SKILL.md): an Agent Skill for setting a person up, from sign-up and credit activation to a connected instance
- [Docs llms.txt](https://tryhamster.dev/docs/llms.txt): an index of the guides alone
- [Developers llms.txt](https://tryhamster.dev/developers/llms.txt): an index of the API, MCP and machine-readable files alone
- [Docs](https://tryhamster.dev/docs.md): every guide, with a quickstart
- [Get access](https://tryhamster.dev/get-access.md): from sign-up or an invitation to a connected agent, step by step
- [Pricing](https://tryhamster.dev/pricing.md): Micro $9, Small $129, Medium $259 and Large $519 a month, usage rates, prepaid billing
- [Hamster OSS API](https://tryhamster.dev/developers.md): authentication, endpoints and example requests
- [Hamster OSS MCP server](https://tryhamster.dev/docs/mcp.md): the instance endpoint and the Hamster OSS account MCP server, their tools, sign-in and client setup
- [Hamster OSS account MCP server](https://tryhamster.dev/mcp): docs, pricing and onboarding tools; OAuth with tryhamster.dev for the account tools
- [Hamster OSS CLI](https://tryhamster.dev/cli.md): install script, platforms and release tracks
- [API versioning and deprecation](https://tryhamster.dev/docs/api-versioning.md): MCP protocol revisions, catalog schema version, Deprecation and Sunset headers, 90-day notice
- [OpenAPI 3.1 document](https://tryhamster.dev/openapi.json): the agent REST API at /api/v1/agent, the instance MCP endpoint, its OAuth metadata and the release catalog
- [API catalog](https://tryhamster.dev/.well-known/api-catalog): RFC 9727 linkset pointing to the OpenAPI document and docs
- [MCP server card](https://tryhamster.dev/.well-known/mcp/server-card.json): the instance MCP server, its transport and protocol versions
- [AI catalog](https://tryhamster.dev/.well-known/ai-catalog.json): ARD entries for the instance and account MCP servers, the OpenAPI document, the API catalog and the skills index (also at /.well-known/ard.json)

## Company

- [About](https://tryhamster.dev/about.md): what Hamster OSS is and who makes it
- [Contact](https://tryhamster.dev/contact.md): access, support, security and privacy email addresses
- [Privacy](https://tryhamster.dev/privacy.md): what these pages store and where to send privacy questions
- [GitHub](https://github.com/gethamster): the gethamster organization

## Optional

- [Homepage as Markdown](https://tryhamster.dev/index.md): the homepage text without HTML
- [Agent view](https://tryhamster.dev/?mode=agent): endpoints, authentication and capabilities as JSON
- [Release catalog](https://dl.tryhamster.dev/channels/tracks.json): signed JSON catalog of release tracks read by the installer
- [Sitemap](https://tryhamster.dev/sitemap.xml): every page on this site