Rokcet is the guided business-app builder for novices. A user describes the customer outcome in ordinary language; Rokcet plans, generates, previews, and deploys the app while Buckets.id provides the professional operational engine for managed agents, business knowledge, media, gated access, customer identity, Buckets Credits, bookings, channels, and authoritative actions.

Run locally

Install Node.js 22.5 or newer and dependencies: npm install
Copy .env.example to .env and configure the services you want to use.
Start Rokcet: npm run dev

Product boundary

Rokcet.dev is for novices: plain-language requirements, guided decisions, sensible defaults, preview, and deployment.
Buckets.id is for professionals: APIs, scopes, providers, Developer MCP, Customer MCP, observability, advanced agent configuration, and operational administration.
Generated customer apps show business outcomes rather than raw IDs, schemas, tokens, MCP terminology, or infrastructure controls.

See DEMO_APPS.md and ROKCET_BUCKETS_PRODUCT_MODEL.md for the canonical generated-app model.

Live workspace chat

Rokcet chat is strict about provider execution: it sends the current session's user/assistant history with each turn, streams provider output over /api/llm/execute/stream, and never replaces a missing key, timeout, provider error, or unsupported model with a fabricated successful response. The model selector dispatches to the matching Google Gemini, OpenAI, Anthropic, or Groq API instead of routing every choice through Gemini.

Configure provider credentials with GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, and/or GROQ_API_KEY. A key entered in Models & Keys overrides the corresponding server environment value for that browser session/request. Verify Providers performs real credential checks; unconfigured or rejected providers are reported as such. OpenAI GPT-5.6 generation uses the Responses API. Provider generation timeouts are activity-based: active streams are allowed to continue. Normal GPT-5.6 chat defaults to 5 minutes for first activity and 2 minutes of inactivity; Agent Mode defaults to 10 minutes and 3 minutes. ROKCET_PROVIDER_FIRST_ACTIVITY_TIMEOUT_MS / ROKCET_PROVIDER_INACTIVITY_TIMEOUT_MS provide global overrides, while ROKCET_AGENT_PROVIDER_FIRST_ACTIVITY_TIMEOUT_MS / ROKCET_AGENT_PROVIDER_INACTIVITY_TIMEOUT_MS can tune Agent Mode independently.

Artifact snapshots are created only when a live provider actually returns filename-addressed code deliverables. Normal prose chat does not create synthetic files or snapshots.

Git-backed project source

Authenticated projects use one private Git repository each. main is the reviewed source line, coding sessions use isolated rokcet/session/<uuid> branches and worktrees, and every Snapshot records a verified commit SHA. Preview, downloads, chat context, and deployment source are resolved by the server from that repository; the browser is never the source authority.

For local development, leaving ROKCET_GIT_API_URL empty creates bare repositories under ROKCET_GIT_LOCAL_REMOTE_ROOT. Staging and production must configure the neutral Rokcet Git variables in .env.example for a private Gitea- or Forgejo-compatible service over HTTPS. The service token is server-only and must not be embedded in repository URLs or Git configuration.

Buckets.id integration

Rokcet deliberately keeps the two Buckets MCP/runtime responsibilities separate:

Build time: Rokcet/coding agent -> Buckets Developer MCP -> inspect, plan, ensure, and validate an App composition.
Runtime: generated application -> customer OAuth/API/conversations -> Buckets managed Agent -> authorized customer/runtime tools.
Integration: normal application traffic uses Buckets APIs, OAuth, SSE, and signed webhooks. Developer MCP OAuth credentials are stored server-side per authenticated Rokcet project and are never shipped into generated customer applications.

The bundled showcase demonstrates five polished, source-backed Buckets-powered apps: Velora (AI models booking), GoGame (gaming marketplace + Pro Buddy coaching), OKgo (luxury travel discovery, rich itinerary concierge, and single checkout), Fred Rentals (AI-first car rental discovery and booking), and FOOTPI (football talent intelligence and AI scouting). Velora preserves its dense Luxevibe-style marketplace, full model chat, scenarios, gated media, credits, and multi-step booking; GoGame preserves its cyber marketplace, rich NEXUS concierge, reviews/comparisons/VOD cards, live tactical coaching rooms, bookings, Cyber Vault, and custom Pro Buddy studio; OKgo preserves its supplied stays, experiences, 4K galleries, rich travel messages, itinerary cart, package checkout, trip passes, cancellation/rescheduling, and VIP rewards; Fred Rentals preserves its concierge-first Bedrock interface, rich car/review/comparison/quote/gallery/location messages, fleet discovery, checkout, active rentals, Digital Stone Keys, extensions, roadside support, and membership rewards. FOOTPI preserves its scouting workspace, criteria builder, shortlist, role-aware scout/agent/owner flows, rich player cards, gated profiles, radar/comparison views, tactical analysis, and acquisition intelligence. The seeded experience is deterministic in preview; connected deployments use real Buckets customer OAuth, managed conversations, bookings, media, access, Buckets Credits, channels/handoff, and signed webhooks.

Required server-side environment

See .env.example. Rokcet does not use a permanent BUCKETS_DEVELOPER_MCP_TOKEN or BUCKETS_OPERATOR_TOKEN. Developer MCP access is authorized interactively per developer/project with Buckets Authorization Code + PKCE, then the rotating access/refresh credentials are encrypted at rest in Rokcet's server database. BUCKETS_CUSTOMER_TOKEN remains optional for the separate customer-runtime testbed and must not be exposed to browser code.

Observability

Open Inspector -> BUCKETS RUNTIME to inspect real Buckets Agent runs, model/token/BC usage, tool calls, authorization decisions, errors, and timing. Trace access uses the same project-scoped Developer MCP OAuth connection with the dedicated read-only developer:observability:read scope; no static operator token is required. Set BUCKETS_CONSOLE_URL to enable deep links into the source-of-truth Buckets Runtime Runs view. Rokcet does not fabricate observability data when Buckets is disconnected.

Buckets Developer MCP authorization

Developer SSO and Developer MCP authorization are separate layers:

SSO answers who the Rokcet developer is. It uses ROKCET_SSO_CLIENT_SECRET server-to-server.
Developer MCP OAuth authorizes one Rokcet project against exactly one dedicated Buckets App. It uses Authorization Code + PKCE and no MCP client secret.

From Rokcet, open Buckets -> MCP Developer Tools -> Connect Buckets App. Rokcet redirects to auth.buckets.id with the current project identity. The developer selects the Organization and approves the scopes; Buckets creates the project's dedicated App on first authorization and reuses that same App on later authorizations. Buckets redirects back to /api/buckets/mcp/oauth/callback; Rokcet exchanges the one-time code, encrypts the rotating access/refresh tokens using ROKCET_SESSION_SECRET, and binds the connection to that Rokcet user + workspace + project. Rokcet has no workspace-shared Buckets authorization fallback.

For production, APP_URL=https://rokcet.dev automatically makes Rokcet's Client ID Metadata Document:

https://rokcet.dev/.well-known/buckets-developer-mcp-client

and the default callback:

https://rokcet.dev/api/buckets/mcp/oauth/callback

ROKCET_MCP_REDIRECT_URI and ROKCET_MCP_CLIENT_ID are optional overrides. Local http://localhost development automatically falls back to Buckets Dynamic Client Registration because Client ID Metadata Documents are HTTPS-only.

Shared Buckets developer SSO

Rokcet uses Buckets as the authority for developer identity. This is intentionally separate from Buckets customer OAuth/OIDC, which remains for end users of Buckets-powered applications.

The browser flow is:

Rokcet redirects the developer to BUCKETS_IDENTITY_URL/developer/sso/authorize with an exact callback URI and CSRF state.
Buckets reuses its host-only developer SSO cookie. If no shared session exists, Buckets shows its normal developer login/signup page.
Buckets sends Rokcet a short-lived, single-use authorization code. The developer password never returns to Rokcet.
Rokcet exchanges the code server-to-server using ROKCET_SSO_CLIENT_SECRET, maps the canonical Buckets developer ID to a local Rokcet account, then issues its own HttpOnly product session.

LOGIN WITH DEMO remains available on the Rokcet auth page. It creates a signed, isolated eight-hour demo session and never creates or impersonates a Buckets account.

Production settings

Use matching values on the two services:

Buckets: ROKCET_SSO_CLIENT_ID=rokcet.dev
Buckets: ROKCET_SSO_CLIENT_SECRET=<strong random shared secret>
Buckets: ROKCET_SSO_REDIRECT_URIS=https://rokcet.dev/api/auth/sso/callback
Rokcet: BUCKETS_IDENTITY_URL=https://auth.buckets.id
Rokcet: ROKCET_SSO_CLIENT_ID=rokcet.dev
Rokcet: ROKCET_SSO_CLIENT_SECRET=<same shared secret>
Rokcet: ROKCET_SSO_REDIRECT_URI=https://rokcet.dev/api/auth/sso/callback
Rokcet: APP_URL=https://rokcet.dev
Rokcet: ROKCET_SESSION_SECRET=<independent strong random secret>

Rokcet's current account and product metadata are stored in the SQLite file configured by ROKCET_DATABASE_PATH through numbered schema migrations. Project source is not stored in SQLite. PostgreSQL remains the durable production direction; the future database adapter change must preserve project IDs, repository identities, session branches, and Snapshot SHAs. Do not horizontally scale the SQLite-backed control plane.

Rokcet project contracts and adapters

The project contract is the source of truth for architecture:

Application profile describes whether the product is full-stack or frontend-only.
Stack adapter defines framework rules, generated-agent constraints, build commands, and file validation.
Deployment adapter defines hosting capabilities and provider-specific deployment/URL behavior without owning the app stack.
Service adapters describe external capability ownership such as Buckets.id or PostgreSQL.
Capability requirements prevent incompatible combinations such as a persistent server on a serverless-only deployment target.

The agent prompt is assembled from these independent contracts at request time. This keeps the core agent provider-neutral and makes a future hosting migration an adapter/configuration change instead of a rewrite of Buckets integration or every generated application.

Adapter-based 1-click production deployment

Rokcet now treats deployment as a project contract rather than a Vercel assumption. Each project has an application profile, stack profile, deployment adapter, optional service adapters, and machine-readable capability requirements. The same contract is injected into the coding agent, validated against the snapshot before deploy, and used to select build/provisioning behavior. The deployer no longer rewrites arbitrary generated code into a Vite scaffold.

The current production deployment adapter is Vercel. The default full-stack profile is Next.js + TypeScript and uses framework-native Route Handlers for trusted server work. A frontend-only Vite + React + TypeScript profile remains available as a separate stack contract. Adding a future deployment provider should be implemented as another deployment adapter with its own runtime capabilities, project URL resolver and deployment API implementation; Buckets and database service contracts remain independent.

Managed database provisioning is opt-in through the project contract. When a project requests a managed PostgreSQL database on the current Vercel adapter, Rokcet can use the Vercel Marketplace Neon integration. Application code receives a generic DATABASE_URL contract rather than depending on provider-specific variable names. Configure VERCEL_TOKEN and, for team deployments, VERCEL_TEAM_ID. The Neon Marketplace integration is only required for projects whose contract requests an automatically managed database; Buckets demo projects do not request one by default.

VERCEL_NEON_INTEGRATION_CONFIG_ID, VERCEL_NEON_PRODUCT_ID_OR_SLUG, VERCEL_NEON_BILLING_PLAN_ID, VERCEL_NEON_REGION, and VERCEL_NEON_RESOURCE_METADATA_JSON remain optional Vercel/Neon adapter overrides. Persistent infrastructure records keep provider and management-provider identifiers separate from application logic.

Demo sessions cannot create real production deployments. Reusing a snapshot ID with different source content is rejected so a deployed snapshot remains immutable. The generic deployment bundle is now the authored snapshot source at the project root; stack-specific validation rejects source that violates the selected contract before any provider request is made.

The generic deployer does not bind a custom rokcet.dev domain yet. The live URL shown is whatever public URL the selected deployment adapter returns. Ploi, Forge, and Custom MCP advanced deployment modes remain simulated placeholders.

Standard app templates and rich messages

New Rokcet projects use a three-step tutorial and can start from Concierge, Chat First, Discover First, or a custom composition. The selected source-backed starter is persisted with the project and adapted by the build agent. See ROKCET_STANDARD_APP_TEMPLATES.md.

All starters render the Buckets-owned buckets.rich-message version 1 semantic contract and keep required text fallback. External channel adapters remain a Buckets concern and are not assumed to be connected.