PaddleBoard

PaddleBoard is a fork of Zed tuned for AI-native development. It keeps Zed’s speed, GPU-accelerated rendering, LSP, debugger, terminal, and git workflow, then layers on the pieces a modern coding agent actually needs — on your terms:

• Bring-your-own-key models — OpenAI, Anthropic, Google, Vertex AI, Bedrock, and more. No hosted plan, no upsells.
• An agent workbench — an agent panel with delegation, plus first-class support for the ADK, LangGraph, CrewAI, and AutoGen frameworks.
• The AI Dock — install and manage agents, skills, and MCP servers from one place.
• Private by default — telemetry is hard-disabled at the source; no account required. Even usage visibility (the agent context gauge in the status bar) is computed and displayed entirely on your machine.

Status: alpha. Build from source — there are no released binaries yet, and builds are not yet notarized by Apple. See Getting Started.

These docs are task-oriented “how-to” guides. For a quick in-app tour, open the command palette and run workspace: Open Paddle Board Tour.

Getting Started

PaddleBoard is alpha and currently builds from source — there are no released binaries yet.

Prerequisites

• Rust (via rustup).
• macOS: Xcode + Xcode command-line tools, and cmake.
• Linux: run script/linux to install system dependencies.
• Windows: Visual Studio with the C++ toolchain, the Windows SDK, and cmake.

Build and run

git clone https://github.com/paddleboarddev/paddleboard.git
cd paddleboard
cargo run -p paddleboard

The first build takes a while (it compiles the whole workspace). Subsequent runs are fast.

First steps

1. Add a model. PaddleBoard ships with no model configured — open the agent panel and add your own API key for a provider. See Configuring LLM Providers.
2. Open a project. Common languages work immediately; others are one click away in Language Support.
3. (Optional) Save your git credentials so pushes don’t prompt — see Git Login.

A note on macOS Gatekeeper

PaddleBoard is not yet code-signed or notarized with an Apple Developer ID. Building from source yourself is unaffected. Once distributed binaries exist, macOS will warn that “Apple cannot check it for malicious software” until notarization is in place — you’d allow it via System Settings → Privacy & Security.

Personas: Tell Your Agent Who to Be

Skills define what your agent can do. A persona defines who it should be — its voice, values, and what it pushes back on. Describe the teammate you want (a Senior Developer, an SRE, a QA Engineer) and PaddleBoard holds the agent to that identity for the whole thread, with any LLM provider.

Personas apply to the native PaddleBoard Agent. External agents (Claude Code, Codex, …) own their system prompts, so persona selection doesn’t apply there — on those threads a muted persona icon links back to the AI Dock’s Personas tab.

Quick start

Drop a PERSONA.md at your project root:

You are a Site Reliability Engineer. You think in blast radius and rollback
plans. For any deploy or migration, ask for the rollback plan before
discussing the rollout. Flag missing timeouts, retries without backoff, and
single points of failure whenever they appear.

That’s it. Every new PaddleBoard Agent thread in that project adopts the persona automatically — plain prose works, no frontmatter required.

The persona library

For more than one persona, keep a library of <name>.persona.md files:

• {project}/.claude/personas/ — project-scoped
• ~/.claude/personas/ — available in every project

Library files use flat YAML frontmatter plus a markdown body:

---
name: qa-engineer
description: A meticulous QA engineer who hunts edge cases.
type: role
voice: terse, skeptical, asks for repro steps before agreeing
---

# Identity
...

# Behavioral rules
- Before proposing a fix, ask for exact reproduction steps.
- When asked to "ship it," name the tests that would have to pass first.

name and description are required for library personas — the description is what the agent (and the picker) uses to choose between them. A project-library persona shadows a user-library persona with the same name.

Writing tip: short, imperative behavioral rules (“ask for repro steps before proposing a fix”) hold up far better over a long conversation than paragraphs of backstory.

Switching personas

Three ways, in increasing order of laziness:

1. The picker. A persona pill sits in the agent panel’s message toolbar, next to the profile selector. Click it to switch or clear the persona for the current thread. The persona is saved with the thread and survives restarts.
2. Just ask. The agent sees your persona catalog in its system prompt and carries an adopt_persona tool — say “be my QA tester” mid-conversation and it switches itself, applying the new identity from its very next response. “Drop the persona” returns it to the default voice. The agent only changes personas when you ask.
3. Starter roles. The AI Dock’s Personas tab ships three ready-made roles — Senior Developer, Site Reliability Engineer, QA Engineer — with one-click Add to project / Add to user install, and lists every persona discovered in your project.

Composing personas with extends:

A persona can inherit another’s rules:

---
name: strict-qa
description: QA engineer on the house base.
extends: house-base
---

The parent’s body is included in the overlay ahead of the child’s (chains are followed; cycles are cut; a missing parent is skipped with a warning), so the child’s own rules always read last and win. Use it to keep a shared “house style” base that every role builds on.

Personas for sub-agents

Delegated work can wear its own identity: the agent can pass persona to its spawn_agent tool — or you can ask it to (“have a QA-persona sub-agent review this”). The sub-agent holds that identity for its whole session while your main thread keeps its own voice. A review pass that genuinely thinks like a reviewer beats an implementer grading their own work.

How it works

The persona is injected into the agent’s system prompt as an identity overlay, snapshotted when selected so a thread’s identity stays stable even if the file changes on disk. Because it rides the system prompt, it works identically with every configured LLM provider and stays byte-stable per thread, which keeps provider prompt caches warm. A persona shapes how the agent responds — tone, priorities, what it pushes back on — never its honesty or capabilities, and it composes with (rather than replaces) your project rules.

Settings

{
  "paddleboard_personas": {
    // Default true. The feature is inert until a persona file exists.
    "enabled": true
  }
}

Set Sail: Deploy to Serverless

Set Sail is PaddleBoard’s serverless-first “deploy to $platform” button. Quick-deploy the current project to Cloud Run, AWS Lambda, or Vercel — no pipeline YAML, no IAM safari. The agent does the work, following the open-source s8sskills playbook.

Quick start

1. Click the ⛵ sailboat in the status bar (or run set sail: Deploy from the command palette).
2. Pick your platform. The modal pre-fills a service name from your project folder; adjust it, set a region where it applies (Vercel manages placement itself), and choose whether the URL should be public. Not set up on the vendor yet? The Get started link at the bottom of the modal takes you to their signup.
3. Click Set Sail. PaddleBoard:
   • installs the platform’s s8sskills pack into your project’s .agents/skills/ — gcloud-project-setup + cloud-run-deploy (GCP), aws-project-setup + lambda-deploy (AWS), or vercel-project-setup + vercel-deploy (Vercel) — skipped if already present, so pin them in git for a fixed version;
   • opens a PaddleBoard Agent thread that reads those skills and follows them.
4. The agent checks your CLI setup first. Anything interactive — gcloud auth login, aws configure, vercel login — is handed to you to run in a terminal; the agent never runs auth flows itself.
5. On success it reports your live URL and everything it created, so you can find (and later clean up) each resource.

Prerequisites

How it works

The platform knowledge is deliberately not hardcoded in PaddleBoard. Set Sail installs versioned skill packs from the community s8sskills catalog and lets the agent follow them — so support for more platforms (Azure, Cloudflare, Netlify, …) arrives by publishing skill packs, not by changing the editor. The deploy runs in a normal agent thread: every command goes through PaddleBoard’s usual permission flow, and you can watch, step through, or stop it like any other agent work.

Costs and cleanup

A real deploy creates billable resources in your cloud account (e.g. a Cloud Run service and Artifact Registry repo, or a Lambda function; Vercel hobby deploys are free-tier). The agent’s success report lists what was created — remove a test deploy with the platform’s delete command, e.g.:

gcloud run services delete <service-name> --region <region>
aws lambda delete-function --function-name <service-name>
vercel remove <service-name>

What’s next

• Rig the pipeline (planned): instead of a one-off deploy, Set Sail will set up the durable flow — repo, GitHub Actions workflow, workload identity — so every git push deploys, the way production teams work.
• More platforms as s8sskills packs land.

Configuring LLM Providers

PaddleBoard is bring-your-own-key: you connect your own model accounts. There is no hosted PaddleBoard plan, and nothing is gated behind a PaddleBoard sign-in.

Add a provider

1. Open the agent panel.
2. Open agent settings → Configure Providers (or the command palette → provider config).
3. Pick a provider, paste your API key, and save. Keys are stored in your OS keychain (never in settings or plaintext).

Most providers also read a standard environment variable (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY) as a fallback.

Supported providers

Includes Anthropic, OpenAI (and ChatGPT subscription auth), Google AI (Gemini), Google Vertex AI, Amazon Bedrock, DeepSeek, Mistral, OpenRouter, Vercel AI Gateway, and local runners (Ollama, LM Studio).

Google Vertex AI (Gemini Enterprise)

Vertex is a PaddleBoard addition for teams whose Gemini access runs through Google Cloud. It supports three auth modes, in precedence order:

1. Service-account key — set credentials_path to a service-account JSON file.
2. Express API key — paste an AI Studio / Express key.
3. gcloud (recommended, no stored secret) — run gcloud auth login once; PaddleBoard borrows short-lived Application Default Credentials. Just set project_id (and optionally location, default global) and it works.

Configure it from the provider settings (project id, location, optional credentials path). Newer models (e.g. Gemini 3) live on the global location, which is the default.

Privacy

Telemetry is hard-disabled in PaddleBoard — your prompts and usage never leave your machine except for the calls you make directly to your chosen provider.

The AI Dock

The AI Dock is one place to browse, install, and create the AI building blocks PaddleBoard supports: agents, skills, and MCP servers.

Open it from the command palette → ai dock: Open.

Tabs

• Agents — register a custom agent server by registry ID (Add Agent), or install a catalog agent. CLI-based agents (e.g. Google ADK) show a Set Up button that opens a terminal with the install command rather than running it inside the app.
• Skills — install bundled slash-command skills (/build, /update-tour, /clippy, /test, /check-drift) with Add to project / Add to user, or Create Skill to write a new .claude/commands/ markdown command.
• MCP — add and manage Model Context Protocol servers, with live status and streaming logs — or Build an MCP to have an agent generate one for a service that has none. See Sandboxed Execution & MCP.

The catalog is data-driven from assets/ai_dock/catalog.json in the repo — additions are pull requests, not network fetches.

Agent Frameworks

PaddleBoard has first-class support for four Python agent frameworks: Google ADK, LangGraph, CrewAI, and AutoGen. When you open a project that declares one of them (in pyproject.toml / requirements.txt), PaddleBoard detects it and offers to run it.

Running a framework

Each framework registers command-palette actions, e.g. adk: Run Agent, crewai: Run Agent.

• Dev-server frameworks (ADK, LangGraph, AutoGen Studio) launch a local server and forward its port into the embedded browser. For example autogen: Run Agent runs autogenstudio ui --port 8081 and streams startup logs to a tab.
• One-shot frameworks (CrewAI) run to completion and stream output to a tab — no port forwarding (crewai: Run Agent → crewai run).

Scaffolding

Frameworks with a project generator expose a Scaffold action (e.g. adk: Scaffold Agent, crewai: Scaffold Agent) that opens a small modal and runs the create command in a terminal.

Installing the CLIs

The frameworks themselves are external tools — install them in your environment (e.g. pip install crewai, pip install autogenstudio). PaddleBoard drives them; it doesn’t bundle them.

Scion: Isolated Parallel Agents

Scion runs “deep agents” as isolated, concurrent processes — each in its own container and git worktree. PaddleBoard integrates with a local Scion daemon so you can launch and watch those agents from the editor, and even delegate subtasks to them from your own agent.

Enable it (opt-in)

Scion is off by default. Turn it on in your settings:

{
  "paddleboard_scion": { "enabled": true }
}

Then install the Scion CLI and initialize it:

go install github.com/GoogleCloudPlatform/scion/cmd/scion@latest
scion init --machine   # one-time, sets up the container runtime
scion init             # in your project

Scion needs a container runtime (Docker / Podman / Apple Container).

Use it

• scion: Start Agent (command palette) opens a modal — set a task, name, and template.
• The Orchestration Panel shows a Scion Agents section with each agent’s phase (provisioning → running → stopped) and activity (working, thinking, waiting…). Right-click a row for View Logs (live-streaming), Sync Changes (pull its worktree changes into your project), or Stop Agent.
• Delegation: when enabled, your agent gains a spawn_scion_agent tool — it can hand a subtask to a container + worktree-isolated Scion agent (instead of an in-process sub-agent that shares your workspace), wait for it, and return the result.

Telemetry (optional)

Scion can export agent-lifecycle traces over OpenTelemetry. See the Settings Reference for paddleboard_otel.

Language Support

PaddleBoard keeps the default install lean with two tiers.

Ready to use

Common languages — Rust, TypeScript/JavaScript, Python, Go, JSON, YAML, HTML/CSS, and more — are enabled by default. Open a matching file and the language server attaches automatically, downloading on first use.

Install support (opt-in)

Languages that need an external toolchain are opt-in. Run Manage Languages from the command palette to enable them; each row shows its prerequisite up front so it never fails silently when the runtime is missing.

Six ship a built-in server:

Ruby and Dart get their servers from extensions, so their row opens the Extensions page.

Why opt-in? It keeps the default install small and means you choose to pull in a heavier toolchain knowingly, rather than hitting a confusing “server reset the connection” crash when the runtime isn’t present.

Git Login

Save your git host credentials once so HTTPS git operations stop prompting on every clone/fetch/push.

The logins list

Run git login: Manage from the command palette. The modal lists each provider — GitHub, GitLab, BitBucket — with its live status: Signed in as <user> or Not signed in. Click a row to select it, or click Remove on a row to delete its saved login. Custom hosts (e.g. a self-hosted GitLab) are managed through the form fields below the list.

Sign in with GitHub (browser)

On builds configured with an OAuth client id, selecting GitHub shows a Sign in with GitHub (browser) button:

1. PaddleBoard displays a short code (like WDJB-MJHT) and opens github.com/login/device.
2. Enter the code and approve access.
3. The token is stored in your OS keychain automatically — you’re signed in.

This is the same device flow the gh CLI uses; no client secret is involved. If the button isn’t there, the build has no client id configured — use a token instead, which always works.

Save a token manually

1. Pick a provider from the list (or enter a custom host).
2. Enter your username and paste a Personal Access Token (the modal links straight to the provider’s token page and lists the scopes to grant).
3. Save. The token is written to your OS keychain — never to settings or plaintext.

After that, git HTTPS clone / fetch / push authenticate silently. The password prompt only appears when there’s no saved login.

Remember from the prompt

No saved login yet? When git’s password prompt appears, tick “Remember on this device” before submitting — the credential is saved to your keychain and the next operation authenticates silently.

Beyond git: API requests

A saved GitHub login also authenticates PaddleBoard’s GitHub API requests — commit-author avatars in git blame resolve on private repos, and you skip the unauthenticated rate limit. GitHub Enterprise hosts use their own saved login. (GITHUB_TOKEN still wins when set.)

Environment-variable fallback

If you’d rather not store a token, set one of these and PaddleBoard answers git auth from it:

export GITHUB_TOKEN=...      # or GITLAB_TOKEN / BITBUCKET_TOKEN

Notes

• PaddleBoard sends the conventional token username per provider unless you set your own: x-access-token (GitHub), oauth2 (GitLab), x-token-auth (BitBucket).
• OAuth sign-in is GitHub-only — GitLab and BitBucket don’t offer a comparable device flow, so they use tokens.
• HTTPS only. SSH key passphrases and host-key confirmations are untouched and still prompt as usual.

Manifest: Your Git State at a Glance

The Manifest panel is a dockable tree that lays out the project’s entire git world in one place — the ship’s manifest. Open it with the tree icon in the dock, or run manifest: Toggle Focus from the command palette.

Everything in the panel reads from state PaddleBoard already tracks in the background, so it renders instantly and never runs git commands on the UI thread.

The five sections

Each section is a collapsible header with a count; click the header (or its disclosure arrow) to fold it away.

Repositories

Every repository in the workspace — multi-repo projects and worktree-backed workspaces included — each flying a sailboat. The active repository is highlighted with a check; click any other repo to make it active. The Branches, Commits, and Stashes sections below always describe the active repository, so this row doubles as the panel’s scope switch.

Branches

The active repo’s local and remote branches, sorted current-branch-first, then local before remote, then by recency. Branches with an upstream show ahead/behind counts (↑2 ↓1) so you can see what needs a push or pull without running anything.

Commits

The current branch’s recent history — up to 250 commits. Subjects stream in as commit metadata loads (rows briefly show Loading… on first open). Click any commit to open its full diff in a commit view tab.

For history beyond the overview — the full graph, searching, other branches — use the Git Graph (the Git panel’s History tab); Manifest deliberately stays a summary.

Stashes

Every stash@{n} with its message. Click a stash to open it in the stash view, which shows its diff and offers Apply, Pop, and Drop.

Contributors

Everyone who has committed to the repository, with their commit count, busiest first. Computed locally with git shortlog when the panel loads and refreshed when the branch head changes.

Note: in a collaboration session on a remote project, the Contributors section is empty — the query currently runs only against local repositories.

Tips

• The panel docks left by default; drag it (or use the dock context menu) to move it right.
• Repo switching from the Repositories section is the same operation as the Git panel’s repository selector — the two stay in sync.

Sandboxed Execution & MCP

PaddleBoard can run agent-invoked code and MCP servers inside an isolated container instead of directly on your host.

Secure agent sandbox

Tool calls that execute code run inside an ephemeral ubuntu:latest container via Podman + the runsc (gVisor) kernel runtime. Your project is bind-mounted; the rest of the host filesystem is not exposed. Permissions still flow through the normal approve / deny / always-allow UI.

A status-bar shield shows live prereq status. If Podman/gVisor aren’t available, behavior is governed by paddleboard_sandbox.on_missing_runtime:

• block (default) — opens the install modal.
• fall_back_to_host — run on the host instead.
• warn_once — warn, then run on the host.

Sandboxed MCP servers

A sandboxed_stdio context-server transport runs MCP servers inside Podman + gVisor too, proxying stdin/stdout transparently so the JSON-RPC framing is unchanged. It’s opt-in per server; the plain stdio transport still works for servers that don’t need isolation.

Manage servers from the MCP tab of the AI Dock, or the dedicated MCP Servers settings page (command palette → zed: Mcp Servers), which lists configured servers and surfaces status and logs without hand-editing JSON.

Build an MCP for any service

When a service has no MCP server, the Build an MCP button at the top of the AI Dock’s MCP tab generates one. You provide:

• a service (e.g. Substack),
• an optional API-docs URL,
• an optional auth env-var name (e.g. SUBSTACK_API_KEY), and
• a sentence describing what it should do.

PaddleBoard then seeds a visible agent thread that researches the service’s API, writes a Python (FastMCP) server, tests it in the sandbox, and installs it into the AI Dock. Because the thread is visible, you can watch the build and course-correct.

The install runs host-side (via the install_mcp_server tool, which you approve): it writes the server under PaddleBoard’s data directory — on macOS ~/Library/Application Support/PaddleBoard/mcp_servers/<id>/ — and registers it as a plain stdio context server that runs with uv run. The generated server reads its API key from the environment PaddleBoard was launched with, so no secret is ever written to settings: just export the variable (e.g. export SUBSTACK_API_KEY=…) in the shell you launch PaddleBoard from. Once installed, the server appears in the MCP tab and starts automatically.

Requirements. uv must be on your PATH — it provisions the server’s Python dependencies on first launch. Open a project before building, since the agent needs an active workspace to work in.

Search & Status Bar Extras

Two quality-of-life additions on top of Zed’s editor.

Search as you type

Project search runs automatically as you type — results update a beat (~200ms) after you pause, no Enter required. This matches VSCode’s behavior and one of upstream Zed’s most-requested changes (zed#9318).

Prefer the classic press-Enter behavior? Turn it off:

{
  "search": { "search_on_type": false }
}

Agent context gauge

While an agent thread is running, a percentage appears in the status bar showing how much of the model’s context window the active thread has used:

• The color follows the agent panel’s thresholds — muted, yellow as you approach the limit, red past it.
• Hover for the token breakdown: used / total, input vs. output.
• Click to jump to the agent panel.
• It hides itself when no thread has token usage.

The gauge is purely local: it displays counts the agent thread already tracks on your machine. Nothing is collected or reported — PaddleBoard’s telemetry stays hard-disabled.

Settings Reference

PaddleBoard-specific settings (on top of all of Zed’s). Add them to your settings.json.

Search

{
  "search": { "search_on_type": true }
}

Project search runs as you type (default true). Set false for the classic press-Enter behavior. See Search & Status Bar Extras.

Scion

{
  "paddleboard_scion": { "enabled": false }
}

Enables the Scion integration (default false). Installing the scion CLI alone does not activate it — this toggle does.

OpenTelemetry (Scion tracing)

{
  "paddleboard_otel": {
    "enabled": false,
    "endpoint": "http://localhost:4317",
    "protocol": "grpc"
  }
}

Exports Scion agent-lifecycle traces over OTLP to a collector (Jaeger, Tempo, etc.). Can also be enabled with PADDLEBOARD_OTEL_ENABLED=1.

Sandbox

{
  "paddleboard_sandbox": { "on_missing_runtime": "block" }
}

Controls what happens when the Podman/gVisor sandbox prerequisites are missing: block (default), fall_back_to_host, or warn_once.

Vertex AI

Configured under the Vertex provider settings — project_id, optional location (default global), and optionally credentials_path (service-account JSON) or an Express key. See Configuring LLM Providers.

Telemetry

There is nothing to configure: telemetry is hard-disabled in PaddleBoard. Events are dropped at the source and never reach the network.