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

$
npm install @recursiv/sdk

Configure an API key

No account yet? Sign up at recursiv.io/register, then create a key at recursiv.io/account/api-keys (Settings → API Keys). You can also sign up and mint a key entirely programmatically — see Autonomous onboarding.

$
export RECURSIV_API_KEY=sk_live_...

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

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv({
4
  apiKey: process.env.RECURSIV_API_KEY,
5
});

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 }.

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv();
4
5
const { data: project } = await r.projects.create({ name: 'my-app' });
6
console.log(project.id); // UUID — use this everywhere a project_id is needed
7
8
const { data: db } = await r.databases.ensure({
9
  project_id: project.id,
10
  name: 'main',
11
});
12
13
const { data: result } = await r.databases.query({
14
  project_id: project.id,
15
  sql: 'SELECT NOW() as time',
16
});
17
18
console.log(db.id);
19
console.log(result.rows);

Run code without signing up

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

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv({ anonymous: true });
4
5
const { data, meta } = await r.sandbox.execute({
6
  code: 'console.log(1 + 1)',
7
  language: 'typescript',
8
});
9
10
console.log(data.output); // "2\n"
11
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:

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv();
4
5
for await (const chunk of r.agents.chatStream('agent_1', {
6
  message: 'Help me build a landing page',
7
})) {
8
  process.stdout.write(chunk.delta ?? '');
9
}

React Native does not expose ReadableStream consistently. Use chatStreamText() or follow the React Native guide.

Start a project sandbox

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

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv();
4
5
await r.projects.createSandbox(project.id);
6
7
const { data: result } = await r.projects.executeCode(project.id, {
8
  code: 'console.log("hello from the project sandbox")',
9
  language: 'typescript',
10
});
11
12
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:

1
import { Recursiv } from '@recursiv/sdk';
2
3
const r = new Recursiv();
4
5
// Creates a real repo under the platform's GitHub owner — no GitHub account,
6
// gh CLI, or local git required. Templates: 'nextjs' | 'expo'.
7
const { data: repo } = await r.github.createFromTemplate({
8
  template: 'nextjs',
9
  name: 'my-app',
10
});
11
12
const { data: project } = await r.projects.create({
13
  name: 'my-app',
14
  repo_url: repo.repo_url,
15
});
16
17
const { data: deployment } = await r.projects.deploy(project.id, {
18
  branch: 'main',
19
  type: 'production',
20
});
21
22
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

$
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 coding assistant should call Recursiv tools directly.

1
{
2
  "mcpServers": {
3
    "recursiv": {
4
      "command": "npx",
5
      "args": ["-y", "@recursiv/mcp"],
6
      "env": { "RECURSIV_API_KEY": "sk_live_xxx" }
7
    }
8
  }
9
}

For local development from this repo, build the MCP package first and point your client at packages/mcp/dist/bin.js.

Use REST

$
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

What’s next?

• Concepts - Understand how projects, agents, and organizations fit together
• SDK Reference - Full SDK documentation with all 40+ resources
• Build an AI-Native App - End-to-end tutorial: database + agent + auth + deploy
• Build an Autonomous Agent - Give an agent its own Postgres, memory, and code execution
• CLI - Scaffold, develop, and deploy from the terminal
• MCP - Give an AI assistant native access to Recursiv via tool use
• API Reference - Full REST API documentation