# Userland agent context

Userland publishes apps to immutable app origins at https://<app_id>.apps.userland.fun/. Use the control-plane API or CLI from a server-side tool with USERLAND_API_KEY in the environment.

Do not expose USERLAND_API_KEY or app secrets in frontend code. Do not invent platform internals for app code. Use manifest.userland.json and the Userland runtime ctx APIs.

Core URLs:
- API: https://api.userland.fun
- Examples: https://github.com/dwrtz/userland-public
- Public CLI source: https://github.com/dwrtz/userland-public/tree/main/cli
- Runtime types: https://docs.userland.fun/types/runtime-context-v0.d.ts
- Manifest schema: https://docs.userland.fun/schemas/resource-manifest-v0.schema.json
- OpenAPI: https://docs.userland.fun/openapi.json

Recommended flow:
1. Read /start, /quickstarts/full-stack-app, /reference/resource-manifest, /reference/runtime-ctx, /reference/api, and /reference/cli.
2. Create manifest.userland.json, public assets, and server/index.js when dynamic behavior is needed.
3. Validate secrets, resources, runtime fallback, and file paths before publishing.
4. Publish with the CLI or PUT /v0/apps.
5. Report app_id, origin, release_id, activation status, and rollback instructions.

Docs routes:
- https://docs.userland.fun/start: The shortest path for a coding agent to build and publish a Userland app.
- https://docs.userland.fun/agents: Operational rules for autonomous and supervised coding agents using Userland.
- https://docs.userland.fun/skills: How Userland repo-scoped Codex skills fit into the agent workflow.
- https://docs.userland.fun/prompts: Copyable prompts for handing a Userland app build to a coding agent.
- https://docs.userland.fun/quickstarts/static-app: Publish a static Userland app with only public assets.
- https://docs.userland.fun/quickstarts/server-app: Publish a dynamic app with a Userland server entrypoint.
- https://docs.userland.fun/quickstarts/full-stack-app: Build a Userland app with static UI, server routes, auth, data, and secrets.
- https://docs.userland.fun/quickstarts/from-example: Start from a public Userland example and adapt it safely.
- https://docs.userland.fun/concepts/apps-and-releases: How Userland app identity, immutable releases, activation, and rollback work.
- https://docs.userland.fun/concepts/resources-and-state: How managed resources relate to durable app state.
- https://docs.userland.fun/concepts/runtime-routing: Request routing order for static files, reserved paths, and server fallback.
- https://docs.userland.fun/concepts/security-boundaries: Userland control-plane, product, and app-runtime trust boundaries.
- https://docs.userland.fun/guides/data: Declare and use app-scoped data collections.
- https://docs.userland.fun/guides/auth: Add app-user auth, roles, invites, and sessions.
- https://docs.userland.fun/guides/files: Declare file stores and generate runtime file URLs.
- https://docs.userland.fun/guides/secrets: Declare, set, and read app secrets safely.
- https://docs.userland.fun/guides/jobs: Declare manual and scheduled jobs for server-side background work.
- https://docs.userland.fun/guides/webhooks: Declare provider webhooks and handle verified deliveries.
- https://docs.userland.fun/guides/rollback: Move an app live pointer back to a compatible release.
- https://docs.userland.fun/guides/resource-migrations: Change resources safely under Userland v0 monotonic resource rules.
- https://docs.userland.fun/guides/troubleshooting: Debug publish, activation, runtime, job, webhook, secret, and rollback failures.
- https://docs.userland.fun/reference/api: Userland v0 control-plane endpoints and request patterns.
- https://docs.userland.fun/reference/resource-manifest: The app metadata, runtime, resource, and release file contract.
- https://docs.userland.fun/reference/runtime-ctx: The server-side Userland runtime context available to app modules.
- https://docs.userland.fun/reference/cli: Userland CLI command surface for publishing and operations.
- https://docs.userland.fun/reference/agent-skills: Reference for Userland repo-scoped Codex skills and expected coverage.
- https://docs.userland.fun/reference/errors: Error response format and common status codes.
- https://docs.userland.fun/reference/limits: Current v0 release and runtime limits agents should validate before publishing.
- https://docs.userland.fun/examples: Public examples catalog agents can copy from.
- https://docs.userland.fun/changelog: Human and agent-visible notes for docs, API, runtime, examples, skills, and CLI changes.