Skip to main content

Getting Started

Get Grackle running and spawn your first AI agent session in about 5 minutes.

Requirements​

  • Node.js 22 or later
  • Docker (if you want containerized environments)

Install and start​

# Install the CLI globally
npm install -g @grackle-ai/cli

# Start the server
grackle serve

This starts three things on localhost:

  • gRPC server on port 7434
  • Web UI on port 3000
  • MCP server on port 7435

A local PowerLine instance also starts automatically — you can run agents on your own machine right away.

Skip the global install

You can prefix every command with npx instead:

npx @grackle-ai/cli serve
pnpm users

pnpm v8+ blocks native install scripts by default. If grackle serve crashes with a Could not locate the bindings file error, run pnpm approve-builds after installing, or add this to your package.json:

{ "pnpm": { "onlyBuiltDependencies": ["better-sqlite3"] } }

Open the web UI​

Navigate to http://localhost:3000. On first launch you'll see a setup wizard that walks you through picking a default runtime (Claude Code, Copilot, or Codex).

Add a Docker environment​

If you have Docker running, add a containerized environment:

grackle env add my-env --docker
grackle env provision my-env

The provision step pulls an image, starts a container, installs PowerLine inside it, and connects. You'll see progress streamed to your terminal.

Spawn your first session​

grackle spawn my-env "Say hello and list the files in the current directory"

You'll see the agent's output streamed in real time — text, tool calls, and results. Press Ctrl+C to detach (the session keeps running).

You can also spawn sessions from the web UI by clicking New Chat and selecting an environment.

What's next​

You now have a working Grackle setup. From here: