Skip to content

Overview

Architecture overview

The apps, core libraries, and services that make up AgentKitProject — local-first by design, with optional cloud.

AgentKitProject is local-first: building, validating, packaging, importing, and exporting kits work fully offline with no account. Cloud services (Market, Profile, Auto) are optional integrations layered on top — never preconditions for local work.

The pieces

  • Forge is the client. Forge is the hosted / self-hostable browser app (a Next.js app); the CLI covers local-first and headless work. Both build, edit, validate, package, import, and export .agentkit.zip kits.
  • All non-UI Forge capability lives in @agentkitforge/core: validation, packaging, import/export, drafts, prepared prompts, build-context, the spec (SPEC.md), the CLI, and the hosted-Market client. The browser client and the CLI share this same engine.
  • Market is the catalog. A Next.js 15 web app serves the public catalog, submission UI, and admin review queue, and is the only writer to the Market backend. See Market.
  • Profile is shared identity. A Next.js account + public-profile app; the canonical display name lives here. See Profile.
  • AgentKitAuto runs kits unattended in the cloud — on demand, on schedules, and from webhooks. See AgentKitAuto.
  • Shared packages: @agentkitforge/ui (design system used by every app) and @agentkitforge/contracts (the contracts-first package every cross-repo payload, route, status enum, and service URL flows through).

The two auth paths (they never mix)

  • Forge device auth — Forge and the CLI sign in via an OAuth 2.0 device flow against WorkOS. The access token is stored in OS secure storage and sent as a bearer token to the Market app's /api/forge/* routes. Headless-friendly: approve the code from any browser.
  • Browser AuthKit cookie sessions — the Market and Profile web apps use WorkOS AuthKit cookie sessions for their browser-facing routes.

These are separate auth paths and are never conflated; a route uses one or the other, never both.

Hosting

The hosted ecosystem runs on managed Kubernetes (DigitalOcean Kubernetes / DOKS). The same web and worker images run on hosted or self-hosted infrastructure, with cloud coupling abstracted behind swappable adapters — so you can self-host the same code on your own cluster.

Where logic belongs. All non-UI capability lives in @agentkitforge/core so Forge (the browser client) and the CLI behave identically.