# SeaShell documentation

> SeaShell is a model-agnostic, terminal-native AI coding agent. Plan, edit, and ship from the place you already live: your shell.

Install SeaShell, connect your models, organize agents and workflows, and keep control of code, context, and client data from the terminal.

## Install

```sh
curl -fsSL https://seashell.sh/install | sh
```

## Introduction

**SeaShell** is a model-agnostic, terminal-native AI coding agent for developers and teams that want control over their model routes, code context, tools, and approval flow.

SeaShell is designed around four operating principles:

- **Bring your own models.** Use hosted, local, self-hosted, or approved open-source models based on the work.
- **Keep private work private.** Local embeddings, permission gates, and auditable tool calls help protect client and company code.
- **Use agents intentionally.** SeaShell can plan, build, review, and coordinate multiple agents when a task is large enough.
- **Stay in the terminal.** Sessions, diffs, approvals, models, MCP tools, and copy formats are all reachable from the TUI.

## Installation

SeaShell ships as a single binary. Install it, restart your shell if needed, then run `seashell --version` to confirm your PATH.

#### macOS and Linux

```bash
curl -fsSL https://seashell.sh/install | sh
```

#### Windows PowerShell

```powershell
irm https://seashell.sh/install.ps1 | iex
```

> **Keep devices current:** Run `seashell upgrade` on each machine. SeaShell updates the local binary on that device; repository changes still move through git.

## Free account signup and sign-in

SeaShell works without an account. A free account gives this installation an authenticated SeaShell identity and lets SeaShell read the account's effective entitlement when account features are used.

Run `seashell signup` and enter your email. SeaShell sends a six-digit code: a new email creates a free account, while an existing email signs back in. No password is created or entered in the terminal.

terminal:
```bash
seashell signup

# These names open the same passwordless flow:
seashell signin
seashell login
```

> **Account remains optional:** Installation, local usage, and SeaShell updates do not require sign-in. Run `seashell logout` at any time to remove the linked account from this machine.

## Quickstart

Open SeaShell in a repository and describe the outcome. SeaShell reads the project, chooses the right context, proposes a plan when needed, and shows work as reviewable terminal output.

terminal:
```bash
cd ~/code/your-project
seashell

> Review this API change, update the tests, and call out any risky migrations.
```

For larger work, say what you want operationally. Phrases like `use multiple agents`, `parallelize the review`, or `split this into agents` are signals that SeaShell should coordinate separate discovery, implementation, and verification lanes.

> **NOTE:** For one-shot automation, use `seashell run`. For interactive work, use the TUI so you can inspect plans, approvals, sessions, and model choices as the task evolves.

## Update SeaShell

SeaShell has a dedicated upgrade command. Use it instead of passing update flags to the default TUI command.

terminal:
```bash
seashell upgrade
atlas --version
```

If a different machine has newer repository code, pull that repository with git and rebuild from source as needed. If you installed from the public installer, `seashell upgrade` updates the installed binary.

## Models

SeaShell is model-agnostic. List available models, authenticate providers, and select the model that fits the task, budget, and data policy.

terminal:
```bash
seashell providers
seashell models
seashell models --refresh
seashell --model anthropic/claude-sonnet-4-5
```

| Item | Detail |
| --- | --- |
| Hosted provider | Use provider/model IDs after authenticating your provider. |
| Local Ollama | Use local models and embeddings when client data must stay on your machine. |
| Model picker | Switch providers, models, variants, and effort without rebuilding the project. |
| Per-run override | Pass --model provider/model when launching SeaShell or seashell run. |

## Providers & API keys

SeaShell brings your own keys. Set a provider's environment variable, or run `seashell providers` to authenticate interactively, and SeaShell registers that provider's models automatically. A provider counts as configured as soon as any one of its environment variables is set.

The table below is providers, not models. SeaShell does not maintain a model list: the catalog comes from models.dev and is refreshed with `seashell models --refresh`, so any model IDs written here would be stale within a release. Run `seashell models <provider>` for the live list.

terminal:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
seashell models anthropic
seashell --model anthropic/claude-opus-5
```

> **Do not trust a model ID you read in a blog post:** Model IDs are retired on a schedule. `claude-3-5-sonnet` and `gpt-4o` still appear in setup guides across the web and no longer resolve. `seashell models <provider>` reads the live catalog and is the only list worth copying from.

| Provider | Env variable | List models |
| --- | --- | --- |
| Anthropic | `ANTHROPIC_API_KEY` | `seashell models anthropic` |
| OpenAI | `OPENAI_API_KEY` | `seashell models openai` |
| Google | `GOOGLE_GENERATIVE_AI_API_KEY` | `seashell models google` |
| OpenRouter | `OPENROUTER_API_KEY` | `seashell models openrouter` |
| xAI | `XAI_API_KEY` | `seashell models xai` |
| Azure OpenAI | `AZURE_OPENAI_API_KEY` | `seashell models azure` |
| Amazon Bedrock | `AWS_BEARER_TOKEN_BEDROCK` | `seashell models amazon-bedrock` |
| Cloudflare Workers AI | `CLOUDFLARE_API_TOKEN` | `seashell models cloudflare` |

Key links and local-model setup: https://seashell.sh/models.md

## Local models

Use a local model route when client requirements or internal policies require model calls to stay on your machine or approved infrastructure. SeaShell can discover Ollama and LM Studio when you explicitly run the local-model command.

terminal:
```bash
ollama list
ollama pull qwen2.5-coder:latest
seashell models --local
```

> **Data path matters:** A local model only protects data for the calls routed to that model. Keep provider keys, MCP servers, and plugins aligned with the privacy policy you promise clients.

## Agents

Agents are reusable operating modes. Use primary agents for normal work and subagents for focused research, review, migration, or testing lanes.

terminal:
```bash
seashell agent list
atlas agent create
```

Specialized agents live in SeaShell configuration and can carry their own instructions, model preference, and permission profile. Keep them small and purpose-built: reviewer, migration planner, test fixer, security checker, or documentation writer.

## Workflows

Workflows turn repeated senior-engineering patterns into reusable execution paths. Use them when a task needs coordination across files, tests, reviews, or agents.

| Item | Detail |
| --- | --- |
| Single task | Ask SeaShell to make a focused change, then review the plan and diff. |
| Review | Use /review for branches, uncommitted work, PR prep, and delivery checks. |
| Parallel agents | Ask SeaShell to use multiple agents when discovery, migration, testing, or review can run in parallel. |
| Large codebase | Use workflows and context-aware search so SeaShell can narrow the right files before editing. |

prompt examples:
```bash
Use multiple agents: one for TUI routing, one for tests, one for docs.
Run a review workflow before committing this branch.
Use a workflow to migrate this feature and verify the build.
```

## Codebase intelligence

SeaShell gathers context from the repository, session history, project files, command output, and available tools. For large codebases, ask it to map the relevant area before editing.

- Use `/init` to create project guidance SeaShell can read later.
- Ask for a file map before broad migrations.
- Prefer scoped prompts that name the subsystem, test, or failure.
- Use local embeddings when code search must stay private.

The resource hubs expand this further with guides for private AI development, local model orchestration, agentic workflows, and codebase intelligence. [Browse resource hubs](https://seashell.sh/resources)

## Permissions

SeaShell treats tool calls as actions that should be classified and gated. Read-only discovery, file edits, shell commands, network calls, and secret-bearing operations do not carry the same risk.

atlas.json:
```json
{
  "permission": "ask",
  "agent": {
    "default_agent": "build"
  }
}
```

> **TIP:** Use tighter permissions for client repositories and broader permissions only for trusted local maintenance tasks.

## Configuration

SeaShell reads global configuration plus project-level configuration. Use project config for repository conventions and global config for personal defaults.

atlas.json:
```json
{
  "model": "ollama/qwen2.5-coder:latest",
  "theme": "atlas",
  "permission": "ask"
}
```

Environment variables and command flags can override config when you need a one-off model, session, or server mode.

## Plugins & MCP

Plugins extend SeaShell directly. MCP connects SeaShell to external tools and context providers through the Model Context Protocol. Both should follow the same permission discipline as built-in tools.

terminal:
```bash
seashell mcp add
seashell mcp list
seashell mcp auth <name>
seashell mcp debug <name>
```

> **WARNING:** MCP servers can expose external systems. Only add servers you trust, and keep credentials scoped to what the workflow needs.

## Sessions

Sessions keep work durable across restarts and machines when the same repository and data are available. Continue the last session, resume a known session ID, or fork a session when you want a new branch of work.

terminal:
```bash
seashell --continue
seashell --session ses_abc123
seashell --session ses_abc123 --fork
seashell session list
```

## SeaShell Cloud

**SeaShell Cloud** is the optional commercial control plane. The agent keeps running locally with your own model keys; SeaShell Cloud adds accounts, entitlements, release manifests, device registration, sync, and allowlisted telemetry on top.

It is designed so ordinary control-plane operations never require your repo contents, prompts, diffs, terminal output, local indexes, embeddings, model outputs, provider request bodies, file paths, or credentials. The local product talks to SeaShell Cloud through published API contracts only, so cloud availability never blocks your work.

| Item | Detail |
| --- | --- |
| cloud-api | Accounts, entitlements, releases, devices, sync, and telemetry intake. |
| model-router | Optional hosted model routing, provider policy, credits, and rate limits. |
| cloud-worker | Billing reconciliation, usage rollups, retention, and release validation. |

> **Cloud is opt-in:** You can run SeaShell fully local with bring-your-own-keys and never touch the control plane. Cloud features activate only when you sign in or enable them.

Learn more: [the privacy-preserving control plane](https://seashell.sh/resources/features/atlas-cloud).

## Licensing & entitlements

SeaShell verifies licenses **offline** against a key built into the binary, so Pro and Company features unlock air-gapped with no phone-home. SeaShell Cloud resolves entitlements and holds billing records, but the runtime does not need a live connection to confirm what a seat is allowed to do.

- **Core** is free, forever.
- **Pro** is a one-time, per-seat license you own, including every update within its major version.
- **Company** is per-seat, annual, with SSO, RBAC, audit logs, and continuous updates while active.

> **Lapses do not brick:** If a Company subscription lapses, the team keeps the last version it was entitled to and simply stops receiving new updates until it renews. See [offline license verification](https://seashell.sh/resources/features/offline-license-verification).

## Hosted model routing

Bring-your-own-keys and local models are the default. For teams that want one place to set provider policy, enforce rate limits, and account for spend, SeaShell Cloud offers an optional hosted **model router** behind an SeaShell runtime feature flag.

The router manages routing, provider policy, credit checks, rate limits, and usage events, so an organization can standardize and meter model access without distributing raw provider keys to every seat. It records usage (which model, how much), not the content of your requests.

atlas.json:
```json
{
  "cloud": {
    "model_router": true
  }
}
```

Learn more: [hosted model routing without giving up bring-your-own-keys](https://seashell.sh/resources/features/hosted-model-routing).

## Telemetry & privacy

Telemetry intake accepts only an **allowlisted event envelope**. Values that look like prompts, model output, provider bodies, or file paths are rejected before they are ever stored, so product analytics never becomes a backdoor for your code or content.

Release and installer manifests expose only public, non-entitlement artifact metadata. Entitlement and usage reads are token-gated. The privacy boundary is a design constraint on what the API accepts, not a policy you have to take on faith.

> **Verify, do not trust:** Because the SeaShell binary runs on your machine and SeaShell Cloud is contract-driven, you can inspect exactly what leaves your machine. Keep provider keys, MCP servers, and plugins aligned with the privacy policy you promise clients.

## Deployment boundaries

Treat the model route, SeaShell operating mode, MCP servers, plugins, provider keys, and local services as one data-flow decision. A local model alone does not make every configured integration local.

| Item | Detail |
| --- | --- |
| Local and offline | Use a local model endpoint plus seashell --offline or ATLAS_OFFLINE=1 to block other outbound SeaShell traffic. |
| Private endpoint | Use an approved OpenAI-compatible endpoint with the organization's network, identity, logging, and retention controls. |
| Hosted provider | Treat the selected provider as an external data boundary and review its contract and data policy. |

> **Do not infer the boundary:** Document the exact endpoint and enabled integrations for each regulated deployment. The public security page records current product facts and current assurance gaps.

## Security review checklist

- Record whether SeaShell will run offline, against a private endpoint, or against a hosted provider.
- List every MCP server, plugin, credential, local service, and network destination enabled for the workflow.
- Choose allow, ask, and deny rules that match the repository and user role.
- Confirm telemetry and update behavior for the selected operating mode.
- Decide whether any Syntora-operated service will receive, maintain, or transmit PHI before discussing a BAA.
- Review the current assurance status instead of assuming a certification from a product feature.

Use the [Security and Trust page](https://seashell.sh/security), [integration evidence](https://seashell.sh/integrations), and [machine-readable security record](https://seashell.sh/security.json) as the starting packet.

## Slash commands

Open the command palette with `ctrl` `p`, or type a slash command directly into the prompt.

| Command | Description |
| --- | --- |
| `/models` | Switch model, provider, variant, or reasoning mode |
| `/agents` | Choose a primary agent or specialized subagent |
| `/workflow` | Open repeatable workflows for review, refactor, and multi-agent work |
| `/review` | Review uncommitted changes, branches, PRs, or delivery state |
| `/mcps` | Inspect configured Model Context Protocol servers |
| `/sessions` | Resume, fork, or continue previous sessions |
| `/themes` | Switch SeaShell themes |
| `/copy-as-slack` | Copy the last assistant message as Slack-ready mrkdwn |
| `/copy-as-gmail` | Copy the last assistant message as email-ready text |
| `/help` | Open the in-app help surface |

## CLI commands

Use CLI commands for updates, scripting, model inspection, server modes, and managing agents or MCP servers. Every command, flag, and default is listed in [the full CLI reference](https://seashell.sh/cli-reference.md).

| Command | Description |
| --- | --- |
| `seashell` | Start the TUI in the current directory |
| `seashell signup` | Create or sign in to a free SeaShell account with a six-digit email code |
| `seashell upgrade` | Update SeaShell to the latest or a specific version |
| `seashell models [provider]` | List available models from configured providers |
| `seashell providers` | Manage provider credentials and authentication |
| `seashell mcp` | Add, list, authenticate, debug, and remove MCP servers |
| `seashell agent` | Create and list reusable SeaShell agents |
| `seashell run [message]` | Run SeaShell non-interactively for scripts and automation |
| `seashell session` | List, resume, fork, export, or delete sessions |
| `seashell serve` | Start a headless SeaShell server |
| `seashell web` | Start the server and open the web interface |

## Keybindings

SeaShell is keyboard-first. The essentials:

| Keys | Action |
| --- | --- |
| `tab` | Move between prompt, agents, and command surfaces |
| `ctrl p` | Open the command palette |
| `enter` | Submit the current prompt |
| `esc` | Cancel the current interaction or close a dialog |
| `ctrl c` | Quit SeaShell |

## Themes

SeaShell ships with its own dark terminal theme and can load custom JSON themes from your SeaShell config directory. Use `/themes` to switch from the TUI.

custom theme:
```json
{
  "name": "midnight",
  "theme": {
    "primary": "#6aa6f5",
    "background": "#0c0c0c",
    "text": "#e6e9ee"
  }
}
```

## Troubleshooting

#### The `seashell` command is not found

Restart your shell so the updated PATH takes effect, or re-run the install script. On Windows, reopen PowerShell or Windows Terminal.

#### SeaShell says it is already installed

Use `seashell upgrade`. If you built SeaShell from source, pull the repo, rebuild the package, and make sure your PATH points at the rebuilt binary.

#### A model is missing

Run `seashell models --refresh`. For local models, confirm the model exists with `ollama list` and that Ollama is running.

> **Still stuck?:** Email [contact@seashell.sh](mailto:contact@seashell.sh) and we will help.

## Full CLI reference

Every command, subcommand, flag, type, and default: https://seashell.sh/cli-reference.md

---

Canonical HTML: https://seashell.sh/docs
Source of truth: src/content/docs.ts (this file is generated from it, never hand-edited).
Licence: SeaShell is proprietary with a free core. It is not open source and there is no public source repository.