Quickstart

Go from an empty directory to a running agent. Scaffold a typed project, point it at a model, run it locally, then deploy by connecting a repository.

#Prerequisites

Kraken AI projects are standard TypeScript packages. You need a working local toolchain and one model provider key.

  • A current Node.js LTS — the SDKs and CLI are distributed as ES modules and target a modern Node runtime.
  • A model API key — the default template uses a Google Gemini model, so a Google API key is sufficient to start. You can switch providers when you scaffold.
  • A package manager — pnpm, npm, yarn, or bun. The scaffolder auto-detects which one invoked it.

#Scaffold a project

The @kraken-ai/create-agents scaffolder generates a complete, typed multi-agent project. Run it with your package manager of choice.

$ pnpm create @kraken-ai/agents my-project

Run with no flags for an interactive setup, or pass flags to skip the prompts. Two templates are available:

  • market-intel (default) — a multi-agent market intelligence pipeline with human-in-the-loop review, demonstrating connectors, skills, and actions working together.
  • starter — a minimal research and review project: a small set of agents, a filesystem connector, one skill, and two actions. This guide uses the starter template.
$ pnpm create @kraken-ai/agents my-project --template starter

Use the -m (or --model) flag to choose the model every generated agent runs on. The default is google/gemini-3-flash-preview; google/gemini-3.1-pro-preview and openai/gpt-5.4 are also supported.

$ pnpm create @kraken-ai/agents my-project --template starter --model openai/gpt-5.4

Tip

The model provider determines which key you need. A google/* model expects GOOGLE_API_KEY; an openai/* model expects OPENAI_API_KEY. The generated .env.example contains the correct variable for the model you chose.

#Project structure

The starter template produces a single typed package. Agents, connectors, skills, and actions are plain modules — the file name is the identity.

my-project/ package.json tsconfig.json .env.example README.md src/ agents/ researcher.tsReads files via the filesystem connector summarizer.tsOrchestrates the researcher as a team member reviewer.tsApproves or rejects content via actions connectors/ filesystem.tsTools: fs_read, fs_write, fs_list skills/ research-guidelines/ SKILL.mdSkill frontmatter + procedure body actions/ approve.tsTyped outbound action reject.tsTyped outbound action clients/ chat.tsStream a chat with an agent action-client.tsRun an agent with typed action handlers
  • agents/ — agent definitions. Each module exports one agent; agents can run alone or coordinate as a team.
  • connectors/ — how agents perceive and act on systems. The filesystem connector exposes fs_read, fs_write , and fs_list tools scoped to a data directory.
  • skills/ — versioned procedures an agent loads on demand. A skill is a directory with a SKILL.md file.
  • actions/ — structured, typed outputs an agent emits to drive downstream work.
  • clients/ — example server-side usage of the PlatformClient for calling agents from your own application.

For the vocabulary behind each of these, see Core Concepts.

#Configure your model key

The scaffolder writes a .env.example with the variables your project reads. Copy it to .env and fill in your model provider key.

$ cd my-project
$ cp .env.example .env

Open .env and set the key for the model you scaffolded with. For the default Google model:

.env
GOOGLE_API_KEY=your-google-api-key

# Optional — set these to talk to a deployed platform from the SDK.
# Leave empty for local-only `kraken dev`.
KRAKEN_BASE_URL=
KRAKEN_API_KEY=

Important

Never commit .env. The generated .gitignore already excludes it. Keys belong in your local environment or your hosting provider’s secret store.

#Run locally

With dependencies installed and a key in place, the CLI runs an agent on your machine so you can iterate before deploying.

  1. Install dependencies

    Install from the project root. The postinstall script runs kraken generate to produce type definitions from your local agents, connectors, skills, and actions.

    $ pnpm install

  2. Run an agent

    The dev script runs kraken dev, which executes an agent locally without a deployed platform.

    $ pnpm dev

    Pass --debug to print the system prompt, registered tools, and per-turn tool arguments and results.

  3. Type-check your changes

    The check script type-checks the project. As you edit agents and connectors, run it to catch issues before deploying.

    $ pnpm check

#Deploy

Deployment is repository-driven. You connect a GitHub repository to the platform once, and every push to the default branch builds and deploys your project automatically — no separate deploy command.

  1. Push your project to GitHub

    The scaffolder initializes a git repository and makes the first commit. Add a remote and push.

    $ git remote add origin <your-repo-url>
$ git push -u origin main

  2. Connect the repository

    In the control plane, open Integrations and import your GitHub repository. GitHub is the supported provider.

  3. Push to deploy

    Every push to the default branch triggers a build and deploy. From then on, triggers start runs against the deployed project.

For build configuration, environments, and rollout behavior, see Deployment.

#Next steps

  • Core Concepts — The platform vocabulary: agents, runs, connectors, skills, actions, memory, triggers, governance, and audit.
  • Agents — Define single agents and multi-agent teams, configure models, and wire in connectors, skills, and actions.
  • CLI — Reference for the kraken CLI: login, generate, dev, validate, and managing API keys.