App Store

The App Store lets users discover, install, publish, and fork apps. Every published app gets a public URL that anyone can try without signing up.

Browsing the Store

Open the App Store from the dock or Cmd+K command palette. The store has three tabs:

• Apps -- productivity tools, utilities, creative apps
• Games -- playable games with leaderboards
• Skills -- AI skills that teach your agent new capabilities

Discovery

• Featured -- curated apps picked by the platform
• Popular -- sorted by installs in the last 7 days
• New -- recently published
• Categories -- game, productivity, utility, social, dev, creative
• Search -- full-text search across names, descriptions, and tags
• Top Rated -- sorted by user ratings (1-5 stars)

Installing Apps

Click "Install" on any app in the store. The app files download to ~/apps/{slug}/ and appear in your dock. Your data stays on your OS -- the publisher provides code, you provide storage.

Publishing Apps

Publish your app by saying "publish my app" in chat or clicking "Publish" in the app settings.

What Happens

1. The AI validates your app (checks matrix.json, runs it, looks for errors)
2. The AI generates a description, screenshots, and tags if you haven't provided them
3. Files upload to the platform registry
4. Your app gets a public URL: matrix-os.com/store/@handle/slug
5. The app appears in the store (automated validation, no manual review for sandboxed apps)

Publish Validation

• matrix.json must include name and description
• The app must start and pass a health check
• Source code is scanned for leaked secrets (API keys, tokens)
• Size limit: 50MB per app (configurable)
• Rate limit: 10 publishes per day

Publishing via IPC

The publish_app IPC tool is available to agents:

publish_app({ appName: "chess", description?: "...", tags?: ["game", "strategy"] })
-> { url: "matrix-os.com/store/@hamed/chess", slug: "chess", version: "1.0.0" }

Public App URLs

Every published app gets two public URLs:

Run Page Behavior

• Anonymous visitor: app runs in a temporary sandbox with no data persistence. Banner: "Sign up to save your progress."
• Logged-in user (not installed): app runs with data saved to the viewer's ~/data/{app}/
• Logged-in user (installed): redirects to their own instance

Forking Apps

Click "Fork" on any public app to get your own editable copy:

1. App files are copied to ~/apps/{slug}/
2. forked_from metadata is added to your local matrix.json
3. The app registers locally and appears in your dock
4. You can modify it freely -- it is just files
5. You can re-publish your fork (with attribution to the original author)

Fork graphs are tracked in the registry. "Forked from @alice/chess" appears on the store page.

The fork_app and install_app IPC tools are available to agents:

fork_app({ author: "alice", slug: "chess" })
install_app({ author: "alice", slug: "chess" })

Ratings and Reviews

After installing an app, you can rate it 1-5 stars. Ratings are averaged and displayed on the store page. Ratings drive the "Top Rated" sort order.

POST /api/store/apps/:id/rate
{ "rating": 5, "review": "Great chess AI!" }

Personal Websites

Every user gets a personal website at {handle}.matrix-os.com:

• Not logged in: shows your public profile page (name, avatar, bio, published apps)
• Logged in as owner: shows the full Matrix OS desktop
• Logged in as other user: shows the public profile

Profile Customization

The profile page is itself a Matrix OS app (~/apps/profile/). Customize it via chat:

Make my profile page dark and add my GitHub link

Pre-built profile themes are available: minimal, developer, creative, gamer.

Custom Domains

Point your own domain to Matrix OS:

1. Set custom_domain in your profile settings
2. Add a CNAME record pointing to matrix-os.com
3. The platform generates a TLS certificate automatically

Skills Store

Skills are publishable and installable alongside apps:

Browse skills in the "Skills" tab of the App Store. Each skill shows name, description, author, and install count. One-click install.

Store API Reference