SHIP

View saved version →

---
name: ship-agent-runs
description: Use when the user wants to read an agent's log, find why a run failed, follow a run live or stop an agent. It reads and controls the agent runs of SHIP missions, and each run is one agent in its own sandbox. List the runs of a mission or of the organization, and read the status, resource use and cost of one run. Read what the agent did from its log, follow one run live until it ends, and stop one run. For example, the user asks "what did the builder do on SHIP-412", "why did the QA run fail" or "show me the agent log". Also use it when the user says "stop that agent", or to find the run that makes a mission slow or expensive.
---

# Read and control agent runs

A mission is the work that SHIP does for one issue. The agents of a mission do that work in runs. A run is one agent
in its own sandbox, for example one Planner run, three Builder runs and one QA run. The id of a run is its sandbox id,
such as `builder-ship-412-3f9c41aa-coding-1`.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship run list`, `ship run get`, `ship run logs`, `ship run watch` | `sandboxes:read` |
| `ship run stop` | `sandboxes:stop` (an org admin's token) |

## When to use it

- The user asks what an agent does now, or what it did.
- You must wait for a run to end before your next step.
- A run failed, and you must find the cause before you send an instruction to the mission.
- A mission costs more or takes longer than the user expects, and you must find the run that is the cause.
- The user asks you to stop one agent.

To read the state of the mission itself, or to send it feedback, use the `ship-missions` skill.

## Find the runs of a mission

```bash
ship status SHIP-412
ship run list --mission SHIP-412
```

`ship status` lists the runs of the mission, oldest first, with the id of each run. The current run has the mark
`(current)`. `ship run list` gives the same runs with their harness and start time, newest first.

You can also find runs across the organization. A list covers every project of the token, unless `--project` names one.
`SHIP_PROJECT_ID` does not narrow a list.

```bash
ship run list --status running
ship run list --mission SHIP-412 --role qa
ship run list --status failed --limit 20 --json
ship run list --status failed --limit 20 --cursor eyJhIjoxfQ
```

When more runs match, the last line gives the `--cursor` for the next page. Give the same filters with it. A status is `running`, `completed`, `stopped`, `failed` or `stale`. A `stopped` run ended on purpose before it finished,
for example because a newer run replaced it. A `stale` run closed without a report, after its time limit. A role is
`planner`, `builder`, `reviewer` or `qa`.

## Read one run

```bash
ship run get builder-ship-412-3f9c41aa-coding-1
```

The command prints the mission and the role of the run, its status, and the reason when a run ended early. It also
prints the harness and the size of the sandbox, the start and end time, and the latest CPU, memory and disk use. The
`session` line is the session of this run, with its outcome and its cost. The `other` line names the sessions of other
runs with the same role. Their cost is not part of the cost of this run.

## Watch a run live

```bash
ship run watch builder-ship-412-3f9c41aa-coding-1
ship run watch qa-ship-412-77d0e2c1-qa-1 --max-seconds 300
ship run watch qa-ship-412-77d0e2c1-qa-1 --since 118
```

The command prints the last events of the agent. Then it prints each new event on one line, for example a thought, a
tool call or an error. It also prints a line when the mission moves to another stage.

When the run ends, the command exits 0 if the run completed, and 7 if it ended in another way. With `--max-seconds`,
the command stops after that time and exits 5 if the run is still active. Its message gives the `--since` value, so
that the next command prints only the events that came after. Use this command to wait for a run, not a loop of
`ship run get` calls.

An agent that uses the SHIP MCP server calls the `watch_agent_run` tool with the id of the run. The call returns when
the run ends, when its mission moves to another stage, or after `maxSeconds` (300 by default, 600 at most). While the
call waits, the server sends each event as a progress notification, if the request has a progress token. The result
has the status of the run, the stage, `ended`, the reason for the return, the last 20 events and a `cursor`. If the run
is still active, call the tool again with `since` set to the cursor.

## Read what the agent did

```bash
ship run logs builder-ship-412-3f9c41aa-coding-1
ship run logs builder-ship-412-3f9c41aa-coding-1 --part system
ship run logs qa-ship-412-77d0e2c1-qa-1 --part prompt
ship run logs builder-ship-412-3f9c41aa-coding-1 --session s-91c2
```

A log has three parts:

| Part | What it has |
| --- | --- |
| `session` (the default) | The event stream of the agent, one JSON event on each line: its thoughts, its tool calls and their results. |
| `system` | The output of the sandbox: the clone, the dependency install, the checks before a push, and git. |
| `prompt` | The text that the repository added to the prompt of the agent, for example from `.ship/agents/<role>.md`. |

The command reads the session of the run itself. To read a session of another run of the same role, name it with
`--session`. The `session` part is long, so filter it before you read it. For example, pipe `--json` output to `jq`, or
search for the error text.

The platform saves the log when the agent ends. While a run is still `running`, the command exits 4 and says so. Read
`ship run get` for its status, and read the log after the run ends. Some old runs did not record their own session. For
such a run, the command also exits 4 and lists the sessions of the role, so that you can name one with `--session`.

## Stop one run

Stop a run only when the user asks for it, because the work in progress of the agent is lost.

```bash
ship run stop builder-ship-412-3f9c41aa-coding-1
```

The status of the run becomes `stopped` a few seconds later. The command stops one run, not the mission. The mission
continues, and it can start a new run for the same stage. To stop the whole mission, use `ship mission stop` from the
`ship-missions` skill.

## Exit codes

Every command also takes `--json`, which prints the raw API response.

| Exit code | Meaning | What to do |
| --- | --- | --- |
| 2 | The arguments are wrong. The message names the problem. | Fix the command. |
| 3 | The token is not set, or it does not have the scope of the command, or it is not an admin's token for `ship run stop`. | Ask the user for a token with the scope. Do not retry. |
| 4 | SHIP found no such run, or the run has no saved log yet. | Check the id with `ship run list`. For a log, wait until the run ends. |
| 5 | `ship run watch` stopped at `--max-seconds`, and the run is still active. | Run the command again with the `--since` value from its message. |
| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |
| 7 | The run that `ship run watch` followed ended, but it did not complete. | Read the reason with `ship run get`, then its log. |

View saved version →

---
name: ship-delegate
description: Use when the user wants to hand a plan, a spec or an open pull request to SHIP. It hands work to the SHIP AI agent team from this repository. Delegate a plan or a spec that you wrote, so SHIP builds it. Delegate a branch with an open pull request, so SHIP runs code review and tests on it and makes it ready to merge. For example, the user says "delegate this", "hand this to SHIP", "let SHIP build this", "let SHIP review this" or "ship this spec". Also use it when the user finishes a plan or a change and asks what to do next.
---

# Hand work to SHIP

Two hand-offs, each one command. SHIP starts a mission for the work, and its agents plan, build, review and test it.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship delegate plan` | `missions:run` |
| `ship delegate pr` | `missions:run` |

## When to use it

- The user wrote a plan or a spec and wants SHIP to build it, not you.
- The user finished code on a branch and wants SHIP to review it, test it and make it ready to merge.

Do not delegate work that you are in the middle of, unless the user asks. Finish or stop first, so that the hand-off
has a complete plan or a complete branch. To read the state of a mission or to send it feedback after the hand-off,
use the `ship-missions` skill.

## Hand over a plan

Write the plan to a file first, then delegate it. SHIP skips its own Planner and builds from your spec as you wrote it.

```bash
# For an issue that already exists
ship delegate plan SHIP-412 --file docs/plan.md

# No issue yet: create one and start the mission in the same call
ship delegate plan --title "Rate-limit the search endpoint" --file docs/plan.md
```

If you know the files that the plan changes, name them with `--file-plan <path.json>`. The file is a JSON array of
`{path, action, description}`. Without it, the Builder chooses the files.

## Hand over a branch

Open the pull request yourself, then delegate it. SHIP never pushes a branch or opens a pull request for you. If the
`gh` CLI is available, the command reads `--pr` from the current branch.

```bash
ship delegate pr SHIP-412              # review, then test, then merge
ship delegate pr SHIP-412 --at qa      # already reviewed: only test it
ship delegate pr                       # no issue: SHIP names the mission after the pull request
```

If CI fails on that pull request, SHIP fixes the failure before the review. That is expected, not an error.

## Choose the harness, model or sandbox for one mission

These flags change how this one mission runs. They take priority over the `ship.yml` of the project and do not change
the file. They apply to the role that the mission starts at: the Builder for `delegate plan`, and the Reviewer or the
QA agent for `delegate pr`.

```bash
ship delegate plan SHIP-412 --file docs/plan.md --harness codex
ship delegate plan SHIP-412 --file docs/plan.md --model opus
ship delegate pr SHIP-412 --at qa --harness open-code --model z-ai/glm-5.2
ship delegate plan SHIP-412 --file docs/plan.md --sandbox python-uv --size standard-2
```

The harnesses are `claude-code`, `codex`, `pi`, `kilo-code` and `open-code`. You can give `--model` without
`--harness`, and the configured harness stays. `--sandbox` names a custom sandbox (see the `ship-sandboxes` skill), and
`--size` sets the machine size for this mission.

Use these flags when the user asks for a specific agent, model or sandbox, or to compare two of them on the same work.
Otherwise, leave them out. The configuration of the project is the setting that the team agreed on.

## The configuration of the project

That configuration is `ship.yml` at the root of the repository. It sets the harness and the model of each role. It
also sets how long the retry loop continues, where a preview environment deploys, and how QA tests a change that has no
preview URL.

The published JSON Schema is the source of truth for its shape:

```
https://letsship.ai/schema/ship.yml.json
```

When you write or change the file, put the modeline on the first line, so that an editor validates the file. Then
validate the file against the schema before you hand anything over:

```yaml
# yaml-language-server: $schema=https://letsship.ai/schema/ship.yml.json
version: 1
deployments: {}
```

`version` and `deployments` are both required. A project that has nothing to preview writes `deployments: {}` and keeps
the key. If the file fails validation, SHIP ignores all of it, and `agents` and `retries` go back to the platform
defaults. The full field reference is at <https://letsship.ai/docs/configuration/schema>.

A change to `ship.yml` is normal work in the repository: a branch and a pull request, or a mission that you delegate.
The flags in this skill never write to the file.

## Give one role extra instructions for one mission

When the user wants this mission built or judged in a different way, send the instructions with the hand-off. Examples
are "review it for security" or "keep the public API stable". Do not put them in the issue text. They apply to the role
that the mission starts at, for this mission only, and SHIP commits nothing to the repository.

```bash
ship delegate pr SHIP-412 --prompt-file security-review.md
ship delegate pr SHIP-412 --prompt-path .ship/lanes/security.md
```

To give the instructions to a different role, add `--prompt-role planner|builder|reviewer|qa`. The `--prompt-file`,
`--prompt-path`, `--prompt-mode` and `--prompt-role` flags also work on `ship mission create` and `ship mission start`,
where the mission starts at the Planner. The delegate commands skip the Planner, so they refuse `--prompt-role planner`.
A restart of a mission with an open pull request also skips the Planner, so name the role with `--prompt-role` there.

```bash
ship mission start SHIP-412 --prompt-file plan-notes.md
ship delegate pr SHIP-412 --prompt-role qa --prompt-file qa-notes.md
```

Write the instructions to a file first, the same way as a plan. `--prompt-path` names a file that is already in the
repository. Add `--prompt-ref` to read that file at a specific git ref.

`--prompt-mode` decides what happens to the own instructions of the repository for that role, in
`.ship/agents/<role>.md`:

| Mode | Effect |
| --- | --- |
| `replace` (default) | Your instructions are the only project instructions for the role. SHIP does not read the file of the repository. |
| `extend` | SHIP reads the file of the repository first and adds your instructions after it. |

```bash
ship delegate pr SHIP-412 --prompt-file security-review.md --prompt-mode extend
```

Use `extend` when you add a concern, such as a security review or one more rule. The `replace` mode drops the
conventions that the repository wrote for the role, and the user almost never wants that. Use `replace` only for a
mission that is a different job from the normal work, or when the user tells you to ignore the file. The SHIP charter
for the role applies in both modes.

## Exit codes

Every command also takes `--json`, which prints the raw API response.

| Exit code | Meaning | What to do |
| --- | --- | --- |
| 2 | The arguments are wrong. The message names the problem. | Fix the command. |
| 3 | The token is not set, or it does not have `missions:run`. | Ask the user for a token with the scope. Do not retry. |
| 4 | SHIP found no such issue or project. | Check the issue id, or give `--project <id>`. |
| 5 | The hand-off needs something that is not true yet, for example a review with no pull request. | Do what the message says, then run the command again. |
| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |

View saved version →

---
name: ship-mcp-servers
description: Use when the user wants the SHIP agents to use an MCP server, or asks which MCP servers the agents can use. It lets the SHIP agents use the MCP servers that this repository declares. Bind a server to agent roles with a credential, approve its tools, start an OAuth sign-in, choose the MCP file or remove a binding. For example, the user says "let the SHIP agents use our GitHub MCP server" or "give the planner Linear access".
---

# Give the agents MCP servers

The SHIP agents can use the MCP servers that the repository declares in its MCP file, which is `.mcp.json` by default.
SHIP never loads that file on its own. A server reaches the agents only through a binding. A binding names the agent
roles that may use the server, the tools that they may call, and the credential that SHIP attaches. The agents never
see the credential.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship mcp list`, `ship mcp bindings` | `connectors:read` |
| `ship mcp tools` without flags | `connectors:read` |
| `ship mcp bind`, `ship mcp connect`, `ship mcp remove`, `ship mcp file` | `connectors:write` |
| `ship mcp tools --refresh`, `ship mcp tools --approve` | `connectors:write` |

Changes also need the admin or owner role in the organization. A token never has more access than the person who
created it.

## See what the repository declares

```bash
ship mcp list --project prj_123
ship mcp bindings
```

`ship mcp list` shows the servers in the MCP file of one project and the binding of each. `ship mcp bindings` shows
every binding in the projects of your organization. Neither command shows a credential value. They show only the names
of the fields that are set.

## Bind a server

`--roles` lists every agent that may use the server: `planner`, `builder`, `reviewer` and `qa`, or `none`. The Reviewer
and the QA agent get only the tools that read, and they cannot use a server that runs inside the sandbox.

```bash
ship mcp bind github --roles planner,qa --header-file Authorization=gh.txt
ship mcp bind sentry --roles qa --env-var-file KEY=t --allow-host sentry.io
ship mcp bind linear --roles planner,builder --no-credential
```

Give credentials as files, so that they stay out of the shell history. Do not put a token in a command line.

- `--header-file <Name=path>`: a request header for a remote server. The file holds the complete value, for example
  `Bearer <token>`. You can give the flag more than one time.
- `--env-var-file <NAME=path>` with `--allow-host <host>`: an environment variable for an isolated server, and the hosts
  that the credential may go to. These flags imply `--transport isolate`.
- `--no-credential`: bind with no credential, and remove a stored one.

Without a credential flag, the binding keeps the credential that it has.

`--transport` is `remote`, `isolate` or `local`. With `remote`, SHIP sends requests to the URL of the server. With
`isolate`, SHIP runs the npm package of the server in isolation, so that the server can hold a secret. With `local`, the
server runs inside the sandbox with no credential. The default is what the declaration of the server allows. `--url`
sets a fixed https URL for the server. Without `--transport` or `--url`, the binding keeps its current server.

## Approve the tools

A new binding gives the agents no tools. Approve them after you bind the server:

```bash
ship mcp tools github --refresh
ship mcp tools github --approve get_issue,get_file --attest get_file
```

Without flags, the command prints the last tool list of the server, with the approval of each tool and whether it only
reads. The `--refresh` flag gets the current list from the server first. The `--approve` flag replaces the approved set
with the tools that you name. A tool that has no annotation from the server goes to the Reviewer and the QA agent only if you also
name it in `--attest`. With `--attest`, you confirm that the tool only reads. Name only the tools that the task needs.

## Sign in to a server that uses OAuth

```bash
ship mcp connect linear --project prj_123
```

The command prints a link. A person opens it in a browser where they are signed in to the SHIP console. The provider
then sends them back to the console, which stores the credential. You cannot complete this step for the user. Give the
user the link. The link works one time and expires.

## Remove a binding or change the MCP file

```bash
ship mcp remove notion --project prj_123
ship mcp file .cursor/mcp.json --project prj_123
ship mcp file default
```

`ship mcp remove` deletes the binding and its stored credential. From their next run, the agents do not get the server.
The command does not change the MCP file of the repository.

`ship mcp file` sets the file that declares the servers of the project, for example `.cursor/mcp.json`. The value
`default` sets it back to `.mcp.json`. SHIP refuses the command while the `ship.yml` of the repository sets
`mcp.config`, because that setting has priority.

## Exit codes

Every command also takes `--json`, which prints the raw API response.

| Exit code | Meaning | What to do |
| --- | --- | --- |
| 2 | The arguments are wrong. The message names the problem. | Fix the command. |
| 3 | The token is not set, or it does not have the scope of the command, or the role cannot change it. | Ask the user for a token with the scope, from an admin. Do not retry. |
| 4 | SHIP found no such server, binding or project. | Check the server name with `ship mcp list`, or give `--project <id>`. |
| 5 | The change needs something that is not true yet. | Do what the message says, then run the command again. |
| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |

View saved version →

---
name: ship-missions
description: Use when the user wants to follow a SHIP mission, check its status, or pass it feedback, review comments or a decision while it runs. It follows, controls and finishes the SHIP missions that you or the user started. List missions, read the state of one, and send it instructions or feedback. Pause, resume, stop, restart, merge or decline a mission, approve a checkpoint or a credit limit, and read its preview, proof and credits. For example, the user asks "what is the status of SHIP-412", "is SHIP done with it" or "tell SHIP to change X". Also use it when the user says "pause that mission" or "merge it", or asks for a change in one line.
---

# Follow and steer a mission

A mission is the work that SHIP does for one issue. Use this skill after a hand-off (see the `ship-delegate` skill), to
read the state of a mission, to send it new information and to finish it. To read what one agent did inside a mission,
use the `ship-agent-runs` skill.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship status`, `ship mission list` | `missions:read` |
| `ship instruct`, `ship mission pause`, `ship mission resume`, `ship mission stop` | `missions:write` |
| `ship mission merge`, `ship mission decline`, `ship mission auto-merge` | `missions:write` |
| `ship mission archive`, `ship mission unarchive`, `ship mission disposition` | `missions:write` |
| `ship mission create`, `ship mission start`, `ship mission approve-ceiling` | `missions:run` |
| `ship mission override get` | `agents:read` |
| `ship mission override set` | `agents:read` and `agents:write` |
| `ship mission override clear` | `agents:write` |
| `ship mission inspect` | `inspect:read` |
| `ship preview list`, `ship preview get` | `environments:read` |
| `ship preview destroy` | `environments:write` |
| `ship artifact list`, `ship artifact get` | `artifacts:read` |
| `ship credits`, `ship credits offers`, `ship credits request`, `ship setup`, `ship notice list`, `ship notice dismiss` | any token |
| `ship credits ledger`, `ship credits buy`, `ship credits plan` | any token, with an owner or admin behind it |

The controls also need a role in the organization that can control missions. Archive and disposition need an owner or
an admin. Without `--project`, the override commands read the project from the mission, so the token also needs
`missions:read`. A token never has more access than the person who created it.

## See the missions

```bash
ship mission list
ship mission list --activity needs_attention
ship mission list --search "rate limit" --json
ship mission list --project prj_123 --offset 25
```

The list shows each mission with what it does now, its stage and its pull request. The `--activity` flag takes the
values of the status filter in the console, for example `building`, `reviewing`, `testing`, `ready_to_merge`,
`needs_attention` or `paused`. The list covers every project of the token, unless `--project` names one.
`SHIP_PROJECT_ID` does not narrow a list. When more missions match, the last line gives the `--offset` of the next
page.

## Read the state of a mission

```bash
ship status SHIP-412
ship status SHIP-412 --json    # for jq
```

The command prints the stage of the mission, its review state, its test state and its pull request. It also lists the
agent runs of the mission, and the run whose artifacts are the proof of the work. Read it before you tell the user that
work is complete.

## Start a mission from a request

When the user asks for a change in one line and there is no plan or branch yet, let SHIP plan it:

```bash
ship mission create --title "Fix the login redirect" --description "- [ ] Login returns to the page it came from"
ship mission start SHIP-412 --project prj_123
```

`ship mission create` files the issue and starts the mission at the Planner. Write the acceptance criteria as
checkboxes, because the QA agent tests against them. `ship mission start` starts a mission on an issue that is already
in the tracker. When the user has a plan or a branch, use the `ship-delegate` skill instead.

## Send feedback to a mission

When the user decides something about work that SHIP already has, send it as an instruction. Examples are an answer to
a question from the agents, review comments, or a correction to a choice that an agent made. The instruction goes to
the agents and starts the Builder on the open pull request of the mission.

```bash
ship instruct SHIP-412 -m "Keep the current Node range. Override nopt instead."
ship instruct SHIP-412 --file review-notes.md
ship instruct SHIP-412 -m "FYI staging is down until 14:00" --note
```

`--note` records context for the next agent and starts no work. Use it for background information. Leave it out for
anything that you want the agents to act on.

Use an instruction, not a new hand-off or a restart. A restart checks the same pull request against the review and test
results that it already has. It finds no change and correctly does nothing, so the feedback goes nowhere. An instruction
is the channel for new information.

The reply tells you what SHIP recorded and what it starts:

```
SHIP-412  instruction recorded (ins_9b8e2a3f3c4d)
  mission   ready_to_merge
  dispatch  builder: it will pick this up on the mission's open pull request
```

When SHIP starts no work, the reply says why and what to do instead. An example is a pull request that is already
merged: the remedy is a new mission, not feedback to a finished one. Read that line before you report back. Do not tell
the user that an instruction arrived until the reply says `recorded`.

## Pause, resume or stop a mission

```bash
ship mission pause SHIP-412
ship mission resume SHIP-412
ship mission stop SHIP-412
```

A pause lets the current stage finish, then holds the mission before its next stage. A resume continues it. A stop ends
every agent of the mission, and their work in progress is lost. The pull request stays open. Pause or stop a mission
only when the user asks for it.

A checkpoint in `ship.yml` pauses a mission after a stage, so that a person can read the result first. `ship status`
then shows `paused yes (checkpoint:<role>)`. When the user approves the result, resume the mission. When the user wants
changes to the result, send an instruction instead.

## Change the agents of one mission

An override changes the harness, the model or another setting of one role, for one mission only. Each field replaces
the same field of `ship.yml`, and the file itself does not change. The next run of that role uses the override.

```bash
ship mission override get SHIP-412
ship mission override set SHIP-412 --role reviewer --harness codex --model gpt-5.5
ship mission override set SHIP-412 --role builder --checkpoint on
ship mission override set SHIP-412 --role qa --prompt-file qa-notes.md --prompt-mode extend
ship mission override set SHIP-412 --role builder --harness codex --unset model
ship mission override clear SHIP-412
```

The action `set` changes only the role that `--role` names, and only the settings that you give. The other roles and
settings of the override stay. The flag `--checkpoint on` pauses the mission after that stage, so that a person reads
the result first. The flag `--reject-on` sets the lowest finding that makes the reviewer ask for changes. The flag
`--base-branch` sets the branch that the mission starts from. The flag `--unset` removes stored fields, for example the
model when you change the harness, and the action `clear` removes the whole override.

Change an override only when the user asks for it, because a different model can change the cost of the mission.
Without `--project`, the command reads the project from the mission. The variable `SHIP_PROJECT_ID` does not apply to
an override, because an override saved for the wrong project changes no run.

## Auto-merge, archive and disposition

```bash
ship mission auto-merge SHIP-412 on
ship mission auto-merge SHIP-412 off
ship mission archive SHIP-412
ship mission unarchive SHIP-412
ship mission disposition SHIP-412 superseded --superseded-by SHIP-420
```

With auto-merge on, SHIP merges the pull request of the mission when the checks, the review and the test pass, and no
person merges it. For this mission, the setting replaces the auto-merge of the project. Turn it on only when the user
asks for it.

An archived mission is not on the board and not in `ship mission list`. The disposition records why a mission ended,
for the delivery statistics: `product`, `probe`, `superseded`, `takeover`, or `none` to clear it. Record only what
the user decided, never your own guess.

## Restart a mission

A mission that stopped, failed or needs attention does not start again on its own. When the user asks for a new
attempt, start it again:

```bash
ship mission start SHIP-412 --project prj_123
```

Read `ship mission inspect` first if you must find why the last attempt failed. It needs the `inspect:read` scope.

```bash
ship mission inspect SHIP-412 --sections taskState,retryReason
```

## Let a mission continue past its credit limit

Each mission can use a fixed number of credits. At that limit, the mission pauses until a member lets it continue.
`ship status` and `ship notice list` show it. When the user agrees to the extra cost, run:

```bash
ship mission approve-ceiling SHIP-412 --project prj_123
```

The command raises the limit of the mission by one step, and the stage that stopped runs again. Without `--project` or
`SHIP_PROJECT_ID`, the command reads the project from the mission, so the token also needs `missions:read`. Check the balance
with `ship credits` before and after work:

```bash
ship credits
ship notice list
ship notice dismiss credits_low:grant_123
```

The notices show what needs attention in the organization, such as a tracker to connect again or credits that run low.
You can close a warning with `ship notice dismiss`. A critical notice stays until someone fixes its cause.

## Credits

```bash
ship credits ledger
ship credits ledger --limit 100 --cursor eyJhIjoxfQ
ship credits offers
ship credits request -m "Two more missions for the release this week"
```

The ledger shows where the credits went, newest first: each mission and the credits that it used, each grant, each
adjustment and each expiry. When more entries exist, the last line gives the `--cursor` for the next page. The offers
are the credit packs, the monthly plans and Enterprise, with their prices. A credit request goes to SHIP or to the
owners and admins of the organization, and the reply says which.

Buy credits or change the plan only when the user asks you to:

```bash
ship credits buy credit_pack_50 --start-now
ship credits buy team --plan starter --start-now
ship credits plan scale
ship credits plan --cancel
```

The command `ship credits buy` prints the address of a payment page and charges nothing. Give that address to the user,
who pays there. Without `--start-now`, the command shows the text of the consent to start the credits at once, and
stops. Show that text to the user, and add `--start-now` only when the user agrees to it. The command
`ship credits plan` changes the monthly plan from the next renewal. With `--cancel`, the plan ends at the end of the
month that the user paid for.

## Check the preview and the proof

```bash
ship preview list --mission SHIP-412
ship artifact list --mission SHIP-412
ship artifact list --run qa-ship-412-77d0e2c1-qa-1
```

SHIP deploys a preview of the pull request through the delivery pipeline of the repository, and the QA agent tests it.
The proof of a mission is the artifacts of the QA run that passed: traces, screenshots, videos and logs. The command
`ship status` names that run, so give its id to `--run`. Each artifact has a link that opens it. Give these links to the
user when they ask for evidence.

`ship preview destroy` removes a preview before it expires. Use it only when the user asks for it.

## Merge or decline the pull request

```bash
ship mission merge SHIP-412
ship mission decline SHIP-412
```

Merge or decline only when the user tells you to. The merge uses the merge method of the repository, and then the
mission becomes done. If the pull request cannot merge, the command exits 5 with the reason. On a merge conflict, SHIP
also starts the Builder to fix the conflict, and it merges the pull request when the mission is ready again. Do not
merge again, and tell the user that the Builder works on the conflict. The decline closes the pull request without a
merge, and you cannot undo it.

## Exit codes

Every command also takes `--json`, which prints the raw API response.

| Exit code | Meaning | What to do |
| --- | --- | --- |
| 2 | The arguments are wrong. The message names the problem. | Fix the command. |
| 3 | The token is not set, or it does not have the scope of the command, or the role cannot do it. | Ask the user for a token with the scope. Do not retry. |
| 4 | SHIP found no such mission, project, preview or artifact. | Check the issue id or the other id, or give `--project <id>`. |
| 5 | The mission is not in a state that allows the action, or the organization has no credits. | Read the message, then `ship status`. Do what the message says. |
| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |
| 8 | Too many requests, or the organization reached a daily limit. | Wait, then run the command again. Tell the user about a daily limit. |

View saved version →

---
name: ship-sandboxes
description: Use when the SHIP agents need a runtime or a tool that is not in their sandbox, or a mission waits for an agent slot. It manages the sandboxes that the SHIP agents run in. Add runtimes and tools to a custom sandbox, build it, read its build log and roll it back. Make a sandbox the default of a project, and connect private package registries. Also read how many agents your missions run at the same time. For example, the user says "the agents need Python", "add a JDK to the SHIP sandbox" or "why does my mission wait".
---

# Manage the sandboxes that agents run in

Every SHIP agent runs in a sandbox. The platform base has what the agents need to run. A custom sandbox adds
steps to that base, for the runtimes and tools that a repository needs. Each change to a sandbox is a new version, and
missions start from the active version.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship sandbox list`, `ship sandbox starters`, `ship sandbox versions`, `ship sandbox logs` | `agents:read` |
| `ship sandbox create`, `ship sandbox update`, `ship sandbox build`, `ship sandbox rollback`, `ship sandbox delete` | `agents:read` and `agents:write` |
| `ship sandbox default` | `projects:admin` |
| `ship sandbox registry list` | `connectors:read` |
| `ship sandbox registry set`, `ship sandbox registry remove` | `connectors:write` |
| `ship sandbox capacity` | `sandboxes:read` |

Changes also need the admin or owner role in the organization. A token never has more access than the person who
created it.

## See the sandboxes and starters

```bash
ship sandbox list
ship sandbox starters
```

The `ship sandbox list` command shows each custom sandbox with its active version, its size and whether its last build
is ready. The `ship sandbox starters` command shows the starter definitions for Python, Java, Go, Rust and Ruby. Each
starter has a size that fits it.

## Create a sandbox

```bash
ship sandbox create --name python-uv --starter python --wait
ship sandbox create --name ml --file ml.Dockerfile --size 2x8192x16000
```

The Dockerfile has steps only: `RUN`, `ENV`, `ARG` and `WORKDIR`. The platform supplies the base, so the file has no
`FROM`. There is also no build context, so `COPY` cannot work. The first build starts immediately. With `--wait`, the
command shows the build log until the build finishes, and exits 7 with the reason if the build fails.

`--size` is `standard-1` to `standard-4`, or a custom `<vcpu>x<memoryMib>x<diskMb>`. A custom size has 1 to 4 vCPU and
8000 to 20000 MB of disk. Its memory is at least 3072 MiB for each vCPU, and at most 12288 MiB.

## Change, build and roll back

```bash
ship sandbox update python-uv --file sandbox.Dockerfile --wait
ship sandbox update sbt_1a2b --size standard-4
ship sandbox build python-uv --wait
ship sandbox logs python-uv --follow
ship sandbox logs sbt_1a2b --build tbd_9f8e
ship sandbox versions python-uv
ship sandbox rollback python-uv --to 2
```

A new definition or size becomes the next version. SHIP makes that version active and builds it. A mission that starts
before the build finishes waits for it, and if the build fails, the mission stops with the reason. A new `--name` alone
does not start a build. A sandbox argument can be the id or the name.

The `ship sandbox build` command builds the active version now. If a build is already in progress, the command returns
that build. The `ship sandbox logs` command prints the log of the last build, or of the build that `--build` names. The
`--follow` flag shows the log until the build finishes.

You cannot change a version, but the `ship sandbox rollback` command makes an earlier version active. If
the snapshot of that version still exists, the rollback is instant. If not, SHIP builds the version again.

## Choose the sandbox of a project

```bash
ship sandbox default python-uv --project prj_123
ship sandbox default none
```

This sets the default sandbox of the project. Three settings have priority over it: `agents.<role>.sandbox` in
`ship.yml`, a `.ship/sandbox.Dockerfile` in the repository, and the `--sandbox` flag of one hand-off (see the
`ship-delegate` skill). The value `none` sets the project back to the platform base.

## Delete a sandbox

```bash
ship sandbox delete python-uv
```

SHIP refuses to delete a sandbox that a project uses as its default. If a `ship.yml` entry still names the sandbox, the
dispatch of that role fails, and the error names the sandbox. Change that entry before you delete the sandbox.

## Connect a private package registry

```bash
ship sandbox registry set --host npm.pkg.github.com --token-file gh.txt
ship sandbox registry set --host acme.io --username ci --password-file pw
ship sandbox registry list
ship sandbox registry remove npm.pkg.github.com
```

SHIP adds the credential to the requests to that host when they leave the sandbox. The credential never enters the
sandbox, its build log or its snapshot. Give a bearer token with `--token-file`, or a user name with `--username` and
`--password-file`. Give secrets as files, so that they stay out of the shell history.

## Read the agent capacity

```bash
ship sandbox capacity
```

Your organization can run as many agents at the same time as its plan allows. If a new agent would go over that number,
its mission waits until one of your agents finishes. A mission can also wait when all agent slots on the platform are in
use. Use this command when the user asks why a mission waits.

## Exit codes

Every command also takes `--json`, which prints the raw API response.

| Exit code | Meaning | What to do |
| --- | --- | --- |
| 2 | The arguments are wrong. The message names the problem. | Fix the command. |
| 3 | The token is not set, or it does not have the scope of the command, or the role cannot change it. | Ask the user for a token with the scope, from an admin. Do not retry. |
| 4 | SHIP found no such sandbox, build or project. | Check the name with `ship sandbox list`, or give `--project <id>`. |
| 5 | The change needs something that is not true yet, for example a delete of a project default. | Do what the message says, then run the command again. |
| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |
| 7 | A build that the command waited for failed. The message is its reason. | Fix the Dockerfile, then update the sandbox again. |

View saved version →

---
name: ship-scheduled-tasks
description: Use when the user wants to schedule a task that SHIP runs every day, week or month, such as a dependency update. It runs SHIP missions on a schedule. Create a scheduled task from a prompt or a template, change its schedule or prompt, or turn it off and on. Run it now, read what its past runs did and cost, and delete it. For example, the user says "every Monday, have SHIP update our dependencies" or "run a flaky test sweep each week". Also use it when the user asks what the last scheduled run did, or which scheduled tasks a project has.
---

# Run missions on a schedule

A scheduled task is a prompt with a cadence. At each run, SHIP files an issue with the prompt as its description, and a
normal mission starts on it. The board, the review, the tests and the proof of that mission are the same as for any
other mission.

This skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at
<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do
the setup too. If its `version` is older than `ship --version`, run `ship init --force`.

| Command | Token scope |
| --- | --- |
| `ship schedule list`, `ship schedule get`, `ship schedule runs`, `ship schedule templates` | `scheduled-tasks:read` |
| `ship schedule create`, `ship schedule update`, `ship schedule delete` | `scheduled-tasks:write` |
| `ship schedule run` | `missions:run` |

Changes also need the admin or owner role in the organization. Each run uses credits, like any mission.

## See the scheduled tasks

```bash
ship schedule list
ship schedule list --project prj_123
ship schedule get aut_123
ship schedule templates
```

`ship schedule list` shows each task with its cadence and its next run. With `--project`, it lists the tasks of one
project. `ship schedule get` also prints the prompt.
`ship schedule templates` shows prepared prompts, each with a suggested cadence.

## Create a scheduled task

```bash
ship schedule create --name deps --template dependency-upgrades
ship schedule create --name triage --file triage.md --every weekly --day monday --time 09:00 --timezone Europe/Amsterdam
ship schedule create --name report --file report.md --every monthly --day 1 --time 06:00 --timezone UTC
```

The schedule is `--every daily`, `weekly` or `monthly`, with `--time` and `--timezone`. A weekly task also needs `--day`
with a weekday. A monthly task needs `--day` with a day from 1 to 28. With `--template`, the task takes the prompt of the
template, and its suggested schedule unless you give one. With `--file` too, the prompt of the file replaces the prompt
of the template. Give `--project <id>`, or set `SHIP_PROJECT_ID`.

Write the prompt like a good issue:

- Write the acceptance criteria as checkboxes, because the QA agent tests against them.
- Say what an empty result is, for example "if no dependency has an update, change nothing".
- Do not ask the agent to change the CI configuration. Nobody watches a scheduled run, and SHIP blocks that change
  without a person.

While the mission of the last run is still open, SHIP skips the next run. Thus a weekly task cannot open a second pull
request that conflicts with the first.

## Change, stop or delete a scheduled task

```bash
ship schedule update aut_123 --file triage.md
ship schedule update aut_123 --every daily --time 07:30 --timezone UTC
ship schedule update aut_123 --disable
ship schedule update aut_123 --enable
ship schedule delete aut_123
```

Only the values that you give change. To change the schedule, give `--every`, `--time` and `--timezone` together, and
`--day` when the interval needs it. `--disable` stops the runs and keeps the task and its history. Delete a task only
when the user asks for it, because its run history goes with it.

## Run a task now, and read its runs

```bash
ship schedule run aut_123
ship schedule runs aut_123
ship schedule runs aut_123 --limit 20 --cursor eyJhIjoxfQ
```

The command `ship schedule run` starts a mission now, outside the schedule. It also runs when the mission of the last
run is still open. The command `ship schedule runs` lists the past runs, each with its status, its mission and the cost
of that mission. When older runs exist, the last line gives the `--cursor` for the next page. A `dispatched` run filed
its issue, but that does not say whether the work passed. Read the mission
with `ship status` for that.

## Exit codes

Every command also takes `--json`, which prints the raw API response.

| Exit code | Meaning | What to do |
| --- | --- | --- |
| 2 | The arguments are wrong, or the API refused the schedule. The message names the problem. | Fix the command. |
| 3 | The token is not set, or it does not have the scope of the command, or the role cannot change it. | Ask the user for a token with the scope, from an admin. Do not retry. |
| 4 | SHIP found no such scheduled task, template or project. | Check the id with `ship schedule list`, or give `--project <id>`. |
| 5 | The organization has no credits for a run now. | Tell the user. Check the balance with `ship credits`. |
| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |
| 8 | Too many requests, or the organization reached a daily limit. | Wait, then run the command again. Tell the user about a daily limit. |