# Getting Started

> Install Struere and create your first agent


Struere projects use a TypeScript SDK with 7 definition primitives (defineAgent, defineData, defineRole, defineTrigger, defineRouter, defineTools, defineView) and a CLI that watches local files and syncs changes to the Convex backend in real time.

You can build:

- **Agents** — LLM-driven assistants with tools, permissions, and dynamic system prompts
- **Data types** — structured entities with JSON schemas and full-text search
- **Roles** — row-level and column-level access control
- **Automations** — event- and cron-driven workflows
- **Routers** — direct conversations to the right agent
- **Custom tools** — your own handlers, executed in a sandbox
- **Custom views** — live, sandboxed dashboards authored as TSX (see [Custom Views](./platform/views))

## Prerequisites

Before you begin, make sure you have:

- **Node.js 18+** installed
- **Bun** installed (`curl -fsSL https://bun.sh/install | bash`) — used as the package manager
- A **Struere account** — sign up at [app.struere.dev](https://app.struere.dev)
- An **LLM provider** — either use Struere's built-in credits or bring your own API key (configured in **Settings > Providers** in the dashboard)

## Quick Start

Run this in your terminal to install the CLI, sign in, scaffold a project, create a starter agent, and set up the developer skill:

```bash
curl -fsSL https://docs.struere.dev/install.sh | bash
```

This single command installs the Struere CLI, signs you in, scaffolds your project, creates a hello world agent, and installs the Struere developer skill into `.claude/skills/`. Open the new project folder in Claude Code, Cursor, or any coding agent — the skill teaches it how to use Struere's SDK, avoid common mistakes, and fetch the right documentation.

If you prefer to set things up manually, continue with the steps below.

## Installation

Install the Struere package as a project dependency:

```bash
bun add struere
```

## Initialize a Project

Run the init command to scaffold an organization-centric project:

```bash
bunx struere init
```

This command will:

1. Open a browser for authentication (sign in with your Struere account)
2. Prompt you to select an organization
3. Create the project directory structure
4. Write a `struere.json` configuration file with your organization details
5. Generate `.struere/` virtual module files (`index.js`, `index.d.ts`, `types.d.ts`)

### Project Structure

After initialization, your project will have this structure:

```
my-org/
├── struere.json
├── agents/
│   └── (your agent definitions)
├── entity-types/
│   └── (your data type schemas)
├── roles/
│   └── (your role definitions with policies)
├── routers/
│   └── (your router definitions)
├── triggers/
│   └── (your automations)
├── tools/
│   └── index.ts
├── evals/
│   └── (your eval suites as YAML)
└── fixtures/
    └── (your test data for evals as YAML)
```

### struere.json

The configuration file identifies your organization:

```json
{
  "version": "2.0",
  "organization": {
    "id": "org_abc123",
    "slug": "acme-corp",
    "name": "Acme Corp"
  }
}
```

## Create Your First Agent

Create a file at `agents/my-agent.ts`:

```typescript
import { defineAgent } from 'struere'

export default defineAgent({
  name: "My First Agent",
  slug: "my-first-agent",
  version: "0.1.0",
  systemPrompt: "You are a helpful assistant for {{organizationName}}. Current time: {{currentTime}}.",
  model: {
    model: "openai/gpt-5-mini",
  },
  tools: ["entity.query"],
})
```

This defines an agent that:
- Uses openai/gpt-5-mini as its LLM
- Has access to query entities
- Receives the organization name and current time in its system prompt via template variables

## Define a Data Type

Create a file at `entity-types/customer.ts`:

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Customer",
  slug: "customer",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      email: { type: "string", format: "email" },
      plan: { type: "string", enum: ["free", "pro", "enterprise"] },
    },
    required: ["name", "email"],
  },
  searchFields: ["name", "email"],
})
```

## Define a Role

Create a file at `roles/support.ts`:

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "support",
  description: "Support agents with read access to customers",
  policies: [
    { resource: "customer", actions: ["list", "read"], effect: "allow" },
    { resource: "customer", actions: ["delete"], effect: "deny" },
  ],
})
```

## Start Development

Run the dev command to sync your definitions to the platform:

```bash
bunx struere dev
```

You should see output like:

```
✓ Logged in as you@example.com
✓ Loaded 1 agent, 1 data type, 1 role
✓ Synced to development environment
  Watching for changes...
```

The resource summary shows all non-zero resource counts, including routers, triggers, custom tools, and fixtures when present.

The `dev` command will:

1. Auto-login if you are not authenticated (opens a browser)
2. Load all resource definitions from `agents/`, `entity-types/`, `roles/`, `triggers/`, `tools/`, `evals/`, and `fixtures/`
3. Sync to the **development** environment (agents, types, roles, triggers) and the **eval** environment (agents, types, roles, eval suites, fixtures)
4. Watch for file changes and re-sync automatically

Every time you save a file, the CLI re-syncs your changes.

## Test Your Agent

Once synced, you can interact with your agent in two ways:

### Via the API

Create an API key from the CLI:

```bash
bunx struere keys create --name "my-app" --env development
```

The plaintext key is shown only once — copy it into your secret store immediately. You can also create keys in the dashboard under **Settings > API Keys** by selecting the **development** environment.

Then send a request using the slug-based endpoint:

```bash
curl -X POST https://api.struere.dev/v1/agents/my-first-agent/chat \
  -H "Authorization: Bearer sk_dev_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'
```

You should receive a JSON response:

```json
{
  "threadId": "jd7abc123...",
  "message": "Hello! I'm your assistant for Acme Corp. I can query your data and log events. How can I help?",
  "usage": {
    "inputTokens": 245,
    "outputTokens": 32,
    "totalTokens": 277
  }
}
```

Your API URL is shown in the dashboard under **Settings > API Keys**.

### Via the Dashboard

1. Open [app.struere.dev](https://app.struere.dev) and navigate to **Agents**
2. Select your agent ("My First Agent")
3. Use the built-in chat interface to send a message

## Deploy to Production

When you are ready to go live, deploy your agents to the production environment:

```bash
bunx struere deploy
```

This promotes all agent configurations to the production environment where they are accessible via production API keys (prefixed `sk_prod_`).

## Next Steps

- [Chat API](./api/chat) — Full API reference for sending messages to agents
- [CLI Overview](./cli/overview) — Learn all available CLI commands
- [Agent Configuration](./sdk/define-agent) — Configure models, tools, and system prompts
- [Data Types](./sdk/define-data) — Define structured data schemas
- [Built-in Tools](./tools/built-in-tools) — All available agent tools
- [Automations](./sdk/define-trigger) — Build event-driven automations
- [Custom Views](./platform/views) — Live, sandboxed dashboards authored as TSX