# Deployment Scenarios

Deploy your frontend alongside agents or separately on Vercel, Netlify, etc.

Choose the deployment shape that matches your app. The SDK supports both same-origin frontends bundled with your Agentuity app and separate frontends hosted elsewhere.

## All-in-One Deployment

Put your frontend code in `src/web/` and deploy everything together:

```
my-project/
├── src/
│   ├── agent/
│   │   └── chat/
│   │       └── agent.ts
│   ├── api/
│   │   └── index.ts
│   └── web/
│       ├── App.tsx
│       ├── frontend.tsx
│       └── index.html
└── agentuity.json
```

When you run `agentuity deploy`, both your agents and frontend are bundled and deployed together.

```tsx
// src/web/App.tsx
import { hc } from 'hono/client';
import type { ApiRouter } from '../api/index';

const client = hc<ApiRouter>('/api');

function Chat() {
  // Use hc() for type-safe API calls
  const handleSend = async (message: string) => {
    const res = await client.chat.$post({ json: { message } });
    return res.json();
  };
  // ... your chat UI
}

export default function App() {
  return <Chat />;
}
```

> [!NOTE]
> **No baseUrl Needed**
> When frontend and agents are deployed together, `hc<ApiRouter>('/api')` automatically targets the same origin. Add `AgentuityProvider` only if you use `@agentuity/react` hooks (see [Provider Setup](/frontend/provider-setup)).

**Best for:**
- New projects starting from scratch
- Simple deployments with one codebase
- Projects that don't need separate frontend scaling

## Separate Frontend

Deploy your frontend on Vercel, Netlify, or any hosting platform while agents run on Agentuity:

```
Frontend (e.g., Vercel)                Agents (Agentuity)
┌───────────────────────┐           ┌───────────────────────┐
│     your-app.com      │ ────────► │    project.cloud      │
│     React/Next.js     │           │     Agent routes      │
└───────────────────────┘           └───────────────────────┘
```

```tsx
import { hc } from 'hono/client';
import type { ApiRouter } from '@acme/agentuity-contract';

const agentuityBaseUrl = 'https://your-project.agentuity.cloud';
const client = hc<ApiRouter>(`${agentuityBaseUrl}/api`);

function Chat() {
  const send = async (message: string) => {
    const res = await client.chat.$post({ json: { message } });
    return res.json();
  };

  return <button onClick={() => send('Hello from Vercel')}>Send</button>;
}

export default function App() {
  return <Chat />;
}
```

> [!NOTE]
> **Share the Router Type or Use fetch**
> If your frontend lives in a separate repo, put `ApiRouter` in a shared package or call the backend with plain `fetch`. `hc()` only needs the exported router type, not a generated registry.

**Best for:**
- Existing projects adding AI agents
- Teams with separate frontend and backend deployments

## CORS Configuration

When your frontend and agents are on different domains, configure CORS in `app.ts`:

```typescript
// app.ts
import { createApp } from '@agentuity/runtime';

export default await createApp({
  cors: {
    sameOrigin: true,
    allowedOrigins: ['https://your-frontend.com'],
  },
});
```

> [!WARNING]
> **Required for Cross-Origin**
> Without CORS configuration, browsers will block requests from your frontend to your agents when they're on different domains.

## Comparison

| Aspect | All-in-One | Separate Frontend |
|--------|------------|-------------------|
| Deployment | Single `agentuity deploy` | Deploy frontend and agents separately |
| Configuration | Minimal | Requires `baseUrl`, absolute API URLs, and CORS |
| Scaling | Tied together | Independent scaling |
| Type-safe client imports | Local relative import | Shared package or monorepo import |
| Best for | New projects | Existing frontends |

## Next Steps

- [React Hooks](/frontend/react-hooks): Auth, analytics, and WebRTC hooks from `@agentuity/react`
- [Provider Setup](/frontend/provider-setup): `AgentuityProvider` configuration for `@agentuity/react` apps
- [RPC Client](/frontend/rpc-client): Build typed clients for same-origin or remote frontends
- [App Configuration](/get-started/app-configuration): CORS and other app-level settings