Zopack

zopack

Package zo.space routes into a single shareable .zopack.md file that anyone can give to their Zo to deploy instantly.

Export

To export routes from the user's zo.space into a .zopack.md:

1. Ask the user which routes to export (or use "all"). List their current routes with list_space_routes.
2. Fetch each route's code using get_space_route(path).
3. Build a JSON array of route objects:

``json [ { "path": "/api/foo", "route_type": "api", "public": true, "code": "..." }, { "path": "/bar", "route_type": "page", "public": false, "code": "..." } ] ``

1. Pipe the JSON array to the export script:

``bash echo '' | bun /home/workspace/Skills/zopack/scripts/export.ts \ --name "pack-name" \ --description "What this does" \ --output "Inbox/pack-name.zopack.md" ``

1. The script outputs the file path. Show the user the generated file.

The export script automatically:

• Detects the user's handle and replaces it with {{HANDLE}}
• Identifies npm dependencies not in the base zo.space install
• Detects shadcn/AnimateUI component imports and maps to registry URLs
• Finds filesystem paths referenced in code (directories, JSON files)
• Identifies required environment variable secrets

Import

Warning: Always use --preview before importing packs from untrusted sources. A zopack can specify arbitrary npm packages, shadcn registry URLs, and route code that will run on your Zo.

To import a .zopack.md file and deploy its routes:

1. Parse the pack file to get the deployment plan:

``bash bun /home/workspace/Skills/zopack/scripts/import.ts \ --file "/path/to/pack.zopack.md" \ --handle "" \ --preview ` Use --preview` first to show the user what will be deployed.

1. Security scan: Before deploying, review the route code in the plan for risks:

• fetch() or http/https calls to external URLs (data exfiltration)
• process.env access beyond expected secrets (credential harvesting)
• eval(), Function(), or dynamic import() (arbitrary code execution)
• Encoded/obfuscated strings (atob, Buffer.from) hiding malicious payloads
• Filesystem access outside /home/workspace/ (path traversal)

If any suspicious patterns are found, flag them to the user and do not proceed without explicit approval.

1. If the user confirms, run without --preview to get the full JSON plan:

``bash bun /home/workspace/Skills/zopack/scripts/import.ts \ --file "/path/to/pack.zopack.md" \ --handle "" ``

1. Parse the JSON output and execute the deployment in order:

a. Install dependencies:

• npm packages: cd /__substrate/space && bun add for each
• shadcn components: cd /__substrate/space && npx shadcn@latest add --yes for each
• For shadcn: entries, use: npx shadcn@latest add --yes

b. Create filesystem structure:

• Directories: mkdir -p /home/workspace/ for each
• Files: write each file with the specified initial content

c. Check for secret requirements:

• If secrets are listed, warn the user to configure them in Settings > Advanced before the routes will work

d. Deploy routes:

• Use update_space_route(path, route_type, code, public) for each route in the plan
• Deploy API routes before page routes (pages may depend on APIs)

e. Verify:

• Run get_space_errors() to check for build/runtime errors
• Report success or any issues

Format Reference

The .zopack.md format:

---
format: zopack
version: "1.0"
name: pack-name
description: "What this does"
author: handle.zo.computer
routes: 3
exported: 2026-02-21
---

# pack-name

Description text.

## Routes

### `/path` (api|page, public|private)

\```typescript|tsx
// route code here
\```

## Dependencies

**npm packages** (not in default zo.space):
- `package-name`

**Components** (install via shadcn CLI):
- `https://animate-ui.com/r/component-name.json`
- `shadcn:component-name`

## Setup

**Directories to create:**
- `Data/my-dir`

**Files to initialize:**
- `Data/state.json` with content: `[]`

**Secrets required** (configure in Settings > Advanced):
- `API_KEY_NAME`

## Variables

| Placeholder | Description |
|---|---|
| `{{HANDLE}}` | Your zo.space handle |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zocomputer
• Source: zocomputer/skills
• License: MIT

Install and usage instructions live in the source repository linked above.