# TinyCloud

TinyCloud is a user-owned personal data layer. Applications and agents access
spaces through explicit, scoped capabilities instead of shared account
credentials.

## Start here

- Documentation index: https://docs.tinycloud.xyz/llms.txt
- Explore a user's TinyCloud: https://docs.tinycloud.xyz/guides/access-and-explore-my-tinycloud
- Exploration guide as Markdown: https://docs.tinycloud.xyz/guides/access-and-explore-my-tinycloud.md
- TinyCloud CLI: https://docs.tinycloud.xyz/cli/overview
- CLI authentication: https://docs.tinycloud.xyz/cli/authentication
- TinyCloud MCP: https://docs.tinycloud.xyz/cli/mcp
- TinyCloud MCP as Markdown: https://docs.tinycloud.xyz/cli/mcp.md
- Account and spaces: https://docs.tinycloud.xyz/cli/account
- Key-value storage: https://docs.tinycloud.xyz/cli/storage
- Delegation artifacts: https://docs.tinycloud.xyz/cli/auth-artifacts
- Agent-readable app data: https://docs.tinycloud.xyz/guides/agent-readable-apps
- Protocol index: https://protocol.tinycloud.xyz/llms.txt

## Choose an access path

Use MCP first for agent workflows. `@tinycloud/mcp` is a separate package,
installed alongside `@tinycloud/cli`. It is a local stdio server, not a hosted
HTTP endpoint or a `tc` subcommand. Both packages require Node.js 20 or newer.
The 16-tool data surface requires `@tinycloud/mcp` 0.2.0 or newer and a
TinyCloud node running 1.6.0 or newer.

The MCP server covers local and authorization status, exact permission requests
and delegation imports, account space and application discovery, delegated
secret reads, bounded KV CRUD with strong ETags, and bounded SQLite schema,
query, and data-mutation operations. Treat file-like KV values according to the
owning app's manifest and schema.

Install the stable packages and create a delegated profile:

```sh
npm install --global @tinycloud/cli @tinycloud/mcp
tc profile create agent --posture delegate-session --operator agent
```

A newly created delegate profile must bootstrap once before MCP starts:

```sh
tc --profile agent --quiet --json auth request \
  --cap tinycloud.kv:account:spaces/:get,list \
  --emit request.json
tc --profile owner --quiet --json auth grant request.json --yes > delegation.json
tc --profile agent --quiet --json auth import delegation.json
```

Configure the MCP client with the explicit delegate profile:

```json
{
  "mcpServers": {
    "tinycloud": {
      "command": "tinycloud-mcp",
      "args": ["--profile", "agent"]
    }
  }
}
```

Explore with `tinycloud_account_spaces_list`,
`tinycloud_account_applications_list`, `tinycloud_kv_list`, and
`tinycloud_kv_get`, in that order as relevant. Use `tinycloud_kv_head` to read
the current ETag before `tinycloud_kv_put` replacement or
`tinycloud_kv_delete`. Use `tinycloud_sql_schema_inspect` before bounded reads
with `tinycloud_sql_query`; `tinycloud_sql_execute` accepts only a single
parameterized `INSERT`, `UPDATE`, or `DELETE` and requires explicit
acknowledgement of database-wide write authority.

Use the CLI to create profiles, exchange exact authorization artifacts, and
perform owner-side inspection. Current `tc account` commands derive the account
registry from the active profile, so delegated agents should use MCP for account
and KV exploration.

## Owner-side CLI inspection

With an explicit owner profile:

```sh
tc --profile owner --quiet --json status
tc --profile owner --quiet --json account spaces list --live
tc --profile owner --quiet --json account apps list --live
```

For delegated exploration, call the MCP account tools and preserve any returned
`tinycloud.auth.request` exactly. Have the owner approve that artifact, import
the returned delegation, and retry the original tool. Start with metadata and
key names, read values only when relevant, never request an owner private key,
and never broaden a requested capability.

When a discovered app manifest points to an agent-readable knowledge bundle,
read its declared knowledge root before interpreting or modifying app data.

## Source

- TinyCloud repositories: https://github.com/TinyCloudLabs
- JavaScript SDK and CLI: https://github.com/TinyCloudLabs/js-sdk