# NetScript > Deno-native, polyglot backend framework: type-safe services and durable workflows in one workspace — observable by default and orchestrated with Aspire, from `netscript init` to a running, type-checked backend. **For AI agents:** NetScript is Deno-native and pre-1.0 (0.0.1-beta.11) — treat every API as unstable. Every documentation page has a clean Markdown twin: append `index.md` to any page URL (for example https://rickylabs.github.io/netscript/reference/telemetry/index.md) to read source-quality Markdown instead of rendered HTML. Prefer the `.md` twins when reasoning about the docs. All links below are absolute and canonical. A single concatenated corpus of every page is available at https://rickylabs.github.io/netscript/llms-full.txt. ## Getting started - [NetScript — the enterprise-grade meta-framework for Deno](https://rickylabs.github.io/netscript/): NetScript is the enterprise-grade meta-framework for Deno: contract-first, end-to-end typed, cloud-agnostic. One unified API from typed services and durable workflows to orchestration, observability… - [AI](https://rickylabs.github.io/netscript/ai/): The NetScript AI stack is a set of composable seams for building agentic chat and tool-calling surfaces on the same contracts-first, hexagonal foundation as the rest of the framework. It is… - [Agent tooling](https://rickylabs.github.io/netscript/ai/agent-tooling/): The rest of this pillar is about the AI you build into your app — the engine, the MCP client stack, durable chat. This page is the mirror image: what NetScript gives the coding agents (and the humans… - [Chat UI](https://rickylabs.github.io/netscript/ai/chat-ui/): The AI chat interface ships as a copy-registry collection in @netscript/fresh-ui: a composer, a message thread, tool-call cards, a model picker, and a generative-UI block renderer. alpha - [Durable chat](https://rickylabs.github.io/netscript/ai/durable-chat/): @netscript/fresh/ai is the server + island seam that turns a Fresh route into a durable AI chat: a chat whose message history and in-flight tool calls survive reload, reconnect, and multi-tab replay… - [AI engine](https://rickylabs.github.io/netscript/ai/engine/): This is the engine guide — how the pieces of @netscript/ai fit together and when to reach for each one. @netscript/ai is the provider-agnostic AI engine at the design center of the stack: a… - [Recipes](https://rickylabs.github.io/netscript/ai/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Build a durable chat](https://rickylabs.github.io/netscript/ai/how-to/build-a-durable-chat/): Goal: wire an AI chat onto a Fresh route whose message history and in-flight tool calls survive reload, reconnect, and a second tab — because the transcript is backed by a durable session stream, not… - [MCP](https://rickylabs.github.io/netscript/ai/mcp/): @netscript/ai/mcp is the MCP client stack: it turns external Model Context Protocol servers into typed tools your agent loop can call — transports, injected auth, multi-server pooling, and a safe… - [CLI reference](https://rickylabs.github.io/netscript/cli-reference/): This is the cheat-sheet: which netscript command we reach for, grouped by task. Each section lists the everyday spelling and stops there — every flag, subcommand, and extended verb lives in the… - [Core concepts](https://rickylabs.github.io/netscript/concepts/): The contract is the source of truth, the host is empty until plugins fill it, and one runtime brings up many resources together. Hold these three and the rest of the docs read as detail. - [Glossary](https://rickylabs.github.io/netscript/glossary/): NetScript is a small framework with a handful of load-bearing words. Most of the friction in learning it is vocabulary, not syntax — once you can map a term to the file it lives in and the API that… - [Quickstart](https://rickylabs.github.io/netscript/quickstart/): From nothing to a running NetScript workspace you can watch boot — in about five minutes. Three commands: install the CLI, scaffold a project, then bring it up under Aspire, which starts Postgres and… - [Aspire quickstart](https://rickylabs.github.io/netscript/quickstart/aspire/): A NetScript workspace is never one process — it is a Fresh app, oRPC services, plugin APIs, background processors, a database, and a cache. Aspire is how we make that whole fleet start with one… - [Why NetScript](https://rickylabs.github.io/netscript/why/): NetScript is one coordinated workspace where the contract you define is the client you call, workflows survive crashes by design, and tracing is wired in from line one. ## Tutorials - [Tutorials](https://rickylabs.github.io/netscript/tutorials/): Tutorials are for learning by building. Each one walks a fixed path from an empty directory to a running application — no step skipped, every rung proven by a real command or endpoint. You don't need… - [AI Chat](https://rickylabs.github.io/netscript/tutorials/chat/): This track builds one thing end to end: a durable AI chat app — think a production support-chat surface, the kind of assistant a real product ships next to its docs. By the last chapter you will have… - [Scaffold the chat workspace](https://rickylabs.github.io/netscript/tutorials/chat/01-scaffold/): Every track starts with a real project on disk. In this chapter you create chat-app/ — a NetScript workspace with a Fresh frontend — add the streams runtime so durable chat sessions have somewhere to… - [The durable chat route](https://rickylabs.github.io/netscript/tutorials/chat/02-durable-chat-route/): The backend of a durable chat is two routes and one model call. In this chapter you wire the session route (runs a model turn, persists it durably, gated by authorize), the one stream proxy the… - [The chat UI](https://rickylabs.github.io/netscript/tutorials/chat/03-chat-ui/): The backend streams and persists turns; now it needs a face. In this chapter you copy the fresh-ui ai component collection into your app, seed the first paint from resolveChatSnapshot, and hydrate a… - [A server-side tool call](https://rickylabs.github.io/netscript/tutorials/chat/04-tool-call/): A chat gets useful when the model can do something. In this chapter you give the model one server-side tool, pass it into the same chat() call from chapter 2, and surface the invocation in the UI as… - [MCP tools & widgets](https://rickylabs.github.io/netscript/tutorials/chat/05-mcp/): Chapter 4's tool was code you wrote. Real products also need capabilities that live behind Model Context Protocol servers — a docs-search server, an ops server, a vendor's tool endpoint. In this… - [Live streaming](https://rickylabs.github.io/netscript/tutorials/chat/06-live-streaming/): Your chat works, but it still feels turn-based: chapter 3's island fires a turn, waits for it to settle, then re-materializes the transcript in one jump. Real chat streams — the reply appears token… - [ERP Sync](https://rickylabs.github.io/netscript/tutorials/erp-sync/): Your team is mid-migration between two ERPs. SAP, the legacy system, is still the system of record — production plans against it every day. Microsoft Dynamics, its replacement, goes live in stages… - [Scaffold the workspace](https://rickylabs.github.io/netscript/tutorials/erp-sync/01-scaffold/): This is the first chapter of the ERP Sync track — the service that keeps Microsoft Dynamics, the ERP your team is migrating to, fed from the file exports of SAP, the legacy system that is still the… - [A CSV file-watch import job](https://rickylabs.github.io/netscript/tutorials/erp-sync/02-import-job/): In Chapter 1 you stood up my-erp/ with the workers and triggers plugins running. Now you wire the first real piece of the pipeline: a file-watch trigger that fires the moment the SAP export job drops… - [A polyglot transform task](https://rickylabs.github.io/netscript/tutorials/erp-sync/03-polyglot-transform/): In Chapter 2 you imported a SAP export as-is. But the SAP export is not a Dynamics import: the legacy system writes material_no where Dynamics wants sku, description where Dynamics wants name, and —… - [Add a queue and a cron schedule](https://rickylabs.github.io/netscript/tutorials/erp-sync/04-queue-and-cron/): Your import job runs one file at a time. A migration does not: the day you backfill Dynamics with SAP's historical exports, twenty files land in the hand-off folder at once, and until cutover the two… - [Run it locally under Aspire](https://rickylabs.github.io/netscript/tutorials/erp-sync/05-deploy/): You have built the whole SAP→Dynamics sync: a file-watch import job, a sandboxed transform task, a queue, and a cron schedule. This final chapter runs all of it together — workers, triggers, queue… - [Live Dashboard](https://rickylabs.github.io/netscript/tutorials/live-dashboard/): An order queue goes wrong quietly. The screen your fulfillment team watches shows five-minute-old rows, so the packing station ships an order the customer cancelled three minutes ago, and a payment… - [Scaffold the dashboard workspace](https://rickylabs.github.io/netscript/tutorials/live-dashboard/01-scaffold/): Every track starts with a real project on disk. In this chapter you create my-dashboard/ — the workspace that will grow into the live order queue from the track index: a Fresh frontend, an orders… - [A typed read-model service](https://rickylabs.github.io/netscript/tutorials/live-dashboard/02-contract-to-service/): In chapter 1 you scaffolded my-dashboard/ and booted it under Aspire. Now you will shape the data the dashboard reads: an orders oRPC contract with a typed list procedure, served by defineService… - [SDK client and cache-first query](https://rickylabs.github.io/netscript/tutorials/live-dashboard/03-sdk-cache-first-query/): In chapter 2 you served an orders.list read-model on port 3002. Now you will read it from the Fresh app. The SDK gives you a typed client built from the same contract, and a query factory that wraps… - [The page builder and the query island](https://rickylabs.github.io/netscript/tutorials/live-dashboard/04-definePage-QueryIsland/): This is the heaviest chapter in the track, and the most rewarding. You will render the orders table with NetScript's definePage builder — its layer / partial / island triad — and hydrate a TanStack… - [Real-time updates with durable streams](https://rickylabs.github.io/netscript/tutorials/live-dashboard/05-live-stream/): In chapter 4 the table was live on the client — it refetched and mutated without a navigation. But it still only knows what it fetched: between revalidations, a cancelled order sits on the screen… - [Run the whole dashboard under Aspire](https://rickylabs.github.io/netscript/tutorials/live-dashboard/06-deploy/): You have built the full spine — contract, service, query layer, page, and live stream. This final chapter steps back and runs the entire graph as one system: the orders service, the Fresh dashboard… - [Build a storefront backend](https://rickylabs.github.io/netscript/tutorials/storefront/): This track is a project, not a tour. Across seven chapters you build a small e-commerce storefront — a products catalog, a cart, a durable checkout, a shipping webhook, and a storefront page — in one… - [Scaffold the storefront](https://rickylabs.github.io/netscript/tutorials/storefront/01-scaffold/): This is chapter 1 of the storefront track. Before you can sell anything you need a workspace on disk and a running system to grow it in. In this chapter you create my-shop/ with the netscript CLI… - [A typed catalog service](https://rickylabs.github.io/netscript/tutorials/storefront/02-catalog-service/): In chapter 1 you scaffolded my-shop/ and watched it boot under Aspire, with a products service answering on :3001. That service is not a placeholder — when you passed --service --db postgres, the… - [Cart, contract-first](https://rickylabs.github.io/netscript/tutorials/storefront/03-cart-contracts/): In chapter 2 you read a typed catalog built around a contract that was largely generated from Prisma. Now you design a domain that does not exist yet — a shopping cart — the other way round: contract… - [Durable checkout](https://rickylabs.github.io/netscript/tutorials/storefront/04-checkout-saga/): In chapter 3 you designed the cart contract. Checkout is what turns a cart into an order — and it is the one place in a shop where a crash mid-flight costs real money. A naive async function that… - [A verified shipping webhook](https://rickylabs.github.io/netscript/tutorials/storefront/05-shipping-webhook/): In chapter 4 your checkout saga sends a create-shipment command and waits for a ShipmentCreated message. But the real signal that a parcel shipped comes from outside your shop — from a carrier or… - [The storefront page](https://rickylabs.github.io/netscript/tutorials/storefront/06-storefront-ui/): Every chapter so far built the backend: a typed catalog, a contract-first cart, a durable checkout, a verified webhook. All of it is reachable by curl — and none of it has a face. This chapter puts… - [Run the whole storefront](https://rickylabs.github.io/netscript/tutorials/storefront/07-deploy/): Across the previous six chapters you built the storefront one piece at a time, usually starting a single service in its own terminal. This final chapter zooms out: you run the entire my-shop/ — the… - [Team Workspace](https://rickylabs.github.io/netscript/tutorials/workspace/): Picture the app this track is modeled on: a production context-accumulator chat application built on NetScript. An operations team lives in it during an ERP cutover — projects and channels full of… - [Scaffold the workspace](https://rickylabs.github.io/netscript/tutorials/workspace/01-scaffold/): You are building the team layer of an operations workspace — the part that will decide who is on the team, where team records live, and which routes a caller may reach. Every chapter in this track… - [Add auth and a session](https://rickylabs.github.io/netscript/tutorials/workspace/02-auth/): You have a running workspace, but anyone can hit it — and for the app this track is building, that is not a cosmetic gap. A team workspace exists to hold things the whole internet must not read… - [Workspace data](https://rickylabs.github.io/netscript/tutorials/workspace/03-workspace-data/): Your app can sign users in, but it has nothing of its own to store yet. This chapter gives the workspace its own data: a second, isolated database with its own Prisma schema, migration history, and… - [Provision with a background job](https://rickylabs.github.io/netscript/tutorials/workspace/04-provision-job/): Think about when a team actually adds a member. Often it is the worst possible moment: something is broken, and the one person who understands the failing subsystem is not in the workspace yet. The… - [Protect routes with authz](https://rickylabs.github.io/netscript/tutorials/workspace/05-route-authz/): Your workspace service still answers anyone — and after chapters 3 and 4 it fronts data with real consequences: the member list of a specific team. The route that returns it has to do two things at… - [Deploy locally](https://rickylabs.github.io/netscript/tutorials/workspace/06-deploy/): You have built every layer of the team workspace: scaffold, an identity layer, isolated team data, a provisioning job that never blocks the caller, and routes that fail closed. This final chapter… ## How-to guides - [All recipes](https://rickylabs.github.io/netscript/how-to/): Recipes live inside their pillar in the sidebar — each area's Recipes section sits below the guides that teach the basics it assumes. This page is the cross-area index: every recipe in the docs… ## Capabilities & hubs - [Background Processing](https://rickylabs.github.io/netscript/background-processing/): Work that outlives the request, from one handler file. In NetScript, moving work off the request path means authoring a single typed handler — the queue, retry policy, scheduler, execution history… - [Recipes](https://rickylabs.github.io/netscript/background-processing/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Add a task runtime adapter](https://rickylabs.github.io/netscript/background-processing/how-to/add-a-task-runtime-adapter/): createDefaultTaskExecutor({ adapters, customAdapters }) lets you keep the built-in task executor while adding a controlled runtime adapter. Use this when a task must run through a host runtime that… - [Restrict worker task permissions](https://rickylabs.github.io/netscript/background-processing/how-to/restrict-worker-task-permissions/): Deno tasks are the worker runtime path that can receive Deno permission flags. Use .permissions() or permissions presets for every Deno task you ship; an omitted permission object compiles to… - [Run a polyglot task](https://rickylabs.github.io/netscript/background-processing/how-to/run-a-polyglot-task/): Define a non-TypeScript script — a Python program, a shell script, a .NET tool, or any executable — as a NetScript task, give it a permission sandbox, and run it through the multi-runtime executor… - [Tune the worker runtime](https://rickylabs.github.io/netscript/background-processing/how-to/tune-worker-runtime/): Trade throughput against isolation by tuning four real knobs — worker concurrency, the runner mode, per-task Deno permissions, and timeouts/retries — without touching a single job handler. - [Polyglot tasks](https://rickylabs.github.io/netscript/background-processing/polyglot-tasks/): Keep the script, gain the runtime. A working Python, .NET, or shell step becomes a queued, retried, traced unit of work by declaring it with defineTask — the script itself does not change, and… - [Background jobs](https://rickylabs.github.io/netscript/background-processing/workers/): One typed handler file is the whole job. Registration, dispatch, retry, execution tracking, scheduling, tracing, and the HTTP trigger API all come from the worker runtime — so shipping a working… - [Data and Persistence](https://rickylabs.github.io/netscript/data-persistence/): Edit one schema file, run one generate, and every consumer follows — the typed Prisma client, the matching zod validation schemas, and the migration all come out of the same netscript db workflow… - [Database & Prisma](https://rickylabs.github.io/netscript/data-persistence/database/): A schema change is never just a schema change. Add one field to a model and three other things are now stale: the client types your services compile against, the runtime validation that guards your… - [Recipes](https://rickylabs.github.io/netscript/data-persistence/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Choose a queue provider](https://rickylabs.github.io/netscript/data-persistence/how-to/choose-a-queue-provider/): Scope: how to pick the right backend for @netscript/queue — the in-memory test adapter, the zero-config Deno KV default, Redis, RabbitMQ (AMQP), and PostgreSQL — and how to either let auto-discovery… - [Database & migration](https://rickylabs.github.io/netscript/data-persistence/how-to/database-migration/): Goal: take a freshly scaffolded NetScript workspace and stand up its database — bring up the AppHost, create the first migration, generate the typed Prisma client, seed it, and confirm the schema is… - [Queue / KV / cron](https://rickylabs.github.io/netscript/data-persistence/how-to/queue-kv-cron/): Scope: three task recipes for the runtime primitives every NetScript app reaches for sooner or later — enqueueing and consuming a queue message, reading and writing KV, and scheduling a cron job… - [Use a second database](https://rickylabs.github.io/netscript/data-persistence/how-to/use-a-second-database/): Goal: add a second database — a second Postgres, or a MySQL/SQL Server instance — to a NetScript workspace that already has its primary datasource, so each datasource gets its own Prisma schema… - [KV, queues & cron](https://rickylabs.github.io/netscript/data-persistence/kv-queues-cron/): The integration trio. Most backends end up hand-assembling three boring-but-load-bearing seams: a key-value store for cache and session state, a message queue for fire-and-forget work, and a cron… - [Durable Workflows](https://rickylabs.github.io/netscript/durable-workflows/): This pillar is about state that must outlive a request — and a process. A saga carries multi-step state across crashes, a trigger turns inbound events into durable work, and a stream fans completed… - [Recipes](https://rickylabs.github.io/netscript/durable-workflows/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Build a validated ingestion queue](https://rickylabs.github.io/netscript/durable-workflows/how-to/build-a-validated-ingestion-queue/): Use createTypedQueue(name, schema, options) when inbound messages must be checked before they enter the queue and again before a consumer handles them. - [Publish a durable stream](https://rickylabs.github.io/netscript/durable-workflows/how-to/publish-a-durable-stream/): Use createDurableStream(options) when a server-side runtime owns entity state that browser clients or other consumers should subscribe to through a durable stream service. - [Durable sagas](https://rickylabs.github.io/netscript/durable-workflows/sagas/): A saga is the answer to the question every retry loop dodges: what happens between step three and step four when the process dies? In NetScript a saga is an explicit, message-driven state machine —… - [Durable streams](https://rickylabs.github.io/netscript/durable-workflows/streams/): A NetScript stream is a typed, durable change-log: producers write entity state into a durable-stream server, and any number of HTTP/SSE consumers materialize the latest value per key. alpha - [Triggers & ingress](https://rickylabs.github.io/netscript/durable-workflows/triggers/): The triggers plugin is NetScript's front door for the outside world. It turns external events — inbound webhooks, files dropped on disk, and cron schedules — into durable background work. A trigger… - [Identity and Access](https://rickylabs.github.io/netscript/identity-access/): One env var and five endpoints separate a scaffolded workspace from a working OAuth sign-in — and the boundaries fail loud with typed errors instead of degrading to a silent anonymous session. - [Authentication](https://rickylabs.github.io/netscript/identity-access/auth/): One env var and five endpoints separate a scaffolded workspace from a working OAuth sign-in — and the boundaries fail loud with typed errors instead of degrading to a silent anonymous session. Auth… - [better-auth plugins](https://rickylabs.github.io/netscript/identity-access/better-auth-plugins/): better-auth ships its feature set as plugins — organizations, two-factor, API keys, bearer and JWT tokens, magic links, passkeys, and more. NetScript's better-auth backend mounts them through a… - [Recipes](https://rickylabs.github.io/netscript/identity-access/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Add authentication](https://rickylabs.github.io/netscript/identity-access/how-to/add-authentication/): Scope. This recipe adds sign-in, sessions, and a /me identity endpoint to an existing NetScript workspace by installing the official auth plugin. You will choose an authentication backend, run the… - [Observability](https://rickylabs.github.io/netscript/observability/): The most expensive turn in any change loop — whether the author is you or an AI agent — is the verification turn: did the change actually work, across every process it touched? This pillar is how… - [Recipes](https://rickylabs.github.io/netscript/observability/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Add OpenTelemetry](https://rickylabs.github.io/netscript/observability/how-to/add-opentelemetry/): Scope: turn on, extend, and read distributed traces in an existing NetScript workspace. OpenTelemetry is not a bolt-on here — @netscript/telemetry wraps @opentelemetry/api and is wired into the… - [Telemetry & logging](https://rickylabs.github.io/netscript/observability/telemetry/): The most expensive turn in any change loop — whether the author is you or an AI agent — is the verification turn: did the change actually work, across every process it touched? NetScript closes that… - [Orchestration and Runtime](https://rickylabs.github.io/netscript/orchestration-runtime/): A NetScript app is never one process — it is services, plugin APIs, background processors, a database, and a cache, wired together. This pillar is about the machinery that makes that fleet derived… - [CLI and Scaffold](https://rickylabs.github.io/netscript/orchestration-runtime/cli-scaffold/): One command — netscript init — lays down a complete, running backend workspace: shared oRPC contracts, an example service, a Fresh frontend, the plugin registry, a default cache, and the Aspire… - [Recipes](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Add a plugin](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/add-a-plugin/): Goal: add one of NetScript's official plugins — workers, sagas, triggers, streams, or auth — to an existing workspace, register it with the runtime, and confirm it is wired up and healthy. - [Author a plugin](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/author-a-plugin/): Scope. This recipe shows how to author a new custom plugin from scratch — its canonical location, the manifest it exports through definePlugin(...), the contribution shape the kernel reads, and the… - [Deno LSP code intelligence in Claude Code](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deno-lsp-code-intelligence/): Goal: give every Claude Code session the same Deno language-server features for NetScript apps: go-to-definition, find-references, hover, document symbols, and live diagnostics across the CLI, VS… - [Deploy to Deno Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy-deno-deploy/): Goal: push a NetScript workspace to Deno Deploy with a single first-class command — netscript deploy deno-deploy — preflighting it for the hosted platform, pushing a preview, promoting to… - [Deploy locally with Aspire](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy-local-aspire/): Goal: run your whole NetScript workspace on one machine under .NET Aspire — scaffold the AppHost, bring up the resource graph (Postgres, Redis, every service and background processor), and watch it… - [Deploy](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/deploy/): Goal: take the workspace you scaffolded with netscript init and run it somewhere other than your laptop — a container host, a VM, or a managed platform — with clear expectations about what the… - [Graceful shutdown](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/graceful-shutdown/): Drain in-flight requests and jobs, run teardown hooks, and close DB/queue connections when your app receives SIGINT/SIGTERM — so a deploy or Ctrl+C never drops work mid-flight. - [Roll out runtime overrides](https://rickylabs.github.io/netscript/orchestration-runtime/how-to/roll-out-runtime-overrides/): Use runtime overrides when operations need to change a deployed behavior without rebuilding the workspace. watchRuntimeConfig(onChange, options) watches the runtime config directory, reloads after… - [Runtime configuration](https://rickylabs.github.io/netscript/orchestration-runtime/runtime-config/): NetScript splits configuration into two layers: a typed project config you author once in netscript.config.ts and load at startup (@netscript/config), and a hot-reloadable runtime override layer that… - [Services and SDK](https://rickylabs.github.io/netscript/services-sdk/): Declare the API once — as a versioned contract — and the server handler, the typed client, the OpenAPI spec, and the query layer all derive from that one object. That is this pillar in a sentence. A… - [Recipes](https://rickylabs.github.io/netscript/services-sdk/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Add a service](https://rickylabs.github.io/netscript/services-sdk/how-to/add-a-service/): Goal: add a new typed oRPC service to an existing NetScript workspace — define its contract, implement the handlers, serve it with defineService, and confirm it answers on its own port over both its… - [Discover services](https://rickylabs.github.io/netscript/services-sdk/how-to/discover-services/): Goal: call another plugin's (or another workspace member's) oRPC service from your app, end to end — declare the dependency so Aspire injects the callee's URL, then obtain a fully typed client from… - [Expose OpenAPI & Scalar](https://rickylabs.github.io/netscript/services-sdk/how-to/expose-openapi-scalar/): Turn on the generated OpenAPI document and the interactive Scalar API reference UI for an existing oRPC service — as a one-line defineService option or by mounting the Layer-1 primitives onto any… - [Typed SDK & client](https://rickylabs.github.io/netscript/services-sdk/sdk/): Declare a contract action once and everything the caller needs — the typed method, the query key, the cache entry, the TanStack options — is derived from it, in one import. - [Services & contracts](https://rickylabs.github.io/netscript/services-sdk/services/): Write the contract once; the handler, the typed client, and the OpenAPI surface are all derived from it — so an agent (or a teammate) never spends a turn keeping them in sync. - [Web Layer](https://rickylabs.github.io/netscript/web-layer/): The web layer is where API drift surfaces last and costs the most turns to fix. NetScript's answer is @netscript/fresh: a server-first meta-framework, built on Fresh 2.x and Preact, that renders… - [Pages and the define-page builder](https://rickylabs.github.io/netscript/web-layer/builders/): @netscript/fresh exposes a fluent builder for declaring pages. You start a chain with definePage(), layer on resources, params, render layers, handlers, and metadata, and finish with build() to… - [Deferred and streaming UI](https://rickylabs.github.io/netscript/web-layer/defer-streaming-ui/): A page often has one region that is slower than the rest — a dashboard panel that aggregates data, a detail view that reads from cache, or a feed that updates as events arrive. @netscript/fresh gives… - [Error handling and diagnostics](https://rickylabs.github.io/netscript/web-layer/error/): @netscript/fresh ships an explicit error-handling surface for the Web Layer. Instead of letting a thrown loader propagate into a blank screen, it normalizes any failure into a single ErrorData… - [Examples and sandbox](https://rickylabs.github.io/netscript/web-layer/examples/): A curated index of runnable Web Layer examples built on @netscript/fresh. Start here when you want to see the meta-framework end to end rather than one capability at a time. Each entry below points… - [Server-validated forms](https://rickylabs.github.io/netscript/web-layer/form/): The @netscript/fresh form surface lets a Fresh page own a form end to end: parse the posted payload on the server, validate it against a schema, surface field-level and form-level errors, and render… - [Fresh UI & design](https://rickylabs.github.io/netscript/web-layer/fresh-ui/): A design system earns its keep when the person — or agent — changing the UI can open every file involved. NetScript's Fresh UI layer is copy-source: components are installed into your repo as… - [Recipes](https://rickylabs.github.io/netscript/web-layer/how-to/): Task-oriented recipes for this area. Each one solves a single concrete problem and assumes you know the basics from the guides above it in the sidebar. The full cross-area catalog lives at All how-to… - [Building a desktop frontend the NetScript way](https://rickylabs.github.io/netscript/web-layer/how-to/build-a-desktop-frontend/): Goal: compose one Fresh frontend that runs as an ordinary browser/Aspire app and gains native window chrome, tray menus, dialogs, notifications, typed RPC, and update-ready UX when hosted by Deno… - [Build a server-validated form](https://rickylabs.github.io/netscript/web-layer/how-to/build-a-server-validated-form/): Use definePage().withForm() when a Fresh page needs route-bound form state, server validation, mutation, and redirect or same-page success handling in one typed page definition. - [Customize Fresh UI](https://rickylabs.github.io/netscript/web-layer/how-to/customize-fresh-ui/): Goal: make the scaffolded frontend yours — edit a route, add an interactive island, restyle a component, install more UI primitives, and re-theme the app — without fighting the framework. NetScript… - [Interactive islands](https://rickylabs.github.io/netscript/web-layer/interactive/): The interactive entrypoint of @netscript/fresh is intentionally small. It exposes the browser-facing seams that the framework owns directly, while route builders, server helpers, and copy-based UI… - [Data loading and the query cache](https://rickylabs.github.io/netscript/web-layer/query/): The @netscript/fresh/query subpath gives islands a package-owned data layer built on TanStack Query, while the package root exposes a small set of cache-entry helpers that page loaders and islands… - [Routing and route contracts](https://rickylabs.github.io/netscript/web-layer/route/): The route surface of @netscript/fresh turns a Fresh route pattern such as "/orders/[id]" into a typed contract. A route contract owns the schemas for its path and search params, parses raw request… - [The Fresh page model](https://rickylabs.github.io/netscript/web-layer/server/): @netscript/fresh is NetScript's web layer: a server-first meta-framework built on Fresh that renders pages on the server, sends HTML, and hydrates only the interactive parts of a page as islands… - [Testing Fresh pages](https://rickylabs.github.io/netscript/web-layer/testing/): The @netscript/fresh testing export provides fixtures for exercising routes, loaders, and layouts without standing up an HTTP server. Reach for it when you want to unit-test a page's loader logic… - [Build and Vite integration](https://rickylabs.github.io/netscript/web-layer/vite/): @netscript/fresh ships a Vite plugin that wires a Fresh workspace into the build: it resolves NetScript app aliases, maps environment variables into import.meta.env, and generates route manifests at… ## Reference - [Reference](https://rickylabs.github.io/netscript/reference/): Reference is information-oriented: precise, exhaustive API documentation for every public NetScript package and plugin. These pages are generated from the source code with deno doc, so they always… - [@netscript/ai](https://rickylabs.github.io/netscript/reference/ai/): The provider-agnostic AI engine core for NetScript: a composition root, a global model registry, the domain vocabulary and capability ports for chat/embeddings/vision/tools/agents/MCP, and a set of… - [@netscript/ai/skills](https://rickylabs.github.io/netscript/reference/ai/skills/): Load validated Agent Skills with progressive disclosure and optional semantic matching. A skill is a SKILL.md document — a small frontmatter block plus Markdown instructions — that an agent can… - [@netscript/aspire](https://rickylabs.github.io/netscript/reference/aspire/): SDK-neutral Aspire diagnostics, config parsing, contribution ports, and TypeScript AppHost generation for NetScript plugin packages. This page is generated from the package's public surface with deno… - [@netscript/auth-better-auth](https://rickylabs.github.io/netscript/reference/auth-better-auth/): Better Auth integration, authenticator, and backend adapter for NetScript auth. This page is generated from the package's public surface with deno doc. - [@netscript/auth-kv-oauth](https://rickylabs.github.io/netscript/reference/auth-kv-oauth/): KV-backed OAuth2/OIDC relying-party backend for NetScript auth. This page is generated from the package's public surface with deno doc. - [@netscript/auth-workos](https://rickylabs.github.io/netscript/reference/auth-workos/): WorkOS-backed authenticator and backend adapter for NetScript auth. This page is generated from the package's public surface with deno doc. - [Auth reference](https://rickylabs.github.io/netscript/reference/auth/): NetScript auth is split across one plugin manifest package, one core contract package, and three backend adapters. This hub is generated from the public surfaces verified with deno doc. - [@netscript/cli](https://rickylabs.github.io/netscript/reference/cli/): Public and maintainer command-line tooling for NetScript workspaces. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and plugins return… - [netscript command reference](https://rickylabs.github.io/netscript/reference/cli/commands/): The complete verb-and-flag surface of the published netscript binary (@netscript/cli). The CLI reference is the curated tour of the everyday path; this page is the exhaustive companion — every… - [@netscript/config](https://rickylabs.github.io/netscript/reference/config/): Typed NetScript project configuration: schemas, loaders, environment helpers, workspace discovery, diagnostics, and scaffold constants. This page is generated from the package public surface with… - [@netscript/contracts](https://rickylabs.github.io/netscript/reference/contracts/): Contract vocabulary shared across NetScript package and plugin boundaries: the oRPC base contract, common error data, pagination schemas, result types, and schema helper factories. Because a… - [@netscript/cron](https://rickylabs.github.io/netscript/reference/cron/): Runtime-agnostic cron scheduling abstraction for NetScript applications. Provides a consistent interface across different backends (native Deno.cron and an in-memory scheduler) with timezone support… - [@netscript/database](https://rickylabs.github.io/netscript/reference/database/): Database adapter contracts, Prisma driver helpers, tracing, and schema tooling for NetScript packages. This page is generated from the package's public surface with deno doc (US-2). For the full… - [@netscript/fresh-ui](https://rickylabs.github.io/netscript/reference/fresh-ui/): Fresh UI registry seams and interactive foundations for NetScript. This page is generated from the package public surface with deno doc (US-2). For the full index of packages and plugins return to… - [@netscript/fresh](https://rickylabs.github.io/netscript/reference/fresh/): Fresh runtime extensions, builders, forms, defer primitives, and route contracts for NetScript. This page is generated from the public surface of the package with deno doc (US-2). For the full index… - [@netscript/kv](https://rickylabs.github.io/netscript/reference/kv/): Reactive key-value storage with a unified API across Deno KV, Redis, and in-memory backends. This page is generated from the package's public surface with deno doc (US-2). For the full index of… - [@netscript/logger](https://rickylabs.github.io/netscript/reference/logger/): Structured logging for NetScript packages, services, workers, and jobs. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and plugins… - [@netscript/mcp](https://rickylabs.github.io/netscript/reference/mcp/): The Model Context Protocol server for NetScript workspaces. This page describes the package's public surface and is maintained by hand; the authoritative, always-current symbol list is deno doc… - [@netscript/plugin-ai-core](https://rickylabs.github.io/netscript/reference/plugin-ai-core/): The contract-only core for the NetScript AI plugin: the oRPC /v1/ai route surface — an SSE-framed chat stream plus models, tools/{name}, embed, and transcribe — that a connector implements and the… - [@netscript/plugin-auth-core](https://rickylabs.github.io/netscript/reference/plugin-auth-core/): Auth plugin contracts, backend ports, stream schemas, config schemas, telemetry primitives, and testing primitives for NetScript auth plugins. This page is generated from the package's public surface… - [@netscript/plugin-auth](https://rickylabs.github.io/netscript/reference/plugin-auth/): Public plugin manifest for NetScript auth. This page is generated from the package's public surface with deno doc. For the auth package map, return to the auth reference hub. - [@netscript/plugin](https://rickylabs.github.io/netscript/reference/plugin/): Plugin manifest, validation, discovery, and host-context contracts for NetScript. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and… - [@netscript/prisma-adapter-mysql](https://rickylabs.github.io/netscript/reference/prisma-adapter-mysql/): Prisma driver adapter for MySQL and MariaDB on Deno. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and plugins return to the reference… - [@netscript/queue](https://rickylabs.github.io/netscript/reference/queue/): Provider-agnostic message queue abstraction for NetScript applications. It wraps Fedify battle-tested queue adapters behind a single, unified MessageQueue interface with optional Zod validation and… - [@netscript/runtime-config](https://rickylabs.github.io/netscript/reference/runtime-config/): Hot-reloadable NetScript runtime override types, loaders, watchers, and diagnostics. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and… - [@netscript/plugin-sagas](https://rickylabs.github.io/netscript/reference/sagas/): NetScript plugin for durable saga orchestration, workflow APIs, and saga runtime metadata. This page is generated from the package's public surface with deno doc (US-2). For the full index of… - [@netscript/sdk](https://rickylabs.github.io/netscript/reference/sdk/): Service discovery, oRPC clients, and cache-backed query factories for NetScript. This page is generated from the package's public surface with deno doc (US-2). For the full index of packages and… - [@netscript/service](https://rickylabs.github.io/netscript/reference/service/): Service bootstrap builders, health probes, and Hono/oRPC runtime wiring for NetScript applications. This page is generated from the package's public surface with deno doc (US-2). For the full index… - [@netscript/plugin-streams](https://rickylabs.github.io/netscript/reference/streams/): Durable Streams development plugin for NetScript: a plugin manifest plus CLI, scaffolding, end-to-end gate, and Aspire integration surfaces for a durable, change-data stream service. This page is… - [@netscript/telemetry](https://rickylabs.github.io/netscript/reference/telemetry/): OpenTelemetry tracing primitives, context propagation, instrumentation registries, and NetScript runtime adapters for jobs, queues, RPC, and SSE. This page is generated from the package's public… - [@netscript/plugin-triggers](https://rickylabs.github.io/netscript/reference/triggers/): NetScript plugin for trigger ingress, scheduling, file watching, and the trigger runtime APIs. This page is generated from the package's public surface with deno doc (US-2). For the full index of… - [@netscript/watchers](https://rickylabs.github.io/netscript/reference/watchers/): Reusable file-watching primitives for NetScript: composable strategies, filters, and a pipeline-based FileWatcher for detecting file-system changes across local and network filesystems. This page is… - [@netscript/plugin-workers](https://rickylabs.github.io/netscript/reference/workers/): The NetScript background-workers plugin: background jobs, task execution, workflow orchestration, a Workers API service, CLI commands, scaffolding, durable streams, and Aspire process wiring. This… ## Explanation - [Explanation](https://rickylabs.github.io/netscript/explanation/): Explanation pages are the why lane. They build the mental model: how NetScript is put together, why each boundary is shaped the way it is, and which trade-offs that shape buys you. Read them when you… - [Architecture](https://rickylabs.github.io/netscript/explanation/architecture/): NetScript is a set of Deno-native framework packages, published on JSR and composed into a running backend by first-party plugins, orchestrated locally by Aspire. This essay answers one question… - [Orchestration with Aspire](https://rickylabs.github.io/netscript/explanation/aspire/): A NetScript app is never one process. This essay explains why it needs an orchestrator at all, how the orchestrator's resource graph is generated from your plugins rather than hand-wired, and what a… - [The pure-backend auth model](https://rickylabs.github.io/netscript/explanation/auth-model/): This essay is the why — the model and its trade-offs. The day-to-day how (guides, recipes, API) lives in Build › Identity & Access. - [Contracts & type flow](https://rickylabs.github.io/netscript/explanation/contracts/): This page explains why NetScript is contracts-first and how a single type definition travels from a contract, through a service handler, all the way to a typed client and a UI island — with no second… - [Durability model](https://rickylabs.github.io/netscript/explanation/durability-model/): This essay is the why — the model and its trade-offs. The day-to-day how (guides, recipes, API) lives in Build › Durable workflows. - [Observability](https://rickylabs.github.io/netscript/explanation/observability/): This essay is the why — the model and its trade-offs. The day-to-day how (guides, recipes, API) lives in Build › Observability. - [The plugin system](https://rickylabs.github.io/netscript/explanation/plugin-system/): This essay explains the mental model behind a NetScript plugin: how a plugin relates to its sibling core package, what it contributes to a host through a typed manifest, how the host discovers it…