> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recursiv.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recursiv.io/_mcp/server.

# Quickstart

This guide gets you from zero to a verified SDK call. It also shows the two paths agents use most often: anonymous sandbox execution and MCP setup.

## Requirements

* Node.js 18 or newer.
* An ESM project (`"type": "module"` in `package.json`) for direct Node scripts.
* A Recursiv API key for authenticated resources.
* No API key for the anonymous sandbox.

## Install the SDK

```bash
npm install @recursiv/sdk
```

## Configure an API key

No account yet? [Sign up at recursiv.io/register](https://recursiv.io/register), then create a key at [recursiv.io/account/api-keys](https://recursiv.io/account/api-keys) (**Settings → API Keys**). You can also sign up and mint a key entirely programmatically — see [Autonomous onboarding](/guides/start-here/auth-api-keys#autonomous-onboarding-for-agents).

```bash
export RECURSIV_API_KEY=sk_live_...
```

The SDK reads `RECURSIV_API_KEY` by default. You can also pass `apiKey` directly:

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv({
  apiKey: process.env.RECURSIV_API_KEY,
});
```

## Create a project and make your first authenticated call

Most resources hang off a project. Create one first — project IDs are UUIDs (e.g. `019d45b3-fc34-76ee-a2dc-1f7131f5447e`), so always use the `id` the API returns. Project-scoped calls return `{ data }`.

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv();

const { data: project } = await r.projects.create({ name: 'my-app' });
console.log(project.id); // UUID — use this everywhere a project_id is needed

const { data: db } = await r.databases.ensure({
  project_id: project.id,
  name: 'main',
});

const { data: result } = await r.databases.query({
  project_id: project.id,
  sql: 'SELECT NOW() as time',
});

console.log(db.id);
console.log(result.rows);
```

## Run code without signing up

The anonymous sandbox is useful for docs examples, demos, and first-run agent checks.

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv({ anonymous: true });

const { data, meta } = await r.sandbox.execute({
  code: 'console.log(1 + 1)',
  language: 'typescript',
});

console.log(data.output); // "2\n"
console.log(`${meta.remaining_executions} executions remaining today`);
```

Limit: 10 anonymous executions per IP per day.

## Stream from an agent

Use `chatStream()` in Node.js and browsers:

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv();

for await (const chunk of r.agents.chatStream('agent_1', {
  message: 'Help me build a landing page',
})) {
  process.stdout.write(chunk.delta ?? '');
}
```

React Native does not expose `ReadableStream` consistently. Use `chatStreamText()` or follow the [React Native guide](/sdk/platform/react-native).

## Start a project sandbox

Use project sandboxes when the code needs project files, dependencies, deploy previews, or persistence.

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv();

await r.projects.createSandbox(project.id);

const { data: result } = await r.projects.executeCode(project.id, {
  code: 'console.log("hello from the project sandbox")',
  language: 'typescript',
});

console.log(result.output);
```

## Deploy

Deploys build from the project's **linked GitHub repository** — a project without a `repo_url` fails with "Project has no linked repository". No repo yet (or no GitHub account)? Scaffold one server-side from a Recursiv starter template:

```typescript
import { Recursiv } from '@recursiv/sdk';

const r = new Recursiv();

// Creates a real repo under the platform's GitHub owner — no GitHub account,
// gh CLI, or local git required. Templates: 'nextjs' | 'expo'.
const { data: repo } = await r.github.createFromTemplate({
  template: 'nextjs',
  name: 'my-app',
});

const { data: project } = await r.projects.create({
  name: 'my-app',
  repo_url: repo.repo_url,
});

const { data: deployment } = await r.projects.deploy(project.id, {
  branch: 'main',
  type: 'production',
});

console.log(deployment.deployment_url);
```

Already have a repo? Pass its URL as `repo_url` on `projects.create` (or link it later with `projects.update`).

## Use the CLI

```bash
npx -p @recursiv/cli recursiv create my-app
cd my-app

npx -p @recursiv/cli recursiv auth login
npx -p @recursiv/cli recursiv projects list
npx -p @recursiv/cli recursiv dev
npx -p @recursiv/cli recursiv deploy vercel
```

`deploy` requires a target: `vercel`, `docker`, `render`, `railway`, or `cloud`.

## Connect an MCP client

Use MCP when an AI assistant should call Recursiv tools directly. Two ways to connect:

**Hosted (recommended)** — no key, no install. In Claude Desktop, Claude.ai, ChatGPT, or the Gemini web app, add a custom connector and paste the URL, then sign in:

```text
https://api.recursiv.io/mcp
```

**Local** — for Claude Code, Cursor, and Codex, run the connector as a subprocess with an API key:

```json
{
  "mcpServers": {
    "recursiv": {
      "command": "npx",
      "args": ["-y", "@recursiv/mcp"],
      "env": { "RECURSIV_API_KEY": "sk_live_xxx" }
    }
  }
}
```

See [MCP](/guides/ai-tools/mcp-claude-cursor) for both paths in full.

## Use REST

```bash
curl -X POST https://api.recursiv.io/api/v1/sandbox/try \
  -H 'Content-Type: application/json' \
  -d '{"code":"console.log(1 + 1)","language":"typescript"}'
```

[API Reference](/api-reference)

## What's next?

* **[Concepts](/guides/start-here/concepts)** - Understand how projects, agents, and organizations fit together
* **[SDK Reference](/sdk/setup/installation-configuration)** - Full SDK documentation with all 40+ resources
* **[Build an AI-Native App](/guides/build/build-an-ai-native-app)** - End-to-end tutorial: database + agent + auth + deploy
* **[Build an Autonomous Agent](/guides/run/build-an-autonomous-agent)** - Give an agent its own Postgres, memory, and code execution
* **[CLI](/guides/ai-tools/cli)** - Scaffold, develop, and deploy from the terminal
* **[MCP](/guides/ai-tools/mcp-claude-cursor)** - Give an AI assistant native access to Recursiv via tool use
* **[API Reference](/api-reference)** - Full REST API documentation