Update to SHIP

{
  "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\".",
  "included_files": [],
  "name": "ship-sandboxes",
  "skill_md_contents": "---\nname: ship-sandboxes\ndescription: 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\".\n---\n\n# Manage the sandboxes that agents run in\n\nEvery SHIP agent runs in a sandbox. The platform base has what the agents need to run. A custom sandbox adds\nsteps to that base, for the runtimes and tools that a repository needs. Each change to a sandbox is a new version, and\nmissions start from the active version.\n\nThis skill needs the `ship` CLI and a `SHIP_API_TOKEN`. If you do not have them, do the setup at\n<https://letsship.ai/SKILL.md> first. If this file has no `version` in its frontmatter, you read the hosted copy, so do\nthe setup too. If its `version` is older than `ship --version`, run `ship init --force`.\n\n| Command | Token scope |\n| --- | --- |\n| `ship sandbox list`, `ship sandbox starters`, `ship sandbox versions`, `ship sandbox logs` | `agents:read` |\n| `ship sandbox create`, `ship sandbox update`, `ship sandbox build`, `ship sandbox rollback`, `ship sandbox delete` | `agents:read` and `agents:write` |\n| `ship sandbox default` | `projects:admin` |\n| `ship sandbox registry list` | `connectors:read` |\n| `ship sandbox registry set`, `ship sandbox registry remove` | `connectors:write` |\n| `ship sandbox capacity` | `sandboxes:read` |\n\nChanges also need the admin or owner role in the organization. A token never has more access than the person who\ncreated it.\n\n## See the sandboxes and starters\n\n```bash\nship sandbox list\nship sandbox starters\n```\n\nThe `ship sandbox list` command shows each custom sandbox with its active version, its size and whether its last build\nis ready. The `ship sandbox starters` command shows the starter definitions for Python, Java, Go, Rust and Ruby. Each\nstarter has a size that fits it.\n\n## Create a sandbox\n\n```bash\nship sandbox create --name python-uv --starter python --wait\nship sandbox create --name ml --file ml.Dockerfile --size 2x8192x16000\n```\n\nThe Dockerfile has steps only: `RUN`, `ENV`, `ARG` and `WORKDIR`. The platform supplies the base, so the file has no\n`FROM`. There is also no build context, so `COPY` cannot work. The first build starts immediately. With `--wait`, the\ncommand shows the build log until the build finishes, and exits 7 with the reason if the build fails.\n\n`--size` is `standard-1` to `standard-4`, or a custom `<vcpu>x<memoryMib>x<diskMb>`. A custom size has 1 to 4 vCPU and\n8000 to 20000 MB of disk. Its memory is at least 3072 MiB for each vCPU, and at most 12288 MiB.\n\n## Change, build and roll back\n\n```bash\nship sandbox update python-uv --file sandbox.Dockerfile --wait\nship sandbox update sbt_1a2b --size standard-4\nship sandbox build python-uv --wait\nship sandbox logs python-uv --follow\nship sandbox logs sbt_1a2b --build tbd_9f8e\nship sandbox versions python-uv\nship sandbox rollback python-uv --to 2\n```\n\nA new definition or size becomes the next version. SHIP makes that version active and builds it. A mission that starts\nbefore the build finishes waits for it, and if the build fails, the mission stops with the reason. A new `--name` alone\ndoes not start a build. A sandbox argument can be the id or the name.\n\nThe `ship sandbox build` command builds the active version now. If a build is already in progress, the command returns\nthat build. The `ship sandbox logs` command prints the log of the last build, or of the build that `--build` names. The\n`--follow` flag shows the log until the build finishes.\n\nYou cannot change a version, but the `ship sandbox rollback` command makes an earlier version active. If\nthe snapshot of that version still exists, the rollback is instant. If not, SHIP builds the version again.\n\n## Choose the sandbox of a project\n\n```bash\nship sandbox default python-uv --project prj_123\nship sandbox default none\n```\n\nThis sets the default sandbox of the project. Three settings have priority over it: `agents.<role>.sandbox` in\n`ship.yml`, a `.ship/sandbox.Dockerfile` in the repository, and the `--sandbox` flag of one hand-off (see the\n`ship-delegate` skill). The value `none` sets the project back to the platform base.\n\n## Delete a sandbox\n\n```bash\nship sandbox delete python-uv\n```\n\nSHIP refuses to delete a sandbox that a project uses as its default. If a `ship.yml` entry still names the sandbox, the\ndispatch of that role fails, and the error names the sandbox. Change that entry before you delete the sandbox.\n\n## Connect a private package registry\n\n```bash\nship sandbox registry set --host npm.pkg.github.com --token-file gh.txt\nship sandbox registry set --host acme.io --username ci --password-file pw\nship sandbox registry list\nship sandbox registry remove npm.pkg.github.com\n```\n\nSHIP adds the credential to the requests to that host when they leave the sandbox. The credential never enters the\nsandbox, its build log or its snapshot. Give a bearer token with `--token-file`, or a user name with `--username` and\n`--password-file`. Give secrets as files, so that they stay out of the shell history.\n\n## Read the agent capacity\n\n```bash\nship sandbox capacity\n```\n\nYour organization can run as many agents at the same time as its plan allows. If a new agent would go over that number,\nits mission waits until one of your agents finishes. A mission can also wait when all agent slots on the platform are in\nuse. Use this command when the user asks why a mission waits.\n\n## Exit codes\n\nEvery command also takes `--json`, which prints the raw API response.\n\n| Exit code | Meaning | What to do |\n| --- | --- | --- |\n| 2 | The arguments are wrong. The message names the problem. | Fix the command. |\n| 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. |\n| 4 | SHIP found no such sandbox, build or project. | Check the name with `ship sandbox list`, or give `--project <id>`. |\n| 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. |\n| 6 | The organization did not finish the onboarding. | Ask the user to finish it in the console. |\n| 7 | A build that the command waited for failed. The message is its reason. | Fix the Dockerfile, then update the sandbox again. |\n"
}