@spaceboy-ai/sdk

The Spaceboy SDK for TypeScript and JavaScript: create projects, run building agents, and ship deploys from your own applications. Every method wraps the same GraphQL API that powers the Spaceboy dashboard, the CLI, and the iOS app.

• Docs: https://spaceboy.ai/docs/developer-reference — every capability, documented across the CLI, the HTTP API, and this SDK
• Requires: Node 20+ and an API key (create one on the API Keys page in your dashboard)

The class is still named Repobot for existing imports; prefer the Spaceboy export.

Install

npm install @spaceboy-ai/sdk

Quickstart

import { Spaceboy } from "@spaceboy-ai/sdk"

const spaceboy = new Spaceboy({
  apiKey: process.env.SPACEBOY_API_KEY,
})

// Describe an app; the agent derives a plan, builds it, and publishes it
const draft = await spaceboy.setup.start({
  description: "A storefront for handmade ceramics",
})
const finished = await spaceboy.setup.wait(draft.id)
console.log(finished.liveDeploy?.resultUrl)

// Keep building on the result
const { reply } = await spaceboy.agent.message({
  projectId: finished.projectId!,
  text: "Add a product reviews section",
})

// Ship it
const deploy = await spaceboy.deploys.request({
  projectId: finished.projectId!,
  target: "PRODUCTION",
})
console.log(deploy.resultUrl)

What's in the box

| Namespace | What it does | | --- | --- | | me(), orgs | Who you are; list and create organizations | | projects | List and create projects; starter templates | | setup | The setup wizard, headless: describe → plan → build → live URL | | agent, ask(), actions | Chat with a project's agent; ask the account agent; confirm proposed actions | | tasks, plans | Fire-and-forget tracked tasks; dependency-graph plans shipped as one release | | deploys, builds, reviews, cicd | Deploys with wait-for-URL, mobile builds, release reviews, CI health | | environments, sessions, previews | Environments and infrastructure; workspace sessions; shareable previews | | domains, theme | Custom domains with DNS records; the app's theme | | billing, integrations, runs, kernel | Plans and credits (incl. saved-card top-ups), BYO connections, agent run forensics, kernel upgrades |

Long-running operations (setup.wait, tasks.watch, deploys.request, plans.run) poll server-side state and resolve on success or throw a RepobotError — the same semantics as the CLI's --wait flags.

Errors

import { Spaceboy, RepobotError } from "@spaceboy-ai/sdk"

const spaceboy = new Spaceboy({ apiKey: process.env.SPACEBOY_API_KEY })

try {
  await spaceboy.deploys.request({ projectId, target: "PRODUCTION" })
} catch (error) {
  if (error instanceof RepobotError) {
    console.error(error.code, error.message)
    // Out-of-credits errors carry error.usage with the balance and
    // top-up bounds; spaceboy.billing.topUp() is the remediation.
  }
}

The escape hatch

The typed surface covers the operations most integrations need. Everything else in the API — the schema is introspectable — is one call away:

const data = await spaceboy.graphql(
  `query($input: AuditLogsInput!) {
    auditLogs(input: $input) { nodes { occurredAt action summary } }
  }`,
  { input: { accountId } },
)

Configuration

| Constructor option | Environment variable | Default | | --- | --- | --- | | apiKey | SPACEBOY_API_KEY (REPOBOT_API_KEY fallback) | — (required) | | account | SPACEBOY_ACCOUNT (REPOBOT_ACCOUNT fallback) | the key's home organization | | apiUrl | SPACEBOY_API_URL (REPOBOT_API_URL fallback) | https://api.spaceboy.ai/graphql |

Prefer a terminal?

The @spaceboy-ai/cli package wraps the same platform for shells, CI pipelines, and coding agents — non-interactive, --json output, meaningful exit codes.