Shipyard Neo

Shipyard Neo Sandbox MCP Tools

Shipyard Neo provides isolated sandbox environments for executing Python, Shell, browser automation, and file operations through MCP tools. All MCP tools are prefixed with mcp--shipyard___neo--.

Architecture Overview

A sandbox's container topology depends on the profile used to create it. Call list_profiles to discover available profiles and their container layout.

Single-Container Profile (e.g., python-default)

Only a Ship container — supports Python, Shell, and Filesystem operations. No browser capability.

Multi-Container Profile (e.g., browser-python)

┌──────────────────────────────────────────────────────────────┐
│                        Sandbox                               │
│  ┌──────────────────┐      ┌──────────────────┐              │
│  │  Ship Container   │      │  Gull Container   │             │
│  │  (code execution) │      │ (browser automat.)│             │
│  │  Python, Shell,   │      │  agent-browser    │             │
│  │  Filesystem       │      │  Chromium headless│             │
│  └────────┬──────────┘      └────────┬──────────┘             │
│           └──────────┬───────────────┘                        │
│           ┌──────────┴──────────┐                             │
│           │   Cargo Volume      │                             │
│           │   /workspace        │                             │
│           └─────────────────────┘                             │
└──────────────────────────────────────────────────────────────┘

Container Isolation Rules

Critical rules:

• Never run agent-browser commands in execute_shell — Ship container does not have agent-browser installed
• Never prefix execute_browser commands with agent-browser — Gull auto-injects it; duplicating causes agent-browser agent-browser ... error
• Both containers share the Cargo Volume at /workspace

Cross-Container Data Sharing

Both containers exchange files through the shared /workspace volume:

# Browser screenshot → Python processing
execute_browser(cmd="screenshot /workspace/page.png")  → Gull writes file
read_file(path="page.png")                             → Ship reads file
execute_python(code="from PIL import Image; img = Image.open('page.png')")

# Python generates data → Browser uses it
execute_python(code="with open('data.json', 'w') as f: json.dump(data, f)")
execute_browser(cmd="open file:///workspace/report.html")

Ship Container Pre-installed Environment

Ship container is based on python:3.13-slim-bookworm with rich pre-installed tools. See references/sandbox-environment.md for details.

Language Runtimes

Pre-installed Python Libraries

System Tools

git, curl, vim-tiny, nano, less, htop, procps, sudo

Environment Variables

Profile-level environment variables can be configured in Bay's config.yaml and are automatically injected into sandboxes:

profiles:
  - id: python-default
    image: "ship:latest"
    env:
      API_KEY: "secret-key-12345"
      DEBUG_MODE: "true"

These environment variables are:

• Available in Shell commands (via /workspace/.bay_env.sh)
• Available in Python code (via os.environ)
• Persist for the lifetime of the sandbox

Accessing in Python:

import os
api_key = os.environ.get("API_KEY")

Accessing in Shell:

echo $API_KEY

Core Workflows

1. Sandbox Lifecycle

list_profiles → create_sandbox → [operations] → delete_sandbox

1. Call list_profiles to discover available profiles (e.g., python-default for Ship only, browser-python for Ship + Gull)
2. Call create_sandbox to create a sandbox and obtain sandbox_id
3. Use sandbox_id for all subsequent operations
4. Call delete_sandbox when finished to release resources

2. Code Execution

Python (via IPython — variables persist across calls):

# First call
execute_python(sandbox_id="xxx", code="import pandas as pd; df = pd.read_csv('data.csv')")

# Subsequent call can use df directly — variables persist within the same sandbox
execute_python(sandbox_id="xxx", code="print(df.describe())")

Shell:

execute_shell(sandbox_id="xxx", command="ls -la", cwd="src")
execute_shell(sandbox_id="xxx", command="npm install && npm run build")
execute_shell(sandbox_id="xxx", command="git init && git add .")

3. File Operations

All sandbox paths are relative to /workspace:

# Text file operations (content passed through MCP protocol)
write_file(sandbox_id="xxx", path="src/main.py", content="print('hello')")
read_file(sandbox_id="xxx", path="src/main.py")
list_files(sandbox_id="xxx", path="src")
delete_file(sandbox_id="xxx", path="src/temp.py")

# Binary/local file transfer (reads/writes actual files on the MCP server's filesystem)
upload_file(sandbox_id="xxx", local_path="/path/to/data.csv", sandbox_path="data/input.csv")
download_file(sandbox_id="xxx", sandbox_path="output/result.png", local_path="./result.png")

When to use upload_file/download_file vs write_file/read_file:

4. Browser Automation

Browser commands execute in the Gull container. Do NOT add the agent-browser prefix.

Operational model (do this to avoid flaky runs):

• Treat cmd as a single command line split into args and executed directly (not a shell script).
• Orchestrate branching/loops in the agent logic, not inside cmd.
• Always follow the cadence: Navigate → Snapshot → Interact → Wait → Re-snapshot.

Standard workflow:

1. execute_browser(cmd="open https://example.com") — Navigate
2. execute_browser(cmd="wait --load networkidle") — Stabilize (optional but recommended)
3. execute_browser(cmd="snapshot -i") — Get interactive element refs (@e1, @e2, ...)
4. Analyze snapshot output to determine next action
5. execute_browser(cmd="click ..." | "fill ..." | "select ...") — Interact using refs
6. If the DOM may have changed, run execute_browser(cmd="snapshot -i") again before further interactions

When to use single vs batch:

Read skills/shipyard-neo/references/browser.md for the detailed command reference, patterns, and artifact handling.

5. Execution History

Track and retrieve past executions for debugging, auditing, or skill creation:

• get_execution_history — Query with filters (exec_type, success_only, tags, limit)
• get_execution — Get full details of one execution by ID
• get_last_execution — Get the most recent execution
• annotate_execution — Add/update description, tags, notes

6. Skill Self-Update Lifecycle

Turn proven execution patterns into reusable, versioned skills.

This mechanism separates evidence from release decisions: execution history records what actually happened, while candidate/evaluation/release records what should be reused. Use optional metadata fields (summary, usage_notes, preconditions, postconditions, upgrade_reason, change_summary) to make each iteration explainable and auditable.

1. Execute tasks → collect execution_ids
2. annotate_execution — Tag and describe executions
3. create_skill_candidate — Bundle execution IDs into a candidate; optionally include summary, usage_notes, preconditions, postconditions for explainable skill metadata
4. evaluate_skill_candidate — Record evaluation results (pass/fail, score, report)
5. promote_skill_candidate — Release as canary or stable; optionally include upgrade_of_release_id, upgrade_reason, change_summary for upgrade traceability
6. rollback_skill_release — Revert to previous version if needed
7. delete_skill_release / delete_skill_candidate — Soft-delete stale records (release deletion is allowed even when active and will make it inactive+deleted; candidate referenced by active release still cannot be deleted)

See references/skills-lifecycle.md for the complete workflow, including optional metadata fields for candidate creation and release promotion.

When creating/using self-iteration skills, apply these payload/replay rules:

• Payload created via create_skill_payload must be a JSON object or array (top-level scalar values are invalid).
• Use payload_ref (blob:...) as reusable external payload storage.
• Browser skill replay is supported via /{sandbox_id}/browser/skills/{skill_key}/run and replays commands from candidate payload.
• For browser replay, candidate payload must be a JSON object with non-empty commands array.
• Python/Shell currently do not have release-based skill replay endpoints (run_*_skill); only direct execution APIs are available.

Key Constraints

Deep-Dive Documentation