@grackle-ai/powerline

The PowerLine is the remote agent runtime that runs inside each Grackle environment. It receives commands from the central Grackle server over gRPC (ConnectRPC on HTTP/2), spawns AI coding agents, and streams their output back in real time.

Think of PowerLine as the "agent host" — it runs wherever your code lives (a Docker container, a remote VM, a GitHub Codespace) and manages the full lifecycle of agent sessions: spawning, streaming, input delivery, suspension, and teardown.

How it works

When you add an environment to Grackle, the server connects to that environment's PowerLine instance over gRPC. From there, the server can:

• Spawn agent sessions — start any supported AI runtime with a prompt, model, and optional configuration like MCP servers, git branch isolation, and system context.
• Stream events — receive tool calls, code output, and status updates as they happen, bridged to the Web UI and CLI via WebSocket.
• Deliver input — send user messages to agents waiting for interactive input.
• Suspend and resume — if the gRPC connection drops, buffered events are parked and can be drained on reconnect. Sessions resume where they left off.
• Push credentials — securely inject API keys and tokens as environment variables or files (with path-traversal protection).
• Manage git worktrees — isolate each task on its own branch in its own worktree, so agents never interfere with each other.

Supported runtimes

PowerLine uses a pluggable runtime architecture. Each runtime implements a common interface for spawning and streaming agent sessions.

| Runtime | Description | | --------------- | --------------------------------------------- | | Claude Code | Anthropic's Claude via the Agent SDK | | Copilot | GitHub Copilot CLI agent | | Codex | OpenAI Codex CLI agent | | Goose | Goose agent (via ACP) | | GenAIScript | Script-based agent for single-turn automation |

Additional runtimes can be added by implementing the AgentRuntime interface.

Resource access (AHP)

As an AHP host, PowerLine exposes a read-only view of the filesystem its sessions run in, over the standard AHP resource* methods. Access is sandboxed to the working trees of the connection's sessions — each createSession adds that session's working directory (and, when worktrees are enabled, its sibling worktree path) to the connection's allowed roots. Requests for paths outside every allowed root are rejected with PermissionDenied (-32009).

• resourceRead — read a file's contents by file:// URI. Returns utf-8 for text content and base64 for binary (or the explicitly requested encoding), with a best-effort contentType.
• resourceList — list a directory's entries (name + file/directory).
• createResourceWatch — start a filesystem watcher over a file:// URI and return an ahp-resource-watch:/<id> channel. Subscribe to that channel to receive batched resourceWatch/changed actions (added/updated/deleted); unsubscribe — or disconnect — to release the watcher.

Installation

npm install @grackle-ai/powerline

You don't typically install PowerLine directly. The Grackle server installs and launches it automatically in Docker environments, and it runs as a standalone process in SSH and Codespace environments.

For development or manual use:

npx @grackle-ai/powerline --port 7433 --token <secret>

Usage

# Start with authentication (required by default)
grackle-powerline --token my-secret-token

# Or use an environment variable
GRACKLE_POWERLINE_TOKEN=my-secret-token grackle-powerline

# Start without authentication (development only)
grackle-powerline --no-auth

# Start on a custom port and host
grackle-powerline --port 9000 --host 0.0.0.0 --token my-secret-token

A token is required by default via --token or the GRACKLE_POWERLINE_TOKEN environment variable. To run without authentication for local development, pass --no-auth explicitly. When --no-auth is set, any token from --token or the environment variable is ignored.

Health check

PowerLine exposes a /healthz endpoint on the same HTTP/2 port for container health probes. It requires no authentication and returns 200 {"status":"ok"} with Cache-Control: no-store.

# Check with Node.js (HTTP/2)
node -e "const client=require('http2').connect('http://127.0.0.1:7433'); const req=client.request({':path':'/healthz'}); req.on('response',h=>console.log(h[':status'])); req.on('data',d=>console.log(d.toString())); req.on('end',()=>client.close()); req.end();"

Requirements

• Node.js >= 22
• Agent runtimes are installed on demand — only the runtimes you use need to be available on the system

License

MIT