---
title: "Getting Started"
description: "Pick a template, create your app, and start customizing it with AI."
---

# Getting Started

By the end of this page, you'll have a working app — Mail, Calendar, Forms, or any other template — running with an AI agent built into the sidebar that can drive every part of it.

## Who is this for? {#who-is-this-for}

There are two ways to use agent-native, depending on how hands-on you want to be:

- **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js 24 LTS](https://nodejs.org) and [pnpm](https://pnpm.io) installed.

Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.

## First run {#create-your-app}

Three commands and you're up:

```bash
npx @agent-native/core create my-platform
cd my-platform
pnpm install && pnpm dev
```

The `create` command defaults to a workspace monorepo. It shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config. If you want one app directory instead, pass `--standalone`.

Open the URL the dev server prints. Workspace apps use app-specific ports, often `http://localhost:8080` or another 808x port; standalone apps usually use `http://localhost:3000`.

### Testing local framework changes {#testing-local-framework-changes}

Framework contributors can scaffold against the current checkout instead of the
published packages:

```bash
AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
```

With that flag, generated workspaces link both the local `@agent-native/core`
and local `@agent-native/dispatch` packages. Use it when you need to verify
unpublished template or package changes end-to-end in a freshly generated
workspace. The packages run their `prepack` build first, so the linked packages
serve fresh `dist` output instead of stale build artifacts.

To exercise the repo-local CLI itself without building first, run it through
the root script:

```bash
pnpm dev:cli --help
pnpm dev:cli code goals
```

## Creating vs adding apps {#creating-vs-adding-apps}

Run `create` from the folder where you want a brand-new workspace:

```bash
cd ~/projects
npx @agent-native/core create my-platform
```

After a workspace exists, run app commands from the workspace root:

```bash
cd my-platform
npx @agent-native/core add-app
pnpm install
pnpm dev
```

If your terminal is inside `apps/content` or another app folder, the CLI still detects the workspace and adds the new app as a sibling under `apps/`. Afterward, go back to the workspace root before running `pnpm install` or `pnpm dev`.

To make a second app from the same template, give it a new app name:

```bash
npx @agent-native/core add-app design-lab --template design
```

## What just happened? {#what-just-happened}

You now have a real, full-featured app running on your machine. Open it in the browser and try it:

- Click around the UI like you would any SaaS product.
- Open the agent panel on the right side. Type something like "show me my settings" or "create a new entry called Welcome." Watch the agent click through the app on your behalf.
- Anything you do by clicking, the agent can do by reading and writing the same database. Anything the agent does shows up in the UI immediately.

That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.

## Try one concrete next step {#first-next-step}

From here, use any AI coding tool (Agent-Native Code, Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.

Good first moves:

- **Open Agent-Native Code** — run `npx @agent-native/core@latest` or `npx @agent-native/core@latest code` from the project. A bare command opens the local Claude Code/Codex-like workspace; a bare prompt such as `npx @agent-native/core@latest "rename the app"` starts a Code task directly.
- **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies the app, UI state, and agent loop are all talking to each other.
- **Make a tiny customization** — ask your coding tool to rename the app, change the first screen copy, or add one field to a form. It will read `AGENTS.md` for the framework conventions.
- **Add another app to the same workspace** — use `npx @agent-native/core add-app` from inside the workspace folder. The command starts at `npx`.
- **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core create my-app --standalone --template mail`.

Agent-Native Code understands built-in slash goals such as `/migrate` and `/audit`, plus project commands in `.agents/commands/*.md`. Use `agent-native code list`, `status`, `resume`, `stop`, or `ui` to inspect and control the same run from the CLI, the local UI, or the Desktop Code tab.

## Next docs to read {#next-docs}

Once your app is running, the most useful follow-ups are:

- **Connect Slack or email** so you can message your agent from anywhere — see [Messaging](/docs/messaging).
- **Set up Dispatch as your central inbox** to triage messages and orchestrate across multiple apps — see [Dispatch](/docs/dispatch).
- **Customize via Workspace** — edit instructions, skills, memory, and connect MCP servers per user — see [Workspace](/docs/workspace).
- **Troubleshoot common setup questions** — see the [FAQ](/docs/faq).
- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.

## Templates {#templates}

Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:

| Template                            | Replaces                                        |
| ----------------------------------- | ----------------------------------------------- |
| [Calendar](/templates/calendar)     | Google Calendar, Calendly                       |
| [Content](/templates/content)       | Notion, Google Docs                             |
| [Brain](/templates/brain)           | Company chat with cited institutional memory    |
| [Slides](/templates/slides)         | Google Slides, Pitch                            |
| [Analytics](/templates/analytics)   | Amplitude, Mixpanel, Looker                     |
| [Mail](/templates/mail)             | Superhuman, Gmail                               |
| [Clips](/templates/clips)           | Replaces Loom — screen + camera recording       |
| [Design](/templates/design)         | HTML prototyping studios                        |
| [Forms](/docs/template-forms)       | Typeform                                        |
| [Dispatch](/docs/template-dispatch) | Workspace control plane — integrations, routing |
| [Starter](/docs/template-starter)   | Minimal scaffold — build from scratch           |

Browse the [template gallery](/templates) for live demos, or see [Templates](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.

## Project structure {#project-structure}

Every agent-native app — whether from a template or from scratch — follows the same structure:

```text
my-app/
  app/             # React frontend (routes, components, hooks)
  server/          # Nitro API server (routes, plugins)
  actions/         # Agent-callable actions
  .agents/         # Agent instructions and skills
```

Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.

## Architecture principles {#architecture-principles}

These principles apply to all agent-native apps. Skim them now, revisit them when you're customizing.

1. **Agent + UI are equal partners** — Everything the UI can do, the agent can do, and vice versa. They share the same database and always stay in sync. You don't think about "the agent" and "the app" separately — you think about them together.
2. **Context-aware** — The agent always knows what you're looking at. If an email is open, it knows which one. If you select text and hit Cmd+I, it can act on just that selection.
3. **Skills-driven** — Core functionality has written instructions so the agent doesn't explore from scratch every time. New features update all four areas: UI, actions, skills/instructions, and application state.
4. **Inter-agent communication** — Agents can discover and call each other via the A2A protocol. Tag your analytics agent from the mail app to pull data into a draft.
5. **Fully portable** — Any SQL database Drizzle supports, any hosting backend Nitro supports, any AI coding tool. These are non-negotiable.
6. **Fork and customize** — Apps you clone and evolve. The agent can modify the app's own code — components, routes, styles, actions — so it gets better over time.
