Publish apps to S3 — iw app publish

InsightWorker apps are bundles — a folder with app.yaml, widget.json, workflow.yaml, plan.md, and (optionally) prompts/ and dictionaries/. iw app publish ships that bundle to a shared S3 bucket so other team members — or an InsightStudio marketplace — can discover and run it.

This is Tier S, the lightweight share path. No database, no service required. Just a bucket your team has read access to.

One-time bucket setup

Pick (or create) a private S3 bucket your team can read. Set one env var pointing at it — the CLI uses this for every publish, pull, and list.

export IW_APP_STORE=s3://your-bucket/optional/prefix
export AWS_REGION=us-east-1                  # or wherever your bucket lives

Credentials come from the standard AWS provider chain — SSO, EC2 instance role, IAM keys, or whatever you've configured. See AWS SSO for the recommended setup.

Publish a bundle

From the bundle's root directory (where app.yaml lives):

iw app publish
# or, for a specific bundle in another folder:
iw app publish ./apps/credit-triage

The publish flow:

1. Validates the bundle against the §15 spec (required files, slug shape, version is semver, widget JSON is parseable).
2. Reads app.yaml for slug and version.
3. Uploads every file under the bundle to s3://<bucket>/<prefix>apps/<slug>/v<version>/.
4. Writes a LATEST alias file at s3://<bucket>/<prefix>apps/<slug>/LATEST with the version number, so consumers can fetch the newest version without listing.

S3 layout reference

s3://<bucket>/<prefix>apps/
├── credit-triage/
│   ├── LATEST                 # plain text: "1.2.0"
│   ├── v1.0.0/
│   │   ├── app.yaml
│   │   ├── widget.json
│   │   ├── workflow.yaml
│   │   ├── plan.md
│   │   ├── manifest.yaml
│   │   ├── prompts/
│   │   └── dictionaries/
│   ├── v1.1.0/
│   └── v1.2.0/
└── broker-submission-intake/
    └── ...

Every version is immutable. Republishing the same version errors out unless you pass --force (don't).

Pull a teammate's app

To run an app someone else published:

iw app pull credit-triage                    # latest version
iw app pull credit-triage --version 1.1.0    # a specific version
iw app pull credit-triage --destination ./   # custom output dir

Files land in ./apps/<slug>/ by default. You can then run them with the standard widget runner:

cd apps/credit-triage
insightworker --ui

List versions

iw app versions credit-triage
# 1.2.0  (LATEST)
# 1.1.0
# 1.0.0

What gets uploaded vs what gets skipped

From CLI to Studio marketplace

If your team runs an InsightStudio instance, apps published this way appear in the Studio marketplace automatically — Studio reads the same S3 bucket on a 60-second cache TTL. No separate publish step. Your CLI authoring loop and Studio's browser-based runners stay in sync.

Related: Join a Studio worker farm · InsightStudio overview