sandy

name	sandy
description	Run TypeScript scripts in sandboxed microVMs or Docker containers with AWS SDK access via IMDS. Use when investigating AWS resources, running read-only queries, or executing TypeScript automation that needs AWS credentials.

Sandy

Sandy executes TypeScript scripts in disposable sandboxed environments (Shuru microVMs or Docker containers) with AWS credentials from IMDS.

The CLI uses explicit sessions. Create one first, then run scripts from that session’s scripts/ directory.

Setup

Read the scripting guide before writing scripts:

sandy resource sandy://skills/cli/resources/scripting-guide.md

This guide defines runtime constraints, available AWS SDK packages, and the required async generator pattern.

IMDS port

Start an IMDS server separately and pass its port to sandy run and sandy check connect.

CLI commands

sandy image

Create or delete the Sandy sandbox image.

sandy image create
sandy image delete
sandy image delete --force

sandy session create

Create a session and print the session name plus scripts path.

sandy session create

sandy check

Verify sandbox health. Each check creates and deletes an ephemeral session; no session argument is accepted.

sandy check baseline
sandy check connect --imds-port 9001
sandy check connect --imds-port 9001 --region ap-southeast-2

sandy run

Run a TypeScript script from <session>/scripts/.

sandy run --session happy-fox-trail --script inventory.ts --imds-port 9001
sandy run --session happy-fox-trail --script inventory.ts --imds-port 9001 --region ap-southeast-2
sandy run --session happy-fox-trail --script inventory.ts --imds-port 9001 -- arg1 arg2

Options:

Flag	Required	Description
--session	yes	Session name
--script	yes	Script path relative to <session>/scripts/
--imds-port	yes	Port of the running IMDS server
--region	no	AWS region (default us-west-2)
--	no	Arguments passed as process.argv inside the script

Session layout on the host:

• .sandy/<session>/scripts/ mounted read-only at /workspace/scripts
• .sandy/<session>/output/ mounted read-write at /workspace/output

Scripts should write files under process.env.SANDY_OUTPUT.

sandy resource

List or read embedded resources.

sandy resource
sandy resource sandy://skills/cli/resources/scripting-guide.md

sandy prime

Print the full skill text to stdout.

sandy prime

Resources

• sandy://skills/cli/resources/scripting-guide.md
• sandy://skills/cli/resources/examples/ec2_describe.ts
• sandy://skills/cli/resources/examples/ecs_services.ts

sandy resource sandy://skills/cli/resources/scripting-guide.md
sandy resource sandy://skills/cli/resources/examples/ec2_describe.ts
sandy resource sandy://skills/cli/resources/examples/ecs_services.ts

Typical workflow

1. Read the scripting guide.
2. Start an IMDS server and note the port.
3. Run sandy image create if needed.
4. Run sandy session create and note the scripts path.
5. Write a script into that scripts directory.
6. Run sandy check connect --imds-port <port>.
7. Run sandy run --session <name> --script file.ts --imds-port <port>.
8. Read outputs from .sandy/<session>/output/ or stdout.

Operating protocols

These rules apply to every Sandy investigation, regardless of mode. Non-adherence defeats the tool.

Division of labour

• Sandy is the engine for data retrieval, collation, and mathematical analysis.
• The agent guides diagnosis, forms and tests hypotheses, and decides what to investigate next.
• Do not spend agent tokens wading through raw data. Reduce it in-sandbox with Sandy scripts, jq, or local tooling, then summarise.

Query strategy

• Prefer small, targeted queries. Escalate to wider scans only when a signal warrants depth.
• Constrain Describe* and List* calls by tag, region, identifier, or time window wherever the API allows.
• Write async-generator iterators for every paginated call. Do not accumulate whole result sets into arrays.

Data to disk, summary to stdout

• Full data artefacts are written to files under process.env.SANDY_OUTPUT.
• Stdout carries short summaries and the evidence that informs the next decision, not raw payloads.
• Record what each file means, either in per-file metadata or via evidence-ledger entries.

Evidence ledger

For each distinct data artefact relevant to the investigation, the script should call Evidence.append (exposed by the in-sandbox sandy module) so the ledger stays synchronised with the produced data. The append contract:

interface EvidenceEntry {
  id: string          // ULID generated inline
  timestamp: string   // ISO 8601
  hypotheses: string[]
  summary: string     // ≤ 20 words (guideline, not enforced)
  dataFile?: string   // path relative to SANDY_OUTPUT
}

hypotheses is a non-empty-compatible string array of hypothesis ids maintained by the agent in hypotheses.json under the session output directory. Dangling hypothesis ids are tolerated at write time and reconciled by the agent.

Companion MCPs

Two companion MCPs, when available, raise code-generation and AWS-claim correctness. Treat them as recommended-but-optional:

• Context7 — library and SDK documentation. Use it whenever you need current API shapes, version-specific behaviour, or code examples for any library (including @aws-sdk/*). Prefer it over recall from training data.
• AWS Knowledge Base MCP — https://knowledge-mcp.global.api.aws. Authoritative AWS service documentation: behaviour, limits, pricing, region availability. Prefer it over recall for any AWS-specific claim.

When either companion is absent, ground claims in sandbox-observable evidence. Do not assert API shapes or service behaviour from memory; record any such gap as a known-unknown.

Triage

On the first substantive research question of a session, classify the work into one of the research modes below, state the chosen mode, and load the matching resource at sandy://skills/research/modes/<mode>.md. When the user explicitly signals a mode change, reload the new mode's resource and announce the switch.

Modes

• Firefight — an incident or active failure. Classification cues: words like "down", "errors spiking", "failing", "broken"; stated customer impact; recent deploy correlation.
• Audit — discovery or inventory across existing resources. Classification cues: words like "how many", "which", "where is", "what owns"; cost or compliance framing; no stated failure.
• Architect — design of a new or changing capability. Classification cues: words like "should we", "trade-off", "alternatives", "design"; discussion of non-existent-yet systems.

If the question does not cleanly match any mode, default to Audit and note the ambiguity to the user.

Where a matching service resource exists under sandy://skills/research/services/<service>.md, load it when the service becomes relevant. Missing service resources are non-blocking; record the gap as a known-unknown in hypotheses.json or in-context notes.

Research mode resources

• sandy://skills/research/modes/firefight.md
• sandy://skills/research/modes/audit.md
• sandy://skills/research/modes/architect.md